Seedance Official Relay Video API

This page specifies the Seedance Official Relay video models. They share the POST /v1/videos create and GET /v1/videos/{id} polling flow with the other video models; authentication, media upload, polling states, downloads and error handling are covered in the Complete Video API Standard. This page lists only the fields and rules specific to this group.

Updated 2026-10-13. These models relay the official Volcengine Seedance API and are a different model group from Seedance Official Edition and SD Cloud Edition; parameters and capabilities do not carry over. These models do not support callback_url: a request with a non-empty callback_url returns 400 and creates no task and no charge (an empty string is treated as not set); poll GET /v1/videos/{id} for results.

Models

The table lists the model IDs of this group. They are visible only to API keys with the corresponding group enabled; otherwise GET /v1/models does not return them.

The earlier model IDs doubao-seedance-2-0-mini-260615, doubao-seedance-2-0-260128, doubao-seedance-2-0-fast-260128 and doubao-seedance-2-5-260628 remain callable and are identical to the models of the same name above. They are no longer shown in the model marketplace; use the IDs in the table for new integrations.

Common rules

• Resolution: choose the output tier with resolution from the table above (case-insensitive, for example 720p or 4k). The default is 720p.
• Duration: whole seconds in duration (or seconds); -1 lets the model choose the duration.
• Aspect ratio: ratio (or aspect_ratio) accepts 16:9, 4:3, 1:1, 3:4, 9:16, 21:9 and adaptive. The default is adaptive (follow the input media). size also accepts a ratio or a resolution tier (for example 16:9 or 1080p); a value that conflicts with ratio, aspect_ratio or resolution returns 400.
• Prompt: may be omitted when references or keyframes are supplied; a request with neither returns 400.
• Generated audio: set generate_audio (boolean) to false to turn audio off; audio is on by default.
• Optional fields: watermark (boolean; true adds an "AI 生成" (AI-generated) watermark in the bottom-right corner, off by default), priority (integer 0–9, queue priority) and return_last_frame (boolean, see Last frame).
• Unsupported fields: seed, camera_fixed, frames and service_tier return 400; draft is supported only by Seedance 2.5, see Drafts and final videos.

Billing

These models are billed on the output tokens reported by the model platform after the task finishes, at the unit price tier matching "resolution × with or without a reference video". Nothing is pre-charged at submission: the usage log first shows a submission record "操作 …" (operation) with an amount of 0, and after the task finishes a "任务用量表达式结算" (usage settlement) record charges the actual usage.

When the model chooses the duration (duration is -1, or Seedance 2.5 is sent without a duration), the seconds in the submission record are an estimate based on the maximum duration and appear as "seconds: 30（预估）" (estimate); the settlement record is what you are actually charged. Failed or cancelled tasks are not charged.

Reference media

• Put reference images in images, reference videos in metadata.referenceVideos and reference audio in metadata.referenceAudios.
• The singular fields also work: image and input_reference as reference images, video as a reference video and audio as reference audio. The same media sent in several fields counts once.
• Each item can be a URL string or { "url": "...", "role": "..." }.
• Images accept public https:// URLs or data: URIs; audio accepts public https:// URLs or data: URIs.
• Reference videos accept only public https:// URLs, not http://, data:, Base64 or local files; for a local video, first obtain a URL through Local media upload. The link must be reachable without login and stay valid until the task finishes.
• The 2.0 family (Mini, 2.0, Fast) cannot take reference audio alone; add a reference image or video.
• Keep total reference video and audio length within 15 seconds each for the 2.0 family and 30 seconds each for 2.5; longer media may be rejected by the model platform after submission.
• You can also use the Volcengine Ark content array directly (text, image_url, video_url and audio_url items; an image role can be first_frame, last_frame or reference_image), either at the top level or inside metadata.

{
  "model": "doubao-seedance-2.0",
  "prompt": "The person from the image dances to the reference audio, moving like the reference video",
  "duration": 8,
  "resolution": "1080p",
  "ratio": "16:9",
  "images": ["https://cdn.example.com/dancer.jpg"],
  "metadata": {
    "referenceVideos": ["https://cdn.example.com/dance-motion.mp4"],
    "referenceAudios": ["https://cdn.example.com/music.mp3"]
  }
}

Virtual portrait library (asset mode)

By default, reference media is submitted directly to the generation API for review. You can instead place media in the virtual portrait library first and use it for generation once it passes library review:

