Seedance Official-Consistent Access (Video Generation)

API-RUN provides Seedance 2.0 / 2.5 series video generation: the API is identical to the official Volcano Ark documentation — request payload, paths, task IDs (native cgt- IDs), official Model IDs, and official list-price billing are all the same source. Write against the official docs and only change the base URL and key to integrate. One interface protocol serves all resource lines; switching lines only requires switching tokens, with zero code changes.

The asset library and face verification are documented separately: Seedance Assets / Face Verification.

Endpoints

Two entries with identical auth and capabilities — pick by payload preference:

Option 1: Native v3 API (recommended)

Paths identical to the official Volcano Ark documentation — write per the official docs and only change the base URL and key:

Create task: POST $URL/api/v3/contents/generations/tasks
Query task: GET $URL/api/v3/contents/generations/tasks/{task_id}
Task list: GET $URL/api/v3/contents/generations/tasks
Cancel task: DELETE $URL/api/v3/contents/generations/tasks/{task_id}

/v3/video/tasks (including /{task_id}, list, cancel) is an equivalent path that also works — both share the same protocol. Missing tasks uniformly return 404 (error.code=task_not_exist).

Option 2: OpenAI-compatible API

Create task: POST $URL/v1/videos
Query task: GET $URL/v1/videos/{task_id}

OpenAI Video style responses (details in "OpenAI-compatible entry" below).

The task paths are identical to the Volcano Ark official documentation; /v3/video/tasks (including /{task_id}, list, cancel) is an equivalent path that also works. Missing tasks uniformly return 404 (error.code=task_not_exist).

Task endpoints use Bearer auth:

http

Authorization: Bearer $YOUR_API_KEY

Supported models (official Model IDs)

API-RUN uniformly uses the vendors' official Model IDs (international release names), with identical payload protocols.

Model	Positioning	Resolution	Duration
`dreamina-seedance-2-5-260628`	2.5 flagship, best quality & consistency	480p / 720p / 1080p	4–30 s
`dreamina-seedance-2-0-260128`	2.0 standard	480p–4k	4–15 s
`dreamina-seedance-2-0-fast-260128`	2.0 fast	480p / 720p	4–15 s
`dreamina-seedance-2-0-mini-260615`	2.0 mini, best value	480p / 720p	4–15 s

duration also supports -1 (smart duration, decided by the model). fast/mini do not support 1080p or 4k; 2.5 has a separate 1080p price tier (see billing). Model/parameter availability per line is subject to the console.

All lines bill on the official token basis, settled by actual usage after task completion (refund/charge the difference).

Billing

Billing is on the official token basis: tokens = (input video duration + output duration) × output resolution pixels × frame rate / 1024. Estimated pre-charge at submission, settled by actual token usage on completion (refund/charge the difference). Tasks with video reference use the "with video reference" tier.

USD / M tokens:

Model	With video reference	Without video reference
`dreamina-seedance-2-5-260628`	6.4 (1080p 7.0)	10.7 (1080p 11.7)
`dreamina-seedance-2-0-260128`	4.3 (1080p 4.7, 4k 2.4)	7.0 (1080p 7.7, 4k 4.0)
`dreamina-seedance-2-0-fast-260128`	3.3	5.6
`dreamina-seedance-2-0-mini-260615`	2.1	3.5

Parameters (create task)

At least one of content and prompt is required: when content has no non-empty text item, prompt is added as a text item.

Field	Type	Required	Description
`model`	string	Yes	A model from the table above
`content`	array	No	Multimodal content array, items of `{type, text?, image_url?, video_url?, audio_url?, draft_task?, role?}`; `type` is `text` / `image_url` / `video_url` / `audio_url` / `draft_task`
`prompt`	string	No	Text prompt (added as a `text` item when `content` has no non-empty text item)
`callback_url`	string	No	Callback URL on task completion
`return_last_frame`	boolean	No	Whether to return the last frame image
`service_tier`	string	No	Service tier: `default` / `flex`
`execution_expires_after`	integer	No	Execution expiry (seconds)
`generate_audio`	boolean	No	Whether to generate audio, default `true`
`draft`	boolean	No	Draft mode (two-step draft flow, see below)
`tools`	array	No	Tool list (task response may return `web_search` `tool_usage`)
`safety_identifier`	string	No	Safety identifier
`priority`	integer	No	Priority
`resolution`	string	No	`480p` / `720p` / `1080p` / `4k`, default `720p`
`ratio`	string	No	`16:9` / `9:16` / `1:1` / `4:3` / `3:4` / `21:9` / `adaptive`, default `16:9`; `adaptive` fits the input image aspect ratio
`duration`	integer	No	Video duration (seconds): 2.5 supports 4–30, 2.0 series 4–15, plus `-1` (smart duration); default `5`
`frames`	integer	No	Frame count
`seed`	integer	No	Random seed
`camera_fixed`	boolean	No	Lock the camera
`watermark`	boolean	No	Whether to add a watermark
`bitrate_mode`	string	No	Bitrate mode
`omni_reference_task_type`	string	No	Omni-reference task type
`output_format`	string	No	Output format

