Create a video task

POST/v1/video/generations

Submit a prompt with optional images, videos or audio to create an asynchronous generation task; the task ID and the reserved amount come back at once.

View Markdown

Put your API key after Authorization: Bearer in the request header.
Send an Idempotency-Key: when the outcome is unknown, retry with the same key and body to create one task and be charged once.
Generation runs in the background: poll Retrieve a video task or receive task.completed at your callback_url.
Funds are reserved for the upper bound at creation and settled on actual usage; failed and cancelled tasks are free.

Headers

#AuthorizationstringRequired

Bearer, a space and your API key. A missing or invalid key returns 401 authentication_failed.

#Content-TypestringRequired

The body is JSON: application/json.

#X-Request-IDstring

Your own request identifier. An invalid or repeated value is replaced; the value used comes back in the X-Request-ID response header.

#Idempotency-KeystringRequired

Generate a new value for every new request and save it; it starts with a letter or digit. When the outcome is unknown, retry with the same key and the original body to get the original response; the same key with a different body returns 409 idempotency_conflict. Keys belong to your team, not to one API key.

Length8–128CharactersA–Z a–z 0–9 . _ : -

Request bodyapplication/json · Required

The body accepts only the fields below; any other field is rejected.

#modelstringRequired

ID of the model used for this request.

dreamina-seedance-2-0-260128Seedance 2.0

dreamina-seedance-2-0-fast-260128Seedance 2.0 Fast

dreamina-seedance-2-0-mini-260615Seedance 2.0 Mini

#contentarrayRequired

Platform limits: 9 images, 3 videos and 3 audio items, 15 materials and 16 content items. Each video or audio clip lasts 2 to 15 seconds; video and audio totals are each at most 15 seconds. The platform downloads, scans, stores and reviews HTTPS inputs before generation. Preparation failure releases the whole reservation at zero charge. Known preparation failures include their content_index.

Items1–16

Each item matches exactly one of these shapes.

#typestringRequired

Identifies the kind of input item.

Alwaystext

#textstringRequired

Prompt describing the video to generate.

Length1–10000

#typestringRequired

Identifies the kind of input item.

Alwaysimage_url

#rolestring

How the asset is used in the input or result.

reference_imageReference image

first_frameFirst frame

last_frameLast frame

#image_urlobjectRequired

An HTTPS image source, an asset:// platform asset reference, or a JPEG/PNG/WebP base64 data URI. HTTPS and inline inputs may be combined; neither can be mixed with asset:// references.

Exactly one of these shapes applies.

#urlstringRequired

Public HTTPS URL with no userinfo, literal IP, local or platform hostname. Port must be omitted or 443; at most 2048 UTF-8 bytes.

Length1–2048Formathttps://

#urlstringRequired

Use asset:// and the ID of an active asset owned by your team. Do not put its original HTTPS source address here.

Length12–128Formatasset://ast-…

#urlstringRequired

JPEG, PNG or WebP data URI with base64 encoding. The decoded image must be smaller than 30 MB and pass image header checks.

Length≤ 40000023Formatdata:image/…;base64,…

#typestringRequired

Identifies the kind of input item.

Alwaysvideo_url

#rolestringRequired

How the asset is used in the input or result.

Alwaysreference_video

#video_urlobjectRequired

An HTTPS video source or an asset:// platform video reference. Use one origin throughout the request.

Exactly one of these shapes applies.

#urlstringRequired

Public HTTPS URL with no userinfo, literal IP, local or platform hostname. Port must be omitted or 443; at most 2048 UTF-8 bytes.

Length1–2048Formathttps://

#urlstringRequired

Use asset:// and the ID of an active asset owned by your team. Do not put its original HTTPS source address here.

Length12–128Formatasset://ast-…

#typestringRequired

Identifies the kind of input item.

Alwaysaudio_url

#rolestringRequired

How the asset is used in the input or result.

Alwaysreference_audio

#audio_urlobjectRequired

An HTTPS audio source, an asset:// platform audio reference, or a WAV/MP3 base64 data URI (wav, x-wav, mpeg and mp3 aliases). HTTPS and inline inputs may be combined; neither can be mixed with asset:// references.

