Skip to main content
POST
Main changes vs 2.0: max duration 15s → 30s; references 9 images + 3 videos + 3 audios → 30 images + 10 videos + 10 audios; audio-only reference supported; mov output added.
Note: resolution supports 480p / 720p / 1080p (2.0’s 4k is not available on 2.5).

Authentication

string
required
Bearer token auth. Get a key from the API Key page.

Request parameters

string
required
Fixed value: seedance-2.5
boolean
default:"false"
Whether to run content moderation before submitting the video task.
  • true: use omni-moderation-latest to review prompts and input images
  • false or omitted: do not send a moderation request, adding no moderation cost or latency (default)
Content reviewed:
  • Text: prompt, negative_prompt
  • Images: image_urls, image_with_roles[].url, first_frame_image, last_frame_image
  • Image-type private asset:// assets: resolve and review their original public URL
  • Base64 images: review them after conversion to a public URL
video_urls, audio_urls, and video/audio private assets are not reviewed, because the moderation model does not support video or audio.Supported model IDs: seedance-2.0, seedance-2.0-fast, seedance-2.0-mini, seedance-2.0-face, seedance-2.0-fast-face, seedance-2-0 (legacy), and seedance-2.5.The moderation call itself is not billed to the user submitting the video request.
  • Flagged content returns a synchronous HTTP 400 (nsfw_content_detected). No task or task_id is created, and no video-generation quota is charged
  • If moderation is unavailable, times out, or returns an invalid response, the request fails open and generation continues. Do not treat this option as an absolute content-safety guarantee
  • Inputs that cannot be resolved to a public image URL are skipped; unsupported models silently ignore nsfw_check: true
Example:
Response when flagged:
boolean
Set to true to generate a 480p draft. Only seedance-2.5 supports this option. Omit it for normal generation.
  • resolution must be 480p; it defaults to 480p when omitted
  • Cannot be combined with draft_task_id
  • Drafts are valid for 7 days from creation and can produce a 1080p final video after successful completion
See Draft mode for the workflow.
string
Generate a 1080p final video from a completed draft. Provide the APIMart task ID from the draft submission response (data[0].task_id), not a video URL.
  • Only seedance-2.5 is supported; use the same model as the draft
  • The draft must belong to the user associated with the current API Key, have completed successfully, and be within 7 days of creation
  • resolution must be 1080p; it defaults to 1080p when omitted
  • Cannot be combined with draft: true; do not resend inherited fields such as prompt, reference media, or duration
See Draft mode for adjustable fields and restrictions.
string
Required for normal generation and drafts. Omit it when using draft_task_id: the final video inherits the draft prompt, and sending this field is rejected.Prompt. Reference media with @图片1 / @视频1 / @音频1 (1-based index matching array order). English aliases in prompts may also be used depending on model behavior; keep indices aligned with arrays.Example: "Use @视频1 for first-person framing throughout, @音频1 as BGM, first frame is @图片1"
string
default:"720p"
Resolution — only:
  • 480p
  • 720p (default)
  • 1080p
Unsupported values like 2k / 4k return a sync 400.Draft-mode exception: draft: true only supports 480p and defaults to it; draft_task_id only supports 1080p and defaults to it.
string
default:"adaptive"
Aspect ratio (field name aspect_ratio is also accepted).Values: 16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptive (default)
Edit, extend, and first/last-frame jobs have hard size constraints — see Task types and constraints.
integer
default:"5"
Duration in seconds:
  • 4 ~ 30
  • -1: model picks duration (pre-charge at the 30s cap; settle to actual length after completion)
If omitted: generate and bill 5 seconds.
boolean
default:"true"
Whether to generate audio (alias field name: audio).
  • true: with audio (default)
  • false: silent video
boolean
default:"false"
Add an “AI generated” watermark. Default false.
integer
Random seed. Different seeds usually yield different results for the same request; the same seed is similar but not guaranteed identical.
string
default:"mp4"
Output container:
  • mp4 (default)
  • mov: higher color precision — recommended for edit / extend workflows