Valid content combinations

The text prompt inside content is optional — consistent with Volcano Ark official: plain text; text (optional) + any combination of image / video / audio; draft task reference (draft_task, 2.5 only). Omitting text, passing only image / video / audio / draft reference are all valid; only an empty or missing content is rejected.

role on media items

Every image/video/audio item must carry a role; missing roles are rejected (InvalidParameter: role must be specified for image contents). Values:

role	Applies to	Description
`first_frame`	image/video	First frame
`last_frame`	image/video	Last frame, combinable with `first_frame`
`reference_image`	image	Reference image, up to 9
`reference_video`	video	Reference video, up to 3
`reference_audio`	audio	Reference audio, up to 3

Two-step draft flow (draft mode, 2.5)

Step 1 — generate a draft: "draft": true, 480p only, fast preview of camera & motion:

bash

curl $URL/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-5-260628",
    "content": [ { "type": "text", "text": "Neon street at night, slow push-in" } ],
    "draft": true, "resolution": "480p", "duration": 4
  }'

Step 2 — draft to final: pass only the draft task ID, no text needed; the prompt / reference materials are reused automatically. The final video resolution is fixed at 1080p (official two-tier design: draft 480p / final 1080p) and must be explicitly set with resolution: "1080p" — a bare Step 2 without resolution is rejected by the upstream as invalid resolution:

bash

curl $URL/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-5-260628",
    "content": [ { "type": "draft_task", "draft_task": { "id": "<task ID from Step 1>" } } ],
    "resolution": "1080p"
  }'

The draft task ID is valid for 7 days (from creation);
The final video stays on the draft's line (draft and final must use the same upstream); if that line is unavailable, the final task fails with an explicit error;
You can only reference draft tasks of your own account.

Examples

Text to video

bash

curl $URL/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-5-260628",
    "content": [
      { "type": "text", "text": "A cat wearing sunglasses walking down a neon street, slow push-in" }
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5
  }'

Image to video (reference an asset)

bash

curl $URL/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0-260128",
    "content": [
      { "type": "text", "text": "Make the pattern in the frame glow, slow push-in" },
      { "type": "image_url", "image_url": { "url": "asset URL from the asset library" }, "role": "first_frame" }
    ],
    "resolution": "720p",
    "duration": 5
  }'

Choose role by purpose: use first_frame to drive camera motion from the image as the first frame; use reference_image as a subject/style reference (without locking the first frame). Asset upload and management: Asset Library.

Video reference to video (V2V continuation)

Pass an existing video as reference for continuation/evolution, with the video item's role set to reference_video:

bash

curl $URL/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0-260128",
    "content": [
      { "type": "text", "text": "Continue the camera motion and subject movement, switch the scene to a seaside at dusk, keep the same color grading" },
      { "type": "video_url", "video_url": { "url": "https://example.com/ref.mp4" }, "role": "reference_video" }
    ],
    "resolution": "720p",
    "duration": 5
  }'

Reference video duration counts into input tokens (the "input video duration" in the billing formula); tasks with video reference bill at the "with video reference" tier. The video URL must be publicly reachable (you can re-host via the asset library first).

Query task

bash

curl $URL/api/v3/contents/generations/tasks/{task_id} \
  -H "Authorization: Bearer $YOUR_API_KEY"

State machine: queued → running → succeeded / failed / cancelled / expired.

Field	Type	Description
`id`	string	Task ID, prefixed `cgt-` (official-style native task ID)
`task_id`	string	Alias of `id`, same value
`upstream_id`	string	Same as `id`
`model`	string	Model name
`status`	string	One of the state machine above
`content.video_url`	string	Result video URL on success
`usage`	object	Actual usage (`completion_tokens` / `total_tokens`), authoritative for billing
`upstream_usage`	object	Raw usage (for reconciliation)
`error`	object	`code` / `message` on failure
`created_at`	integer	Creation time (Unix seconds)
`completed_at`	integer	Completion time (Unix seconds)