Exactly one of these shapes applies.

#urlstringRequired

Public HTTPS URL with no userinfo, literal IP, local or platform hostname. Port must be omitted or 443; at most 2048 UTF-8 bytes.

Length1–2048Formathttps://

#urlstringRequired

Use asset:// and the ID of an active asset owned by your team. Do not put its original HTTPS source address here.

Length12–128Formatasset://ast-…

#urlstringRequired

WAV or MP3 data URI with base64 encoding, up to 15 MB and 2 to 15 seconds. The audio/x-wav and audio/mp3 aliases are accepted.

Length≤ 20000024Formatdata:audio/…;base64,…

#resolutionstring

Output resolution. Seedance 2.0 Fast and Mini accept only 480p or 720p.

Default720pOne of480p720p1080p

#ratiostring

Aspect ratio of the output image.

DefaultadaptiveOne ofadaptive21:916:94:31:13:49:16

#durationinteger

Output duration in whole seconds from 4 to 15; the default is 5.

Default5Range4–15

#generate_audioboolean

Whether to generate audio with the video.

Defaultfalse

#seedinteger

Random seed; the default -1 means random.

Range-1–4294967295Default-1

#watermarkboolean

Whether to add a watermark to the output.

Defaultfalse

#callback_urlstring

The address that receives the callback when the task ends. It must match, byte for byte, a callback address of your team that is verified in the console, not removed and not expired; otherwise 400 callback_target_not_verified. A retry with the same Idempotency-Key cannot add, drop or change it; that returns 409 idempotency_conflict.

Length1–2048Formathttps://

Parameters not supported yet7

return_last_frame

Setting it to true returns 400 unsupported_capability.

draftoutput_formatomni_reference_task_typeexecution_expires_afterprioritysafety_identifier

The current models do not take these; sending one returns 400 invalid_request.

Request

IDEMPOTENCY_KEY=${IDEMPOTENCY_KEY:-$(uuidgen)}
printf '%s\n' "Save IDEMPOTENCY_KEY for retries: ${IDEMPOTENCY_KEY}" >&2
curl --request POST "${CHENVOYA_BASE_URL}/v1/video/generations" \
  --header "Authorization: Bearer ${CHENVOYA_API_KEY}" \
  --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "dreamina-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "A paper boat crossing a moonlit lake."
    }
  ]
}'

import urllib.request
import urllib.parse
import json
import os
import sys
import re
import uuid

key = os.environ["CHENVOYA_API_KEY"].strip()
if not key or re.search(r"[\x00-\x1f\x7f-\x9f]", key):
    sys.exit("Set CHENVOYA_API_KEY to a non-empty value without control characters")
base = os.environ["CHENVOYA_BASE_URL"].rstrip("/")
headers = {"Authorization": "Bearer " + key}
idempotency = os.environ.get("IDEMPOTENCY_KEY") or str(uuid.uuid4())
print("Save IDEMPOTENCY_KEY for retries: " + idempotency, file=sys.stderr)
headers["Idempotency-Key"] = idempotency
path = "/v1/video/generations"
body_text = "{\"model\":\"dreamina-seedance-2-0-260128\",\"content\":[{\"type\":\"text\",\"text\":\"A paper boat crossing a moonlit lake.\"}]}"
headers["Content-Type"] = "application/json"
body = json.dumps(json.loads(body_text)).encode("utf-8")
request = urllib.request.Request(base + path, data=body, headers=headers, method="POST")
try:
    with urllib.request.urlopen(request) as response:
        print(response.read().decode("utf-8"))
except urllib.request.HTTPError as error:
    print(error.read().decode("utf-8"))
    sys.exit(1)

