Video Generation (Seedance)

This guide explains how to call the unified video generation API for Seedance models (e.g. doubao-seedance-2.0).

API Overview

Create a video generation task

• POST /v1/videos/generations
• Alias: POST /v1/video/generations

Query a video generation task

• GET /v1/videos/generations/{task_id}
• Alias: GET /v1/video/generations/{task_id}

Authentication

Pass your API key in the Authorization header:

Authorization: Bearer sk-xxxxxx

Create a task

Request headers

Content-Type: application/json
Accept: application/json
Authorization: Bearer sk-xxxxxx

Request body

{
  "model": "doubao-seedance-2.0",
  "prompt": "A cat running on the beach, cinematic, sunset, 4k",
  "mode": "pro",
  "input_type": "text_to_video",
  "images": [],
  "videos": [],
  "audios": [],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "metadata": {
    "draft": false,
    "generate_audio": false,
    "watermark": false
  }
}

Success response example

{
  "id": "task_65RmeonGhUJrizaVkQzAauwIXdOA1YFg",
  "task_id": "task_65RmeonGhUJrizaVkQzAauwIXdOA1YFg",
  "object": "video.generation.task",
  "status": "submitted",
  "message": "task submitted"
}

Notes:

• The create endpoint only confirms that the task was submitted.
• Most async video tasks do not return the final video immediately upon creation.
• Use the query endpoint to retrieve the final result.

Query a task

Request example

curl --request GET \
  --url 'https://bigbangtoken.com/v1/videos/generations/task_65RmeonGhUJrizaVkQzAauwIXdOA1YFg' \
  --header 'Authorization: Bearer sk-xxxxxx' \
  --header 'Accept: application/json'

Success response example

{
  "id": "task_65RmeonGhUJrizaVkQzAauwIXdOA1YFg",
  "task_id": "task_65RmeonGhUJrizaVkQzAauwIXdOA1YFg",
  "object": "video.generation.task",
  "status": "succeeded",
  "message": "task completed",
  "trace_id": "trace_xxx",
  "data": [
    {
      "url": "https://example.com/output.mp4"
    }
  ],
  "video_url": "https://example.com/output.mp4",
  "duration": 5,
  "usage": {
    "completion_tokens": 108000,
    "total_tokens": 108000
  }
}

Failure response example

{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "video.generation.task",
  "status": "failed",
  "message": "task failed",
  "error": {
    "message": "provider returned an error",
    "code": "provider_error"
  }
}

Request parameters

Top-level fields

Field	Type	Required	Description
model	string	Yes	Model name, e.g. doubao-seedance-2.0
prompt	string	Yes	Text prompt
mode	string	No	Generation mode, e.g. pro, fast. Effectiveness depends on model and upstream
input_type	string	No	Input type, e.g. text_to_video, first_last_frame, reference
image	string	No	Single-image compatibility field. The server maps it to images[0]
images	string[]	No	Array of image input URLs
videos	string[]	No	Array of video input URLs
audios	string[]	No	Array of audio input URLs
resolution	string	No	Output resolution, e.g. 480p, 720p, 1080p
ratio	string	No	Aspect ratio, e.g. 16:9, 9:16, 1:1
size	string	No	Compatibility field for explicit dimensions, e.g. 1280x720
duration	number / string	No	Output duration in seconds. Prefer integers, e.g. 5
seconds	string	No	Compatibility field with the same meaning as duration
metadata	object / string	No	Upstream extension parameters. Object or JSON string

Common metadata fields

metadata passes through additional upstream parameters. Supported fields vary by provider:

Field	Type	Description
draft	boolean	Enable draft/preview mode
generate_audio	boolean	Generate synchronized audio
watermark	boolean	Add watermark
return_last_frame	boolean	Return the last frame
callback_url	string	Callback URL when the task completes
seed	number	Random seed
execution_expires_after	number	Task timeout in seconds
safety_identifier	string	End-user unique identifier
tools	object / array	Tool configuration defined by upstream

Notes:

• Fields in metadata not explicitly consumed by the platform are passed through to upstream when possible.
• Some fields may be ignored or rejected if the current channel or model does not support them.

Input types

1. Text-to-video

Best for generating video from text only.

{
  "model": "doubao-seedance-2.0",
  "prompt": "A cat running on the beach, cinematic, sunset, 4k",
  "input_type": "text_to_video",
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}

2. First and last frame

Provide start and end frame images; the model generates the motion in between.