string
default:"auto"
Sub-task type hint: auto / reference / edit / extend.Passing reference / edit / extend validates that type’s constraints at submit time. Invalid requests return 400, create no task, and charge nothing. See Task types and constraints.
array<string>
Reference image URLs, all treated as reference_image.Supports:
  • Public URL: https://example.com/pic.jpg
  • Private asset: asset://cm9xxxxxxxx
For first/last frames use image_with_roles.
  • Max 30 images
  • Prefer image_with_roles for first/last-frame roles
array<object>
Images with explicit roles.Example:
If video_urls / audio_urls are present, first_frame / last_frame are auto-converted to reference_image (multimodal reference job).
array<string>
Reference videos (reference_video).Input: video URL or asset ID (asset://...).See Reference video specs.
array<string>
Reference audio URLs (reference_audio). Public URLs or asset://....Max 10; total duration ≤ 30s (each clip 2~30s).
2.5 supports audio-only reference (no image/video required).
boolean
default:"false"
When true, the successful result also includes the last-frame image for chaining.
array<object>
Tool list for enhancements such as web search.Example:

Media limits

Reference video specs

  • Input: video URL or asset ID (asset://...)
  • Container: mp4, mov — codecs in the table below
  • Resolution: 480p, 720p, 1080p
  • Duration: each clip [2, 30] s; up to 10 reference videos; total duration of all videos ≤ 30s
  • Per-video dimensions:
    • Aspect ratio (width/height): [0.4, 2.5]
    • Side length (px): [300, 6000]
    • Total pixels: [640×640=409600, 3326×2494=8295044], i.e. width × height must fall in [409600, 8295044]
  • Size: each video ≤ 200 MB
  • Frame rate (FPS): [24, 60]

Supported codecs

Task types and constraints

The service infers task type from references and prompt intent. The last three types hard-constrain size / duration; violations fail asynchronously after the job starts (e.g. InvalidParameter.TaskTypeConstraint):

Turn async errors into sync errors with omni_reference_task_type

Passing reference / edit / extend declares the sub-task type so its constraints are validated at submit time. Invalid requests return 400 immediately: no task is created and nothing is charged — you do not have to poll until failed. Notes:
  • If edit omits duration, the platform sets it to -1. Omitting duration otherwise defaults to 5 seconds, which conflicts with the upstream edit requirement of -1. The trade-off is a 30-second prepaid hold (same as duration: -1); unused amount is refunded after completion. For a smaller hold, skip edit and use default auto.
  • If edit sends duration explicitly, it must be -1. Any other value returns 400 (output length follows the source video).
  • ⚠️ You can still fail asynchronously with InvalidParameter.TaskTypeMismatch. Upstream re-classifies the job from the prompt; a mismatch with your declared type is rejected. Keep prompt wording aligned (edit: “edit / delete / replace…”; extend: “extend forward/backward / continue…”).
  • All Seedance 2.5 channels share the same validation and upstream payload; switching channels does not change this behavior.

Asset library

You can pass public URLs as references, or upload into the library first and use asset://. Prefer the library when:
  1. Real human faces must use the library — raw URLs are blocked by content moderation; only approved library assets can be used
  2. Assets are reused often — upload once, skip repeated moderation on later jobs, faster submits
  3. URLs are signed temporary links — the platform stores a durable copy on ingest so later use does not depend on the original URL staying alive
  4. Library assets are synced to all available channels so multi-channel routing can use them wherever the job lands
The library is shared with the 2.0 family; approved asset:// IDs work in both 2.0 and 2.5 generation requests. Full submit fields: also see Private avatar assets.

Upload assets

The response includes a local task id. Poll with Get task status (GET /v1/tasks/{id}). After approval, list assets to obtain the asset:// ID.

Media limits (validated at submit)

Violations return 400 immediately (which asset index and which rule), without starting moderation or consuming moderation quota: Error example:
For 30s video assets, submit with "model": "seedance-2.5" (2.0 cannot use assets longer than 15s).
If the platform cannot probe the media (e.g. network blip), it may pass through and leave the decision to moderation.

Use in generation requests

Reference approved assets with asset:// in image_urls / image_with_roles / video_urls / audio_urls:
Multi-channel: after ingest, assets sync to all available channels so any routed channel can use them. If a channel’s copy is missing, the platform may re-upload from the original URL as a fallback (if that URL is already expired, that channel is skipped and another takes over).

Management APIs (quick reference)

Asset APIs are free of charge (auth + rate limits only); they do not create billing records.

FAQ

Q: How long does moderation take?
Images usually seconds; video and real-person assets may take minutes. Poll the task id until a terminal status.
Q: Moderation failed with no clear reason?
Some failures omit a detailed reason (often a transient fetch failure). The platform already retries once; if it still fails, change the URL (ensure it is publicly downloadable) and resubmit.
Q: Same asset for both 2.0 and 2.5 — upload twice?
No. Upload once; asset:// works for both generations. Cross-channel / cross-model sync is handled by the platform.
Q: Can I pass a real-person face as a raw URL?
Real-person assets must go through the library first.

Billing

These rules apply to normal generation and drafts. For final videos rendered from drafts, see Draft mode billing.
  • Billed by seconds × resolution tier.
  • With reference video input: billable seconds = total input video duration (≤30s) + output duration, at the input-reference rate tier.
  • duration = -1 (auto): pre-charge at the 30s cap; settle to actual output after completion.
  • Omit duration: generate and bill 5 seconds.
  • Failed jobs or content moderation blocks: full refund (charge only on successful output).

Draft mode

Generate a 480p draft to review the visuals, then use its task ID to generate a 1080p final video. The final video reuses the draft’s prompt, reference media, duration, aspect ratio, seed, audio setting, and task type to align with the draft.

Step 1: Generate a 480p draft

Add "draft": true to a normal generation request. Media and task-type constraints remain the same. Omitted resolution defaults to 480p; 720p or 1080p returns 400.
Read the draft task ID from data[0].task_id. Poll task status and submit the final video only after data.status becomes completed.
Poll every 5–15 seconds. pending means queued, processing means generating, completed means successful, and failed means failed. Video URLs are in the data.result.videos[].url array; read url[0].

Step 2: Generate a 1080p final video

Set draft_task_id to the ID returned in step 1. Omitted resolution defaults to 1080p; other resolutions return 400.
The final video returns a new task ID. Query its result with GET /v1/tasks/{task_id}. The following fields are inherited from the draft. Do not resend them: even identical values return 400: prompt, image_urls, image_with_roles, video_urls, audio_urls, duration, size, aspect_ratio, seed, generate_audio, audio, omni_reference_task_type, generation_type, camerafixed, web_search, tools. You may adjust these output options:
draft: true and draft_task_id are mutually exclusive. Neither drafts nor final videos support service_tier.Drafts expire 7 days after creation. A missing task, a task owned by another user, an incomplete or non-draft task, or an expired draft returns 400 on final-video submission, without creating a task or charging.
The final video must use the same route that generated the draft; the service associates it automatically. If that route is temporarily unavailable, submission returns 400. Retry later with the same draft_task_id. An unexpired draft can generate multiple final videos. Each is an independent task billed separately.

Draft mode billing

Drafts are billed as normal 480p videos. Reference-video input duration is included as usual, up to 30 seconds in total. Final videos always use the 1080p tier without video input. Input-video duration is not charged again, even if the draft used reference videos. Successful tasks settle against actual token usage, refunding excess reservations or charging any shortfall. Failed tasks are fully refunded. Rates and discounts follow model pricing.
Width and height are the output pixel dimensions of the corresponding task. After success, data.usage.completion_tokens reports the tokens used for settlement.

Request examples

Text-to-video (30s)

Multimodal reference (image + video + audio)

Video edit

First–last frame

Private asset

Common errors

Response (submit)

integer
Status code; 200 on success
array
Submit response with status / task_id

Completed task (GET /v1/tasks/{task_id})

After submit, poll with Get task status. When status is completed, the payload looks like this.

Completed response example

Completed fields

Notes

  • Failed tasks (status=failed): cost is always 0 (pre-charge fully refunded); reason in data.error.message
  • usage may be missing for a few seconds after completion (settlement lag); query again shortly

Differences from 2.0