// Needs Node.js 20 or later; save it as a .mjs file and run it.
const key = process.env.CHENVOYA_API_KEY?.trim();
if (!key || /[\x00-\x1f\x7f-\x9f]/.test(key)) {
  console.error("Set CHENVOYA_API_KEY to a non-empty value without control characters");
  process.exit(1);
}
const base = process.env.CHENVOYA_BASE_URL;
if (!base) throw new Error("Set CHENVOYA_BASE_URL");
const headers = {Authorization: `Bearer ${key}`};
const idempotency = process.env.IDEMPOTENCY_KEY || crypto.randomUUID();
console.error("Save IDEMPOTENCY_KEY for retries: " + idempotency);
headers["Idempotency-Key"] = idempotency;
const path = "/v1/video/generations";
let bodyText = "{\"model\":\"dreamina-seedance-2-0-260128\",\"content\":[{\"type\":\"text\",\"text\":\"A paper boat crossing a moonlit lake.\"}]}";
headers["Content-Type"] = "application/json";
const body = JSON.stringify(JSON.parse(bodyText));
const response = await fetch(base.replace(/\/$/, "") + path, {method: "POST", headers, body: body});
console.log(await response.text());
if (!response.ok) process.exitCode = 1;

package main

import (
	"crypto/rand"
	"fmt"
	"io"
	"net/http"
	"os"
	"regexp"
	"strings"
)

func main() {
	key := strings.TrimSpace(os.Getenv("CHENVOYA_API_KEY"))
	if key == "" || regexp.MustCompile(`[\x00-\x1f\x7f-\x9f]`).MatchString(key) {
		fail("Set CHENVOYA_API_KEY to a non-empty value without control characters")
	}
	base := strings.TrimRight(os.Getenv("CHENVOYA_BASE_URL"), "/")
	if base == "" {
		fail("Set CHENVOYA_BASE_URL")
	}
	path := "/v1/video/generations"
	bodyText := "{\"model\":\"dreamina-seedance-2-0-260128\",\"content\":[{\"type\":\"text\",\"text\":\"A paper boat crossing a moonlit lake.\"}]}"
	request, err := http.NewRequest("POST", base+path, strings.NewReader(bodyText))
	if err != nil {
		fail(err.Error())
	}
	request.Header.Set("Authorization", "Bearer "+key)
	request.Header.Set("Content-Type", "application/json")
	idempotency := os.Getenv("IDEMPOTENCY_KEY")
	if idempotency == "" {
		idempotency = newOperationKey()
	}
	fmt.Fprintln(os.Stderr, "Save IDEMPOTENCY_KEY for retries: "+idempotency)
	request.Header.Set("Idempotency-Key", idempotency)
	response, err := http.DefaultClient.Do(request)
	if err != nil {
		fail(err.Error())
	}
	text, err := io.ReadAll(response.Body)
	response.Body.Close()
	if err != nil {
		fail(err.Error())
	}
	fmt.Println(string(text))
	if response.StatusCode < 200 || response.StatusCode > 299 {
		os.Exit(1)
	}
}

func fail(message string) {
	fmt.Fprintln(os.Stderr, message)
	os.Exit(1)
}

// newOperationKey returns a random UUID; save it to retry with the same value.
func newOperationKey() string {
	var b [16]byte
	if _, err := rand.Read(b[:]); err != nil {
		fail(err.Error())
	}
	b[6] = b[6]&0x0f | 0x40
	b[8] = b[8]&0x3f | 0x80
	return fmt.Sprintf("%x-%x-%x-%x-%x", b[0:4], b[4:6], b[6:8], b[8:10], b[10:16])
}

IDEMPOTENCY_KEY=${IDEMPOTENCY_KEY:-$(uuidgen)}
printf '%s\n' "Save IDEMPOTENCY_KEY for retries: ${IDEMPOTENCY_KEY}" >&2
ASSET_ID_PATTERN='^ast-[0-9a-f]{32}$'
if [[ ! ${ASSET_ID} =~ ${ASSET_ID_PATTERN} || ${ASSET_ID} == *[!A-Za-z0-9._-]* ]]; then
  printf '%s\n' 'Set ASSET_ID to the ID from the creation response first.' >&2
  exit 1