• Set "image_source_mode": "asset" for images and "video_source_mode": "asset" for reference videos (videos must still be public https:// URLs). Both fields can go at the top level or in metadata and are independent of each other.
• Local images uploaded with multipart/form-data are placed in the virtual portrait library and submitted in asset mode automatically, with no extra setting; see File upload.
• Library review only checks whether the media is usable; it is not real-name, face or liveness verification. There is currently no authorized enrollment flow for real people, and photos of real people may fail review in asset mode as well.
• There is currently no standalone media management (separate upload, media list or media IDs), so every generation request must include its media.

{
  "model": "doubao-seedance-2.5",
  "prompt": "The person in image 1 wears the necklace from image 2 and turns slowly in a bright studio",
  "duration": 6,
  "resolution": "720p",
  "ratio": "9:16",
  "image_source_mode": "asset",
  "images": [
    { "url": "https://cdn.example.com/model.png", "role": "reference_image" },
    { "url": "https://cdn.example.com/necklace.png", "role": "reference_image" }
  ]
}

Multiple reference images keep their submission order. State in the prompt what "image 1", "image 2" and so on each contain, so people and objects are not mixed up.

First and last frames

Put keyframes in metadata.firstFrame and metadata.lastFrame; they count toward the image limit.

• lastFrame requires firstFrame.
• Keyframes cannot be combined with reference images, videos or audio.
• With keyframes, Seedance 2.5 (multi-resolution) requires ratio to be adaptive (or omitted).

{
  "model": "doubao-seedance-2.0-fast",
  "prompt": "Transition smoothly from an empty square at dawn to the same view at night with the lights on",
  "duration": 5,
  "resolution": "720p",
  "metadata": {
    "firstFrame": "https://cdn.example.com/start.jpg",
    "lastFrame": "https://cdn.example.com/end.jpg"
  }
}

Seedance 2.5 video editing and extension

When Seedance 2.5 (multi-resolution) receives a reference video, omni_reference_task_type selects the task:

output_format can be mp4 or mov. Both fields apply to 2.5 only; the 2.0 family returns 400.

{
  "model": "doubao-seedance-2.5",
  "prompt": "Turn the daytime scene into a rainy night and keep the person's movement",
  "omni_reference_task_type": "edit",
  "duration": -1,
  "ratio": "adaptive",
  "metadata": {
    "referenceVideos": ["https://cdn.example.com/source.mp4"]
  }
}

Drafts and final videos (Seedance 2.5)

Seedance 2.5 (multi-resolution) can first generate a low-cost 480p draft and, once you are happy with it, generate a 1080p final video from that draft. Other models do not support drafts.

1. Generate a draft: add "draft": true to the request; the output is fixed at 480p. A draft cannot also set return_last_frame.
2. Wait for the draft to succeed: poll GET /v1/videos/{id} as usual and review the draft once the status is completed.
3. Generate the final video: put a single draft_task in content, with id set to the draft task's id (the task_… returned when the draft was created). The final video is fixed at 1080p and inherits the prompt, media, duration, ratio, audio and other settings from the draft. Do not resend prompt, media, duration, ratio, generate_audio, omni_reference_task_type or return_last_frame; doing so returns 400.

{
  "model": "doubao-seedance-2.5",
  "content": [
    { "type": "draft_task", "draft_task": { "id": "task_REPLACE_WITH_YOUR_DRAFT_TASK_ID" } }
  ],
  "watermark": false
}

• Only successful draft tasks created by your own account can be used; generate the final video within 7 days of creating the draft.
• The draft and the final video are two separately billed tasks. The final video is billed at the 1080p tier, and if the draft used a reference video, the final video is likewise billed at the with-reference-video tier.

Last frame

Set "return_last_frame": true in the request. After the task succeeds you can fetch the last frame of the video as an image, for continuing the shot or as the first frame of the next clip:

curl https://api.88api.ai/v1/tasks/task_xxx/artifacts \
  -H "Authorization: Bearer sk-your-api-key"

In the returned artifacts, the item whose key is last_frame is the last-frame image; download it from its content_url (also with your API key). The last frame is not included in the GET /v1/videos/{id} response. The image format is whatever the download's Content-Type says; it is not guaranteed to be PNG.

Web search

The Seedance 2.0 family and 2.5 support web search through tools, which suits prompts that need real-time information:

{
  "model": "doubao-seedance-2.0",
  "prompt": "Based on today's weather in Shanghai, generate a street-view video of the Bund",
  "duration": 5,
  "resolution": "720p",
  "tools": [{ "type": "web_search" }]
}

• tools supports only {"type": "web_search"}.
• The model decides from the prompt whether to actually search. Searches are billed per search only when they actually happen (see the pricing notes in the console for the unit price); there is no extra charge when no search is made.

Cancelling a task

A task that is still queued and has not started generating can be cancelled:

curl -X DELETE https://api.88api.ai/v1/videos/task_xxx \
  -H "Authorization: Bearer sk-your-api-key"

• A successful cancellation returns {"id": "task_xxx", "object": "video", "status": "cancelled", "cancelled": true}. The task then shows as failed (reason "任务已被用户取消", cancelled by the user) and is not charged.
• A task that has started preparing or generating, or has already finished, cannot be cancelled and returns 409 task_not_cancellable; keep querying the task result instead.
• DELETE /v1/video/generations/{id} has the same effect.

Official task ID

Once Volcengine Ark accepts the task, GET /v1/videos/{id} returns official_task_id (for example cgt-20261012120000-abcde), and the console task log also shows the official task ID. When you need a generation issue checked, provide both the task id and the official task ID. The field is not returned while the task is still queued and has not been accepted.

File upload

You can upload local images directly with multipart/form-data, including several at once: repeat the same field name (for example image), and the files map to "image 1", "image 2" and so on in submission order. Uploaded images are placed in the virtual portrait library automatically and submitted in asset mode.

curl https://api.88api.ai/v1/videos \
  -H "Authorization: Bearer sk-your-api-key" \
  -F model=doubao-seedance-2.5 \
  -F "prompt=The person in image 1 wears the necklace from image 2 and turns slowly" \
  -F duration=6 \
  -F resolution=720p \
  -F "image=@./model.png" \
  -F "image=@./necklace.png"

• When you use local files, do not also send images in images, image, input_reference or content.
• Each file can be up to 64 MB and the whole request up to 128 MB.
• Local videos and audio cannot be uploaded directly with multipart/form-data: first obtain an https:// URL through Local media upload, then put it in the reference video or reference audio field; reference audio can also be a data: Data URI.