{
  "model": "doubao-seedance-2.0",
  "prompt": "Smooth camera push-in, character turns from stillness",
  "input_type": "first_last_frame",
  "images": [
    "https://example.com/frame-start.png",
    "https://example.com/frame-end.png"
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}

Notes:

• first_last_frame typically requires at least 2 images in images.
• Exact limits depend on the model and upstream.

3. Reference image

Use one or more reference images to control subject, style, or composition.

{
  "model": "doubao-seedance-2.0",
  "prompt": "Keep the character consistent, orbiting camera, cinematic",
  "input_type": "reference",
  "images": [
    "https://example.com/reference-1.jpg"
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}

4. Reference video

Regenerate, extend, or restyle based on an existing video.

{
  "model": "doubao-seedance-2.0",
  "prompt": "Keep the subject motion, change the overall mood to cyberpunk",
  "input_type": "reference",
  "videos": [
    "https://example.com/reference.mp4"
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}

Notes:

• Video input support depends on the model and channel.
• Video input usually affects final billing.

5. Reference audio

Tasks that include audio input.

{
  "model": "doubao-seedance-1.5-pro",
  "prompt": "Character moves to the music rhythm, steady camera push",
  "input_type": "reference",
  "audios": [
    "https://example.com/reference.wav"
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "metadata": {
    "generate_audio": true
  }
}

Field compatibility

image vs images

• Prefer images
• For a single image, image is also accepted
• The server treats image as images[0]

duration vs seconds

• Prefer duration
• seconds is kept for legacy clients
• If both are sent, server parsing takes precedence — avoid sending both

metadata

• Object form:

"metadata": {
  "draft": true,
  "watermark": false
}

• JSON string form:

"metadata": "{\"draft\":true,\"watermark\":false}"

Task status

The API returns one of these statuses:

Status	Description
pending	Created, waiting for submission or upstream confirmation
submitted	Submitted to upstream
running	Generation in progress
succeeded	Completed successfully
failed	Generation failed

Response fields

Create task response

Field	Type	Description
id	string	Public task ID
task_id	string	Same as id (compatibility field)
object	string	Always video.generation.task
status	string	Current task status
message	string	Status message

Query task response

Field	Type	Description
id	string	Public task ID
task_id	string	Same as id
object	string	Always video.generation.task
status	string	Current task status
message	string	Status message
trace_id	string	Upstream trace ID, may be empty
data	array	Video results; usually at least one object on success
data[].url	string	Generated video URL
video_url	string	Primary video URL, usually same as data[0].url
duration	number	Output video duration
usage.completion_tokens	number	Actual tokens consumed (from upstream)
usage.total_tokens	number	Total tokens (from upstream)
error.message	string	Failure reason
error.code	string	Failure code

Billing

For async video tasks:

1. A pre-deduction may occur when the task is submitted.
2. After completion, final cost is settled using usage.completion_tokens from the query result.
3. If the final charge is lower than the pre-deduction, the difference is refunded.
4. If the final charge is higher, an additional charge is applied.

Recommended distinctions in your application:

• Create success: task accepted
• Query success with status = succeeded: generation succeeded
• usage.completion_tokens present in query result: final billing amount is available

Error responses

Unified error format:

{
  "error": {
    "message": "task_id is required",
    "type": "invalid_request_error",
    "param": "",
    "code": ""
  }
}

Common error scenarios:

Scenario	Description
401 Unauthorized	Invalid or missing API key
403 Forbidden	Token lacks permission for this model or channel
400 Invalid Request	Missing/invalid parameters or unsupported model combination
404 Not Found	task_id does not exist or does not belong to the current user
500 Internal Server Error	Server or upstream error

Best practices

1. Create, then poll

Recommended flow:

1. Call the create endpoint to get task_id
2. Poll the query endpoint every 2–5 seconds
3. Stop when status is succeeded or failed

2. Use public URLs for media

Provide publicly accessible URLs for images, videos, and audio, for example:

• https://example.com/input.jpg
• https://example.com/input.mp4
• https://example.com/input.wav

3. Do not mix compatibility fields

For example:

• Do not send both image and images
• Do not send both duration and seconds

4. Validate against model capabilities

Model support varies for:

• Image input
• Video input
• Audio input
• 1080p resolution
• Draft mode
• Synchronized audio

Validate parameter combinations in your application to avoid invalid requests.

cURL examples

Text-to-video

curl --request POST \
  --url 'https://bigbangtoken.com/v1/videos/generations' \
  --header 'Authorization: Bearer sk-xxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "doubao-seedance-2.0",
    "prompt": "A cat running on the beach, cinematic, sunset, 4k",
    "input_type": "text_to_video",
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "metadata": {
      "draft": false,
      "generate_audio": false,
      "watermark": false
    }
  }'

Reference image video

curl --request POST \
  --url 'https://bigbangtoken.com/v1/videos/generations' \
  --header 'Authorization: Bearer sk-xxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "doubao-seedance-2.0",
    "prompt": "Keep the character consistent, orbiting camera, cinematic",
    "input_type": "reference",
    "images": [
      "https://example.com/reference-1.jpg"
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5
  }'

Query task

curl --request GET \
  --url 'https://bigbangtoken.com/v1/videos/generations/task_65RmeonGhUJrizaVkQzAauwIXdOA1YFg' \
  --header 'Authorization: Bearer sk-xxxxxx'