fi
curl --request POST "${CHENVOYA_BASE_URL}/v1/video/generations" \
  --header "Authorization: Bearer ${CHENVOYA_API_KEY}" \
  --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "dreamina-seedance-2-0-260128",
  "duration": 5,
  "ratio": "16:9",
  "resolution": "720p",
  "content": [
    {
      "type": "text",
      "text": "Animate the reviewed reference image."
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "asset://'"${ASSET_ID}"'"
      }
    }
  ]
}'

import urllib.request
import urllib.parse
import json
import os
import sys
import re
import uuid

key = os.environ["CHENVOYA_API_KEY"].strip()
if not key or re.search(r"[\x00-\x1f\x7f-\x9f]", key):
    sys.exit("Set CHENVOYA_API_KEY to a non-empty value without control characters")
base = os.environ["CHENVOYA_BASE_URL"].rstrip("/")
headers = {"Authorization": "Bearer " + key}
idempotency = os.environ.get("IDEMPOTENCY_KEY") or str(uuid.uuid4())
print("Save IDEMPOTENCY_KEY for retries: " + idempotency, file=sys.stderr)
headers["Idempotency-Key"] = idempotency
path = "/v1/video/generations"
body_text = "{\"model\":\"dreamina-seedance-2-0-260128\",\"duration\":5,\"ratio\":\"16:9\",\"resolution\":\"720p\",\"content\":[{\"type\":\"text\",\"text\":\"Animate the reviewed reference image.\"},{\"type\":\"image_url\",\"role\":\"reference_image\",\"image_url\":{\"url\":\"asset://ast-bca04b1132034b9b42cb51fe29e9a0a7\"}}]}"
ASSET_ID = os.environ["ASSET_ID"]
if not re.fullmatch("^ast-[0-9a-f]{32}$", ASSET_ID):
    sys.exit("Set ASSET_ID to the ID from the creation response")
body_text = body_text.replace("\"asset://ast-bca04b1132034b9b42cb51fe29e9a0a7\"", json.dumps("asset://" + ASSET_ID))
headers["Content-Type"] = "application/json"
body = json.dumps(json.loads(body_text)).encode("utf-8")
request = urllib.request.Request(base + path, data=body, headers=headers, method="POST")
try:
    with urllib.request.urlopen(request) as response:
        print(response.read().decode("utf-8"))
except urllib.request.HTTPError as error:
    print(error.read().decode("utf-8"))
    sys.exit(1)

// Needs Node.js 20 or later; save it as a .mjs file and run it.
const key = process.env.CHENVOYA_API_KEY?.trim();
if (!key || /[\x00-\x1f\x7f-\x9f]/.test(key)) {
  console.error("Set CHENVOYA_API_KEY to a non-empty value without control characters");
  process.exit(1);
}
const base = process.env.CHENVOYA_BASE_URL;
if (!base) throw new Error("Set CHENVOYA_BASE_URL");
const headers = {Authorization: `Bearer ${key}`};
const idempotency = process.env.IDEMPOTENCY_KEY || crypto.randomUUID();
console.error("Save IDEMPOTENCY_KEY for retries: " + idempotency);
headers["Idempotency-Key"] = idempotency;
const path = "/v1/video/generations";
let bodyText = "{\"model\":\"dreamina-seedance-2-0-260128\",\"duration\":5,\"ratio\":\"16:9\",\"resolution\":\"720p\",\"content\":[{\"type\":\"text\",\"text\":\"Animate the reviewed reference image.\"},{\"type\":\"image_url\",\"role\":\"reference_image\",\"image_url\":{\"url\":\"asset://ast-bca04b1132034b9b42cb51fe29e9a0a7\"}}]}";
const ASSET_ID = process.env.ASSET_ID;
if (typeof ASSET_ID !== "string" || (new RegExp("^ast-[0-9a-f]{32}$")).exec(ASSET_ID)?.[0] !== ASSET_ID) throw new Error("Set ASSET_ID to the ID from the creation response");
bodyText = bodyText.replaceAll("\"asset://ast-bca04b1132034b9b42cb51fe29e9a0a7\"", JSON.stringify("asset://" + ASSET_ID));
headers["Content-Type"] = "application/json";
const body = JSON.stringify(JSON.parse(bodyText));
const response = await fetch(base.replace(/\/$/, "") + path, {method: "POST", headers, body: body});
console.log(await response.text());
if (!response.ok) process.exitCode = 1;

