seedance-2 Video Generation
Generate videos with seedance-2, seedance-2-fast, and seedance-2-mini
Note for users in mainland China: Please use https://toapis.cn as the API endpoint (Base URL). Replace https://toapis.com with https://toapis.cn in the examples in this document.
- Supports
seedance-2,seedance-2-fast, andseedance-2-mini - Supports text-to-video, first-frame / first-last-frame image-to-video, and multimodal reference-to-video;
seedance-2-minialso supports frame roles and the audio generation switch - Supports combined image, video, and audio references;
seedance-2-miniallows up to9images,3videos, and3audios - Async task workflow: the submit API returns
generation.task, and the completed result is fetched from the task status API
Authorizations
AuthorizationstringheaderrequiredAll requests require Bearer Token authentication.
Get your API Key from the API Key Management Page.
Authorization: Bearer YOUR_API_KEYBody
modelstringbodyrequireddefault: seedance-2Video generation model name.
Available models:
seedance-2- Standard version for higher quality output and the broader Seedance 2 workflowseedance-2-fast- Faster version for previews and lower-latency iterationseedance-2-mini- Lightweight version for lower-cost drafts and multimodal reference workflows, currently fixed to1result per request
promptstringbodyVideo content description.
Supports Chinese and English input. We recommend clearly describing the scene, camera motion, subject action, style, and audio mood.
Recommendations:
- Keep Chinese prompts within
500characters - Keep English prompts within
1,000words - When referring to reference materials, use “image 1 / video 1 / audio 1” to identify them
client_business_idstringbodyYour business-side ID, such as an order number or internal job ID. Once submitted, it is stored with the task and can be used later for status lookup:
GET /v1/videos/generations/{client_business_id}.
metadata.client_business_id is also accepted, but the top-level field is recommended.
durationintegerbodydefault: 0Video duration in seconds.
Rules:
seedance-2:4-15seedance-2-fast:4-15seedance-2-mini:4-150: auto duration (seedance-2/seedance-2-fastonly)-1: auto duration (seedance-2/seedance-2-fastonly)
aspect_ratiostringbodyVideo aspect ratio.
Options:
21:916:94:31:13:49:16adaptive
adaptive lets the upstream choose an appropriate ratio from the input media.
image_urlsstring[]bodyCompatibility image URL array.
We recommend using image_with_roles instead so you can explicitly mark first_frame, last_frame, or reference_image.
- Do not use
image_urlstogether withimage_with_roles. - For new integrations, use
image_with_rolesto explicitly mark how each image should be used.
image_with_rolesarraybodyImage list with explicit roles.
Supported patterns:
seedance-2/seedance-2-fast/seedance-2-minifirst_framefor first-frame image-to-videofirst_frame+last_framefor first-last-frame video generationreference_imagefor multimodal reference generation
Field details
urlstringbodyrequiredImage URL.
Supported:
https://...
rolestringbodyrequiredImage role.
Allowed values:
first_framelast_framereference_image
- Maximum
1first_frame - Maximum
1last_frame - Maximum
9reference_image - Frame mode and reference mode cannot be mixed
seedance-2-minialso supportsfirst_frame,last_frame, andreference_image
video_with_rolesarraybodyVideo list with roles.
Only reference_video is currently supported in multimodal reference mode.
Field details
urlstringbodyrequiredVideo URL.
rolestringbodyrequiredFixed to:
reference_video
Limits:
seedance-2-mini: up to3reference videos
audio_with_rolesarraybodyAudio list with roles.
Only reference_audio is currently supported in multimodal reference mode.
Field details
urlstringbodyrequiredAudio URL.
rolestringbodyrequiredFixed to:
reference_audio
Limits:
seedance-2-mini: up to3reference audios
audio_with_roles cannot be used alone. At least one visual input is required.
resolutionstringbodydefault: 720pVideo resolution.
Options:
seedance-2:480p,720p,1080p,4kseedance-2-fast:480p,720pseedance-2-mini:480p,720p
generate_audiobooleanbodydefault: trueWhether to generate synced audio.
seedance-2-mini also supports this field.
return_last_framebooleanbodydefault: falseWhether to return the generated video's last-frame image.
When set to true, the completed task response includes the image URL at result.data[0].last_frame_url.
toolsarraybodyTools the model may call. The Seedance 2 series currently supports web search:
[{ "type": "web_search" }]The model decides whether a search is needed from the prompt. The actual number of searches is returned at usage.tool_usage.web_search; 0 means no search was performed.
tools is supported only for text-to-video requests and cannot be combined with image, video, or audio inputs.
seedintegerbodyRandom seed for generation control.
callback_urlstringbodyToAPIs standardized completion callback. Configure the Token URL and signing secret first; request-level URLs must be same-origin. See Task Webhooks.
trace_idstringbodyYour tracking field. It does not depend on Webhook configuration.
disable_nsfwbooleanbodydefault: trueNSFW content generation is disallowed by default. Set to false to allow it.
Asset review
When a request includes image, video, or audio inputs, some channels review the media automatically before submitting generation. No extra parameter is needed; pass media URLs in the existing media fields.
- An accepted request returns a video task immediately. When review is required, the task stays
queuedand generation is submitted only after all media in the request pass. First-time review can take several minutes; reusing the same URL for the same user and channel reuses the review result. - Each media preparation round lasts up to 20 minutes by default. Rejection or preparation timeout ends the task as
failed; seeerror.messagefor the reason. Failed review incurs no video generation fee. - Media must be public HTTP(S) URLs; Base64 and local paths are not accepted. Keep images within 30 MB and video or audio within 100 MiB. Each model's existing format limits still apply.
- Channels that review media validate it at submission: a URL with embedded credentials or longer than 2048 bytes, the same URL used as different media types, or more than 64 media references in one request returns HTTP 400 with
error.codeinvalid_private_assets. - Media is identified by URL. Use a new URL after the file content changes.
- Legacy
asset://references are retired and return HTTP 400.
Input Combinations
Typical supported combinations:
- Text only: text-to-video
- Text + first frame: first-frame image-to-video
- Text + first frame + last frame: first-last-frame generation
- Text + reference images: multimodal reference generation
- Text + reference video: video-reference generation
- Text + reference images + reference audio: multimodal reference generation
- Text + reference images + reference video + reference audio: multimodal reference generation
seedance-2-mini also supports first-frame and first-last-frame workflows. Use image_with_roles with explicit first_frame / last_frame roles.
Capabilities
| Item | seedance-2 | seedance-2-fast | seedance-2-mini |
|---|---|---|---|
| Positioning | Higher quality and longer runs | Faster generation and lower latency | Lower-cost drafts and multimodal reference |
| Duration | 4-15 seconds, auto duration supported | 4-15 seconds, auto duration supported | 4-15 seconds |
| Resolution | 480p / 720p / 1080p / 4k | 480p / 720p | 480p / 720p |
| Image roles | first_frame / last_frame / reference_image | first_frame / last_frame / reference_image | first_frame / last_frame / reference_image |
| Video roles | reference_video | reference_video | reference_video |
| Audio roles | reference_audio | reference_audio | reference_audio |
| Frame mode | Supported | Supported | Supported |
| Reference image limit | 9 | 9 | 9 |
| Reference video limit | Depends on the routed channel | Depends on the routed channel | 3 |
| Reference audio limit | Depends on the routed channel | Depends on the routed channel | 3 |
| Synced audio field | generate_audio | generate_audio | generate_audio |
| ToAPIs callback | callback_url (trace_id optional) | callback_url (trace_id optional) | callback_url (trace_id optional) |
seedance-2-mini is currently fixed to 1 output per request and does not expose count / n. Express frame control through image_with_roles using first_frame / last_frame.
Fetch completed results from Video task status. When original URL delivery is enabled, prefer result.data[].url and use the optional fallback_url only if the primary URL cannot be accessed. Last frames use last_frame_url and fallback_last_frame_url. Fallback fields are returned only when copies are available.
Response
idstringTask ID for status queries.
client_business_idstringYour business-side ID. Returned only when client_business_id was provided in the request.
objectstringObject type, always generation.task.
modelstringModel name used for this request.
statusstringTask status: queued, in_progress, completed, or failed.
progressintegerTask progress percentage (0-100).
created_atintegerTask creation timestamp.
The submit API returns the base task object. After completion, use Get Video Task Status to fetch completed_at, expires_at, and result.type = "video" with result.data[].url and result.data[].format. With return_last_frame, the last-frame URL is at result.data[0].last_frame_url; with web_search, the search count is at usage.tool_usage.web_search.
requestExample
curl --request POST \
--url https://toapis.com/v1/videos/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"model": "seedance-2-mini",
"client_business_id": "order_20260616_001",
"prompt": "Keep the character from image 1, follow the camera motion of video 1, and match the rhythm of audio 1 for a short indoor product clip.",
"duration": 10,
"aspect_ratio": "16:9",
"image_with_roles": [
{"url": "https://example.com/ref-image-1.jpg", "role": "reference_image"}
],
"video_with_roles": [
{"url": "https://example.com/ref-video-1.mp4", "role": "reference_video"}
],
"audio_with_roles": [
{"url": "https://example.com/ref-audio-1.mp3", "role": "reference_audio"}
],
"resolution": "480p"
}'curl --request POST \
--url https://toapis.com/v1/videos/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"model": "seedance-2",
"prompt": "Slowly push from the bouquet by the window toward the dining table, keeping a warm and soft look.",
"duration": 5,
"aspect_ratio": "16:9",
"image_with_roles": [
{"url": "https://example.com/first-frame.png", "role": "first_frame"},
{"url": "https://example.com/last-frame.png", "role": "last_frame"}
],
"resolution": "720p",
"generate_audio": false
}'import requests
response = requests.post(
"https://toapis.com/v1/videos/generations",
headers={
"Authorization": "Bearer your-ToAPIs-key",
"Content-Type": "application/json",
},
json={
"model": "seedance-2-mini",
"prompt": "Keep the same character and use the reference image and video rhythm to create a short indoor ad clip",
"duration": 8,
"aspect_ratio": "16:9",
"resolution": "720p",
"image_with_roles": [
{"url": "https://example.com/ref.png", "role": "reference_image"}
],
"video_with_roles": [
{"url": "https://example.com/ref.mp4", "role": "reference_video"}
],
},
)
print(response.json())responseExample
{
"id": "tsk_vid_xxx",
"client_business_id": "order_20260616_001",
"object": "generation.task",
"model": "seedance-2-mini",
"status": "in_progress",
"progress": 10,
"created_at": 1781577600
}