Every Seedance 2.5 request field, and what it does

Updated 2026-10-02

The Seedance 2.5 request body is small, but several fields behave in ways that do not match what you would guess. This page goes field by field, using only what VideoRouter's documentation states. Where a detail depends on the host or variant, it says so instead of guessing; the model pages are the source of truth for per-host support.

Core fields

duration_secs: requested, then snapped

The value you send is snapped to the nearest duration the model actually supports, and the snapped value is what you are billed for, once, at creation. Two practical consequences. First, a request for an odd length can end up a different length than you intended, so read back the job rather than assuming. Second, because the charge happens at creation and not at completion, the right way to control cost is to request the shortest clip that demonstrates what you need. If you do not send the field, the default is 4 seconds. Which durations Seedance 2.5 supports can differ by host; check the model page and test with a short request before building a pipeline around a specific length.

resolution and aspect_ratio: forgiving, not strict

The Seedance 2.5 model page lists many resolution tier strings: plain tiers (480p, 720p, 1080p, 2160p) and suffixed variants such as 720p-sr, 720p-esr, 1080p-sr, 1080p-esr, 1440p-sr, 1440p-esr and 4k-esr, with a 60 fps option shown on one of them. Not every host offers every tier; VideoRouter's documentation notes that some hosts carry enhanced and super-resolution tiers that others do not. Treat the tier string as a menu item you pick from the page for the host you intend to use.

The behaviour that matters most: an unsupported resolution and aspect_ratio combination never returns a 400. It is silently ignored and the model default is used, exactly as if you had omitted both. So a typo in a tier name will not fail loudly. Verify output dimensions in your test suite, for example with ffprobe, and do not infer success from a 202.

If you need exact pixels, height and width are accepted as integers and take precedence over the other two. For most callers the tier plus ratio is simpler.

start_image_url: animate a first frame

Add start_image_url as a public https:// URL or an inline data:image/...;base64,... URI and the model animates that frame. The model id does not change. For a local file, POST /v1/uploads (multipart, up to 50 MB) returns a presigned URL valid for 30 minutes, which is a scratch link for the next call, not storage. An expired or unreachable URL is a common cause of a failed job. Image input is a per-host capability: models that do not take an image reject the field with a 400. See the image-to-video guide for a worked request.

One field you might expect is end_image_url for last-frame control. VideoRouter's documentation states that no model accepts it yet, and a request including it is rejected with a 400 instead of ignored. Even where a model page mentions start and end frames in general terms, do not send it.

Reference arrays

Reference-to-video guides a new clip with material you supply. Three optional arrays share one shape, {"type": "image_url", "image_url": {"url": "..."}} and its video and audio equivalents:

• input_references: images, up to 9 on models that support it
• input_video_references: videos, up to 3 on supporting models
• input_audio_references: audio, up to 3 on supporting models

The documented combined cap on the Seedance 2.0 reference endpoint is 12 across all three. At least one reference is required when you use the mode, and exceeding any cap is a 400, not a truncation. Caps are model- and host-dependent, and the documentation names specific Seedance 2.0 hosts as supporting the full set while other hosts accept images only. For Seedance 2.5, confirm the arrays on the model page for your host before depending on them. Details and a consistency workflow are in the reference-to-video guide.

Reference mode is mutually exclusive with input_video_url, the editing field, and with start_image_url. Pick one intent per request.

Provider preferences

The optional provider object controls which host serves the job. Fields that apply to video: only (allow-list), ignore (block-list), order (priority, not a restriction), sort (price, latency, reliability or queue), policy (named shorthands such as lowest_cost, fast_finish and most_reliable) and allow_fallbacks. The default is cheapest-healthy-first with automatic fallthrough on a rejected submission. A separate failover.on_timeout_sec hedges to the next host if an accepted job has not finished by a deadline, and both attempts are billed if both land. The live table below shows how much choosing a host can matter:

Per second, before VideoRouter's 2% platform fee. For tiered models each row compares the resolution tier with the widest host-to-host gap. Built 2026-10-02 from the live catalog.

A request using the fields together

{
  "model": "bytedance/seedance-2.5",
  "prompt": "the subject turns toward camera and smiles, gentle push-in",
  "start_image_url": "https://example.com/portrait.jpg",
  "duration_secs": 5,
  "resolution": "720p",
  "aspect_ratio": "9:16",
  "provider": {"sort": "price"}
}

Checklist before you ship

1. Send the shortest duration_secs that proves the idea, and log the snapped value.
2. Take tier strings from the model page for your host, then verify the file's real dimensions.
3. Pick one input mode per request: start image, references or editing.
4. Float unless you need a host-specific capability; if you pin, decide whether you want fallbacks.

New to the API? Start with how to call it or the quickstart, then create a key.

Frequently asked questions

Keep reading

• Seedance 2.5 vs 2.0 vs Fast vs Mini — Choosing a Variant for API Use
• Seedance Reference-to-Video API: Images, Video, Audio Refs
• Seedance Image-to-Video API: start_image_url Prompts & Setup
• Seedance vs Kling vs Veo API: How to Choose by Workload