package main

import (
	"crypto/rand"
	"fmt"
	"io"
	"net/http"
	"os"
	"regexp"
	"strconv"
	"strings"
)

func main() {
	key := strings.TrimSpace(os.Getenv("CHENVOYA_API_KEY"))
	if key == "" || regexp.MustCompile(`[\x00-\x1f\x7f-\x9f]`).MatchString(key) {
		fail("Set CHENVOYA_API_KEY to a non-empty value without control characters")
	}
	base := strings.TrimRight(os.Getenv("CHENVOYA_BASE_URL"), "/")
	if base == "" {
		fail("Set CHENVOYA_BASE_URL")
	}
	path := "/v1/video/generations"
	bodyText := "{\"model\":\"dreamina-seedance-2-0-260128\",\"duration\":5,\"ratio\":\"16:9\",\"resolution\":\"720p\",\"content\":[{\"type\":\"text\",\"text\":\"Animate the reviewed reference image.\"},{\"type\":\"image_url\",\"role\":\"reference_image\",\"image_url\":{\"url\":\"asset://ast-bca04b1132034b9b42cb51fe29e9a0a7\"}}]}"
	assetID := os.Getenv("ASSET_ID")
	if !regexp.MustCompile(`\A(?:ast-[0-9a-f]{32})\z`).MatchString(assetID) {
		fail("Set ASSET_ID to the ID from the creation response")
	}
	bodyText = strings.ReplaceAll(bodyText, "\"asset://ast-bca04b1132034b9b42cb51fe29e9a0a7\"", strconv.Quote("asset://"+assetID))
	request, err := http.NewRequest("POST", base+path, strings.NewReader(bodyText))
	if err != nil {
		fail(err.Error())
	}
	request.Header.Set("Authorization", "Bearer "+key)
	request.Header.Set("Content-Type", "application/json")
	idempotency := os.Getenv("IDEMPOTENCY_KEY")
	if idempotency == "" {
		idempotency = newOperationKey()
	}
	fmt.Fprintln(os.Stderr, "Save IDEMPOTENCY_KEY for retries: "+idempotency)
	request.Header.Set("Idempotency-Key", idempotency)
	response, err := http.DefaultClient.Do(request)
	if err != nil {
		fail(err.Error())
	}
	text, err := io.ReadAll(response.Body)
	response.Body.Close()
	if err != nil {
		fail(err.Error())
	}
	fmt.Println(string(text))
	if response.StatusCode < 200 || response.StatusCode > 299 {
		os.Exit(1)
	}
}

func fail(message string) {
	fmt.Fprintln(os.Stderr, message)
	os.Exit(1)
}

// newOperationKey returns a random UUID; save it to retry with the same value.
func newOperationKey() string {
	var b [16]byte
	if _, err := rand.Read(b[:]); err != nil {
		fail(err.Error())
	}
	b[6] = b[6]&0x0f | 0x40
	b[8] = b[8]&0x3f | 0x80
	return fmt.Sprintf("%x-%x-%x-%x-%x", b[0:4], b[4:6], b[6:8], b[8:10], b[10:16])
}

ReturnsHTTP 202

Accepted: the task is created and the funds are reserved. The Location response header is the task's lookup path.

#idstringRequired

Task ID assigned by the platform.

Length4–128CharactersA–Z a–z 0–9 _ -

#objectstringRequired

Identifies the kind of object returned.

Alwaysvideo.task

#request_idstringRequired

Request ID used to correlate this task.

Length4–128CharactersA–Z a–z 0–9 _ -

#billing_correlation_idstringRequired

Billing correlation ID for this task.

Length4–128CharactersA–Z a–z 0–9 _ -

#modelstringRequired

ID of the model used for this request.

dreamina-seedance-2-0-260128Seedance 2.0

dreamina-seedance-2-0-fast-260128Seedance 2.0 Fast

dreamina-seedance-2-0-mini-260615Seedance 2.0 Mini

