Seedance 2.5
Generate a video with sound from a prompt, frames or reference images, videos and audio, or edit or extend a video, billed by the output length.
Seedance 2.5 (product seedance) generates a video from a prompt, a first and last frame, or reference images, videos and audio, and can edit or extend a video you already have. The output has sound by default. Each mode has its own page with its parameters, price and request examples:
mode | What it does | Docs |
|---|---|---|
text_to_video | Text to video: generated from a prompt alone. | Text to Video |
image_to_video | Image to video: from a first frame, optionally with a last frame. | Image to Video |
reference_to_video | Reference to video: a new video from reference images, videos and audio. | Reference to Video |
video_edit | Video edit: an existing video changed as your prompt says. | Video Edit |
video_extension | Video extension: new footage that continues an existing video, or leads into it. | Video Extension |
This page has the rules every mode shares.
Create a task
https://api.nanoapi.ai/v1/tasksUse the shared create endpoint with model: "seedance-2.5" and one of the modes above. Parameters every mode takes:
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | Yes | seedance-2.5. |
mode | string | Yes | text_to_video, image_to_video, reference_to_video, video_edit or video_extension. |
resolution | string | Yes | 480p, 720p or 1080p. |
aspect_ratio | string | Yes in text_to_video, image_to_video and reference_to_video; not accepted by video_edit and video_extension | auto, 21:9, 16:9, 4:3, 1:1, 3:4 or 9:16. auto follows the first frame or the reference images and videos; with nothing to follow (text_to_video, or reference audio only), it gives 16:9. video_edit and video_extension follow the video you send. |
duration | integer | Yes; not accepted by video_edit | Output length in seconds, 4–30. It's what you pay for, see Pricing. For video_extension, the length of the new part. A video_edit output is as long as the video you edit, see Video Edit. |
generate_audio | boolean | No | Whether the output has sound. Default true. The price is the same either way. |
webhook_url | string | No | Notified when the task succeeds or fails. See Webhooks. |
- Required parameters: every mode needs
resolution;text_to_video,image_to_videoandreference_to_videoalso needaspect_ratio, and every mode exceptvideo_editneedsduration. Whetherprompt,image_urls,video_url,video_urls,audio_urlsandextension_modeare required, optional or not accepted depends on the mode: see its page. - Parameter checks: a parameter that breaks the mode's rules (for example
image_urlswithtext_to_video,durationoraspect_ratiowithvideo_edit, orvideo_extensionwithoutextension_mode) returns400 invalid_requestwithparamset to that parameter, and no task is created. - Response:
200 OK, the same short task as for every model (see Create a task: Response), withdata.modelseedance-2.5. Keepdata.idto get the result. - The endpoint usually responds in under 1 second, and the cost is frozen within a few seconds.
Get the result
A video usually takes several minutes (about 4–6 at 480p). Once the task has finished (succeeded or failed), get the result either way:
- Webhook (recommended in production): if you passed
webhook_url, the full task is pushed to it once when the task finishes. See Webhooks. - Polling: call
GET /v1/tasks/{task_id}withdata.idat most once every 15 seconds untilstatusissucceededorfailed. Check several tasks at once withidsin List tasks.
| Field | Seedance 2.5 |
|---|---|
outputs[0].url | The generated video, with sound when generate_audio is true (the default). For video_extension, only the new part, see Video Extension. |
outputs[0].preview_url | A silent, compressed copy for previews, see Outputs. |
billing.billed_seconds | The duration; for video_edit, the actual output length. |
input | The parameters you sent. generate_audio is always there (true if you didn't send it). |
On failure the frozen amount is returned in full and the reason is in data.error.type, see Errors. Every field is described in The task object.
Media
All media is passed as public http(s) URLs. There's no upload endpoint: host the files yourself. URLs are at most 4096 characters, must download directly and can't point to localhost or private, loopback or reserved addresses.
| Parameter | What it is | Modes |
|---|---|---|
image_urls | Images: a first and last frame (up to 2), or reference images (up to 30). | image_to_video, reference_to_video, video_edit |
video_url | The video to edit or extend. | video_edit, video_extension |
video_urls | Reference videos, up to 3. | reference_to_video |
audio_urls | Reference audio (mp3, wav, m4a and other common formats), up to 9. | reference_to_video |
Which ones a mode requires is on its page. The files must meet these requirements:
| Requirement | Otherwise the task fails with |
|---|---|
The video to edit (video_edit) 4–30 seconds | video_too_short / video_too_long |
The video to extend (video_extension) and each reference video at most 30 seconds | video_too_long |
| The reference videos together at most 30 seconds | video_too_long |
| Each reference audio file, and all of them together, at most 30 seconds | invalid_media |
image_to_video: the first and last frames both landscape or both portrait (not checked when one of them is square) | invalid_media |
A file that can't be downloaded or read (corrupt, unsupported format) fails the task with invalid_media.
Seedance 2.5 reads every file only after the task is submitted for generation, a few seconds after creation, once the cost has been frozen: none of the above is checked when the task is created. If a file can't be used, the frozen amount is returned in full. Keep every link reachable until the task finishes, including links that expire.
Referring to files in the prompt
In prompt | Refers to |
|---|---|
@Image1, @Image2, … | The images in image_urls, in order. |
@Video1, @Video2, … | The videos: video_url first, then the video_urls entries in order. video_edit: @Video1 is the video to edit. reference_to_video: @Video1 is the first reference video. |
@Audio1, @Audio2, … | The audio files in audio_urls, in order. |
Pricing
cost = duration × price per second of the mode and resolutionLoading the current prices…
Billed seconds are the duration you ask for (4–30); for video_extension, the length of the new part. They don't depend on your images, videos or audio: reference videos, reference audio and sound in the output (generate_audio) cost nothing extra.
video_edittakes noduration: 30 × the price per second is frozen first; when the task succeeds, the actual output length is charged and the rest returned. See Video Edit → Pricing.
Example: text_to_video at 720p with duration 5 freezes 5 × its 720p price per second and is charged the same when it succeeds; if it fails, all of it is returned. How freezing and charging work in general: Billing.
Except for video_edit, the price is known from the request alone, so you can show it before submitting: read the current prices from GET /v1/products, one prices row per mode and resolution (the row's mode). Prices change, so don't hard-code them. billing.frozen on the retrieved task is what counts.
Errors
Errors and failure reasons specific to Seedance 2.5. Every error of the create endpoint: Create a task → Errors; every failure reason: Failure reasons.
Create request errors: the request fails with an HTTP error and no task is created.
| Status | error.type | When | What to do |
|---|---|---|---|
400 | invalid_request | A parameter breaks the mode's rules: a required one is missing (prompt in text_to_video, video_edit and video_extension; video_url in video_edit and video_extension; extension_mode in video_extension), one the mode doesn't take was sent (duration or aspect_ratio with video_edit, aspect_ratio with video_extension, files the mode has no use for), there are too many files, or resolution, aspect_ratio, duration or extension_mode isn't an allowed value. param names the parameter and message says what's wrong, for example duration is not allowed for mode video_edit; the output is as long as the source video or image_urls is not allowed for mode text_to_video. Each mode's rules are on its page. | Fix the parameter param names and send the request again. |
Task failures: the create request succeeded (200) and the task later turned failed. There's no HTTP status: the reason is the task's error.type, from retrieving the task or the webhook.
error.type | When | What to do |
|---|---|---|
insufficient_balance | Your available balance can't cover duration × the price per second (for video_edit, 30 seconds of it). Within a few seconds of creating the task, nothing frozen. | Top up, then create the task again. |
spend_limit_exceeded | This task's cost would go over one of the key's spend limits. Within a few seconds of creating the task, nothing frozen. | Raise the limit in Console → API keys, or wait for it to reset, then create the task again. |
invalid_media | An image, video or audio file can't be downloaded or read (corrupt or an unsupported format), a reference audio file is longer than 30 seconds or they add up to more, or the image_to_video first and last frames aren't both landscape or both portrait. Found when the files are downloaded, a few seconds after the task is submitted. | Replace the file error.message points to and create the task again. |
content_policy | The prompt or a file breaks the content policy: adult content, or a protected likeness or copyrighted material (for example a photo of a public figure). This includes files turned down by the model provider's moderation. Found when the task is submitted or while it's generated; the frozen amount is returned in full. | Resubmitting it as is fails again: change the prompt or the file. |
video_too_short | The video to edit (video_edit) is shorter than 4 seconds. Found when the videos are downloaded, a few seconds after the task is submitted; started_at may be null. | Use a video of 4–30 seconds and create the task again. |
video_too_long | The video to edit or extend, or a reference video, is longer than 30 seconds, or the reference videos together are. Found when the videos are downloaded, a few seconds after the task is submitted; started_at may be null. | Trim the videos (or send fewer) so each is 30 seconds or less and the reference videos add up to 30 or less, then create the task again. |
error.message states the requirement, not your file's length (for example The video duration must be between 4 and 30 seconds.); the messages are listed under Messages. invalid_media, video_too_short and video_too_long happen after the cost is frozen: billing.frozen keeps the frozen amount, all of it is returned (refunded equals frozen) and billing.charged is "0.00".