ToAPIsToAPIs
seedance-2

seedance-2 Video Generation

Generate videos with seedance-2, seedance-2-fast, and seedance-2-mini

POST
/v1/videos/generations

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, and seedance-2-mini
  • Supports text-to-video, first-frame / first-last-frame image-to-video, and multimodal reference-to-video; seedance-2-mini also supports frame roles and the audio generation switch
  • Supports combined image, video, and audio references; seedance-2-mini allows up to 9 images, 3 videos, and 3 audios
  • Async task workflow: the submit API returns generation.task, and the completed result is fetched from the task status API

Authorizations

Authorizationstringheaderrequired

All requests require Bearer Token authentication.

Get your API Key from the API Key Management Page.

Authorization: Bearer YOUR_API_KEY

Body

modelstringbodyrequireddefault: seedance-2

Video generation model name.

Available models:

  • seedance-2 - Standard version for higher quality output and the broader Seedance 2 workflow
  • seedance-2-fast - Faster version for previews and lower-latency iteration
  • seedance-2-mini - Lightweight version for lower-cost drafts and multimodal reference workflows, currently fixed to 1 result per request
promptstringbody

Video 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 500 characters
  • Keep English prompts within 1,000 words
  • When referring to reference materials, use “image 1 / video 1 / audio 1” to identify them
client_business_idstringbody

Your 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: 0

Video duration in seconds.

Rules:

  • seedance-2: 4-15
  • seedance-2-fast: 4-15
  • seedance-2-mini: 4-15
  • 0: auto duration (seedance-2 / seedance-2-fast only)
  • -1: auto duration (seedance-2 / seedance-2-fast only)
aspect_ratiostringbody

Video aspect ratio.

Options:

  • 21:9
  • 16:9
  • 4:3
  • 1:1
  • 3:4
  • 9:16
  • adaptive

adaptive lets the upstream choose an appropriate ratio from the input media.

image_urlsstring[]body

Compatibility 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_urls together with image_with_roles.
  • For new integrations, use image_with_roles to explicitly mark how each image should be used.
image_with_rolesarraybody

Image list with explicit roles.

Supported patterns:

  • seedance-2 / seedance-2-fast / seedance-2-mini
    • first_frame for first-frame image-to-video
    • first_frame + last_frame for first-last-frame video generation
    • reference_image for multimodal reference generation
Field details
urlstringbodyrequired

Image URL.

Supported:

  • https://...
rolestringbodyrequired

Image role.

Allowed values:

  • first_frame
  • last_frame
  • reference_image
  • Maximum 1 first_frame
  • Maximum 1 last_frame
  • Maximum 9 reference_image
  • Frame mode and reference mode cannot be mixed
  • seedance-2-mini also supports first_frame, last_frame, and reference_image
video_with_rolesarraybody

Video list with roles.

Only reference_video is currently supported in multimodal reference mode.

Field details
urlstringbodyrequired

Video URL.

rolestringbodyrequired

Fixed to:

  • reference_video

Limits:

  • seedance-2-mini: up to 3 reference videos
audio_with_rolesarraybody

Audio list with roles.

Only reference_audio is currently supported in multimodal reference mode.

Field details
urlstringbodyrequired

Audio URL.

rolestringbodyrequired

Fixed to:

  • reference_audio

Limits:

  • seedance-2-mini: up to 3 reference audios

audio_with_roles cannot be used alone. At least one visual input is required.

resolutionstringbodydefault: 720p

Video resolution.

Options:

  • seedance-2: 480p, 720p, 1080p, 4k
  • seedance-2-fast: 480p, 720p
  • seedance-2-mini: 480p, 720p
generate_audiobooleanbodydefault: true

Whether to generate synced audio.

seedance-2-mini also supports this field.

return_last_framebooleanbodydefault: false

Whether 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.

toolsarraybody

Tools 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.

seedintegerbody

Random seed for generation control.

callback_urlstringbody

ToAPIs standardized completion callback. Configure the Token URL and signing secret first; request-level URLs must be same-origin. See Task Webhooks.

trace_idstringbody

Your tracking field. It does not depend on Webhook configuration.

disable_nsfwbooleanbodydefault: true

NSFW 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 queued and 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; see error.message for 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.code invalid_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

Itemseedance-2seedance-2-fastseedance-2-mini
PositioningHigher quality and longer runsFaster generation and lower latencyLower-cost drafts and multimodal reference
Duration4-15 seconds, auto duration supported4-15 seconds, auto duration supported4-15 seconds
Resolution480p / 720p / 1080p / 4k480p / 720p480p / 720p
Image rolesfirst_frame / last_frame / reference_imagefirst_frame / last_frame / reference_imagefirst_frame / last_frame / reference_image
Video rolesreference_videoreference_videoreference_video
Audio rolesreference_audioreference_audioreference_audio
Frame modeSupportedSupportedSupported
Reference image limit999
Reference video limitDepends on the routed channelDepends on the routed channel3
Reference audio limitDepends on the routed channelDepends on the routed channel3
Synced audio fieldgenerate_audiogenerate_audiogenerate_audio
ToAPIs callbackcallback_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

idstring

Task ID for status queries.

client_business_idstring

Your business-side ID. Returned only when client_business_id was provided in the request.

objectstring

Object type, always generation.task.

modelstring

Model name used for this request.

statusstring

Task status: queued, in_progress, completed, or failed.

progressinteger

Task progress percentage (0-100).

created_atinteger

Task 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
}