#statusstringRequired

Current state; see the value notes for its meaning.

Alwaysqueued

#phasestring

The inputs are being prepared before generation starts.

Alwayspreparing_assets

#settlement_statusstringRequired

Current progress of billing settlement.

Alwaysreserved

#quoteobjectRequired

Reservation quote recorded when the task is accepted.

6 child fields

#currencystringRequired

Currency of the amounts: USD.

AlwaysUSD

#reserved_amountstringRequired

Amount that must be reserved to accept the task.

Format6 decimal places

#meter_typestringRequired

The meter used to record usage.

Alwaysseedance_video_generation

#estimated_usage_upper_boundobjectRequired

Upper estimate of usage for the reservation.

1 child fields

#video_tokensintegerRequired

Number of video tokens. The field type determines whether an actual usage value may be null.

Range≥ 1

#price_versionstringRequired

Version of pricing applied to this quote.

Length4–128CharactersA–Z a–z 0–9 _ -

#quote_policy_versionstringRequired

Version of the policy used to calculate the reservation quote.

Length1–128CharactersA–Z a–z 0–9 . _ : -

#created_atintegerRequired

Creation time as whole seconds since the Unix epoch.

Range≥ 0

Response headers

#X-Request-IDstringRequired

The identifier of this request: the valid value you sent, or its replacement.

#LocationstringRequired

Canonical relative lookup path for the accepted object.

Response

{
  "id": "task_32ae2a5177b310d3bc1ec83a98f63889",
  "object": "video.task",
  "request_id": "req_6acd96894df9798feb0ddb21e5a52d70",
  "billing_correlation_id": "billcorr_2f6c57065a4404b27fb9b6b24ea9a0d0",
  "model": "dreamina-seedance-2-0-260128",
  "status": "queued",
  "settlement_status": "reserved",
  "quote": {
    "currency": "USD",
    "reserved_amount": "0.782453",
    "meter_type": "seedance_video_generation",
    "estimated_usage_upper_bound": {
      "video_tokens": 111779
    },
    "price_version": "price_06c9ad4cf0af577624218747c25fdb37",
    "quote_policy_version": "seedance2_quote_v1"
  },
  "created_at": 1793167380
}

{
  "error": {
    "code": "invalid_request",
    "message": "request parameters are invalid"
  },
  "trace_id": "trace_error_example"
}

{
  "error": {
    "code": "idempotency_conflict",
    "message": "the idempotency key was used with a different canonical request"
  },
  "trace_id": "trace_error_example"
}

{
  "error": {
    "code": "insufficient_balance",
    "message": "available USD balance is below the required reservation",
    "details": {
      "currency": "USD",
      "reserved_amount": "0.782453",
      "meter_type": "seedance_video_generation",
      "estimated_usage_upper_bound": {
        "video_tokens": 111779
      },
      "price_version": "price_06c9ad4cf0af577624218747c25fdb37"
    }
  },
  "trace_id": "trace_error_example"
}

Status codes

Each error.code and what to do about it is on Error codes.

Status	Meaning and error.code
202	Accepted: the task is created and the funds are reserved. Response headers`Location`
400	The format or parameters are wrong, or a referenced asset or callback address cannot be used. asset_not_found asset_unusable callback_target_not_verified input_video_duration_exceeded invalid_request unsupported_capability
401	The API key is missing or invalid. Response headers`WWW-Authenticate` authentication_failed
409	The idempotency key conflicts or its replay has expired, the API key is not ready, or an asset is still processing. asset_not_ready idempotency_conflict idempotency_replay_expired key_provisioning_incomplete
429	The balance is too low, requests come too fast, or asset storage is full. Response headers`Retry-After` asset_storage_quota_exceeded insufficient_balance rate_limited
500	Internal error. internal_error
503	The service is temporarily unavailable, or new tasks are paused. dependency_unavailable funding_intake_closed

Quickstart Generate a video Idempotency and retries Handle errors

Create a video task

Headers

Request bodyapplication/json · Required

ReturnsHTTP 202

Response headers

Status codes

Related guides