Cancel task

bash

curl -X DELETE $URL/api/v3/contents/generations/tasks/{task_id} \
  -H "Authorization: Bearer $YOUR_API_KEY"

Queued tasks can be cancelled; successful cancellation refunds in full;
For tasks already executing, it depends on the line: if the upstream allows it the task is cancelled and refunded; if the upstream refuses, the task continues to completion and bills by actual usage (the upstream error code is passed through);
Completed tasks return 409 TaskAlreadySucceeded; missing tasks return 404.

OpenAI-compatible entry (/v1/videos)

If you already use an OpenAI SDK / client, use the unified entry POST /v1/videos (query GET /v1/videos/{task_id}, OpenAI Video style response). Top-level parameters follow OpenAI semantics; official Volcano parameters pass through the metadata field with names and values identical to official. Prefer the official-path entry (see Endpoints); this entry is for OpenAI-form compatibility.

Field	Type	Required	Description
`model`	string	Yes	Model name
`prompt`	string	No	Text prompt
`seconds`	string / integer	No	Duration (seconds), default `5`. Note the OpenAI duration parameter is `seconds`, not `duration`
`images`	string[]	No	Reference image URL array (single image defaults to `first_frame`, multiple to `reference_image`)
`metadata`	object	No	Pass-through of official Volcano parameters — all fields from the "Parameters" table plus the `content` array

Note: OpenAI's input_reference (i2v) and size (aspect) currently have no effect — use metadata.content + role for i2v, and metadata.resolution + metadata.ratio for the frame.

Text to video:

bash

curl $URL/v1/videos \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-5-260628",
    "prompt": "A cat wearing sunglasses walking down a neon street",
    "seconds": "5",
    "metadata": { "resolution": "1080p", "ratio": "16:9" }
  }'

The response is an OpenAI Video object: id (cgt- task ID) / status (queued / in_progress / completed / failed) / progress / created_at; when done, metadata.url holds the result video.

Task list

bash

curl "$URL/api/v3/contents/generations/tasks?page_num=1&page_size=10" \
  -H "Authorization: Bearer $YOUR_API_KEY"

Parameter	Type	Description
`page_num`	integer	Page number, from 1, default `1`
`page_size`	integer	Items per page, 1–100, default `10`
`status`	string	Optional filter: `queued` / `running` / `succeeded` / `failed`

Response:

json

{
  "items": [ { "id": "cgt-...", "task_id": "cgt-...", "status": "succeeded", "model": "...", "content": { "video_url": "..." }, "usage": { ... } } ],
  "total": 12,
  "page_num": 1,
  "page_size": 10
}

items entries share the exact same format as single-task query; newest first, only your own tasks.

FAQ

Q: How long does generation take?

Text-to-video usually 1–5 minutes; image-to-video / with audio takes longer (up to ~15 minutes). Tasks time out at 20 minutes and are marked failed with a full refund.

Q: Why does billing differ from the estimate?

Pre-charge is an estimate by resolution and duration; the final charge settles by actual token usage. Image-to-video usually bills output duration only, so actual charges are often lower.

Q: Getting 400 / parameter errors?

Check the content[] structure against the official format (text / image_url / video_url / audio_url / draft_task); image/video/audio items must carry role; video_url assets must be uploaded to the asset library and processed first.

Seedance Official-Consistent Access (Video Generation) ​

Endpoints ​

Option 1: Native v3 API (recommended) ​

Option 2: OpenAI-compatible API ​

Supported models (official Model IDs) ​

Billing ​

Parameters (create task) ​

Valid content combinations ​

role on media items ​

Two-step draft flow (draft mode, 2.5) ​

Examples ​

Text to video ​

Image to video (reference an asset) ​

Video reference to video (V2V continuation) ​

Query task ​

Cancel task ​

OpenAI-compatible entry (/v1/videos) ​

Task list ​

FAQ ​

Seedance Official-Consistent Access (Video Generation)

Endpoints

Option 1: Native v3 API (recommended)

Option 2: OpenAI-compatible API

Supported models (official Model IDs)

Billing

Parameters (create task)

Valid content combinations

role on media items

Two-step draft flow (draft mode, 2.5)

Examples

Text to video

Image to video (reference an asset)

Video reference to video (V2V continuation)

Query task

Cancel task

OpenAI-compatible entry (/v1/videos)

Task list

FAQ