switch_heading
Seedance 2.5 API Documentation
Generate Seedance 2.5 and Seedance 2.5 Flash videos through API v3: text-to-video, reference images, video and audio, first/last frames, video editing, and 4K output.
API v3 is a separate endpoint for Seedance 2.5 only. Existing /v1 and /v2 integrations keep working exactly as before; switch to /v3 only when you want Seedance 2.5.
Quick Start
| 1 | curl -X POST 'https://seedanceapi.org/v3/generate' \ |
| 2 | -H 'Authorization: Bearer YOUR_API_KEY' \ |
| 3 | -H 'Content-Type: application/json' \ |
| 4 | -d '{ |
| 5 | "model": "seedance-2.5", |
| 6 | "prompt": "A cinematic aerial shot over a coastline at golden hour", |
| 7 | "aspect_ratio": "16:9", |
| 8 | "resolution": "720p", |
| 9 | "duration": 10 |
| 10 | }' |
Authentication
All API requests require a Bearer token in the Authorization header.
Important: Get your API key from the API Keys page in your dashboard. Keep it on your server and never ship it in browser code. → Get Your API Key
| 1 | Authorization: Bearer YOUR_API_KEY |
Generation modes
| Mode | Fields to send |
|---|---|
| Text to video | prompt + aspect_ratio |
| Reference generation (images, video, audio) | prompt + image_urls / reference_video_urls / reference_audio_urls |
| First / last frame | prompt + first_frame_url (+ last_frame_url) |
| Video editing | prompt + reference_video_urls (1) + duration: -1 + aspect_ratio: "adaptive" |
Pricing (credits)
Credits are charged per second of video and depend on the model, resolution, and whether you send reference videos. The amount is deducted when the task is created and refunded automatically if it fails.
Need to recharge credits? → Top up on the pricing page. 1 USD = 100 credits.
Seedance 2.5
Highest quality, supports 480p, 720p, and native 4K.
| Resolution | Input | Rate | Example |
|---|---|---|---|
| 480p | Text / images / audio | 28 credits / s | 10s output = 280 credits |
| 480p | With reference video | 17 credits / s | 5s reference + 10s output = 255 credits |
| 720p | Text / images / audio | 63 credits / s | 10s output = 630 credits |
| 720p | With reference video | 38 credits / s | 5s reference + 10s output = 570 credits |
| 4k | Text / images / audio | 251 credits / s | 10s output = 2510 credits |
| 4k | With reference video | 155 credits / s | 5s reference + 10s output = 2325 credits |
Seedance 2.5 Flash
Faster and cheaper, supports 480p and 720p.
| Resolution | Input | Rate | Example |
|---|---|---|---|
| 480p | Text / images / audio | 18.5 credits / s | 10s output = 185 credits |
| 480p | With reference video | 11.5 credits / s | 5s reference + 10s output = 173 credits |
| 720p | Text / images / audio | 41 credits / s | 10s output = 410 credits |
| 720p | With reference video | 25.5 credits / s | 5s reference + 10s output = 383 credits |
With reference_video_urls, billing uses the lower video-input rate on reference video seconds plus output seconds. Video editing (duration -1) bills twice the input video length. Totals are rounded up to a whole credit.
API Endpoints
/v3/generateStart a Seedance 2.5 or Seedance 2.5 Flash job. The call returns a task_id right away; poll /v3/status or pass callback_url to get the result.
Request Body
Text prompt (required, up to 5000 characters).
seedance-2.5 (default) or seedance-2.5-flash. Defaults to seedance-2.5.
Output length in seconds: any integer from 4 to 30. Use -1 for video editing, where the output keeps the input video's length. Defaults to 5.
Seedance 2.5: 480p, 720p, or 4k. Seedance 2.5 Flash: 480p or 720p. 1080p is not available. Defaults to 720p.
16:9, 9:16, 4:3, 3:4, or adaptive. Video editing requires adaptive. Defaults to 16:9.
Up to 4 reference image URLs (http/https). Describe how each image should be used in the prompt.
Image URL used as the first frame. Cannot be combined with image_urls, reference_video_urls, or reference_audio_urls.
Optional image URL used as the last frame. Requires first_frame_url.
Up to 3 reference video URLs, 30 seconds in total. For video editing, send exactly one video between 4 and 30 seconds long.
Up to 3 reference audio URLs, for example music or a voice track.
Generate a soundtrack together with the video. Defaults to true.
Let the model look up the web for subjects in the prompt. Defaults to false.
Optional webhook called when the task finishes (public URL; localhost is not allowed).
Optional: allow the result to appear in the public gallery.
Text to video
| 1 | { |
| 2 | "model": "seedance-2.5", |
| 3 | "prompt": "A slow dolly shot through a neon-lit street in the rain", |
| 4 | "aspect_ratio": "16:9", |
| 5 | "resolution": "720p", |
| 6 | "duration": 10 |
| 7 | } |
Reference image + audio
| 1 | { |
| 2 | "model": "seedance-2.5", |
| 3 | "prompt": "The woman in the reference image dances to the beat of the reference audio in a sunlit studio", |
| 4 | "image_urls": ["https://example.com/character.jpg"], |
| 5 | "reference_audio_urls": ["https://example.com/beat.mp3"], |
| 6 | "aspect_ratio": "9:16", |
| 7 | "resolution": "720p", |
| 8 | "duration": 8 |
| 9 | } |
First and last frame (Flash)
| 1 | { |
| 2 | "model": "seedance-2.5-flash", |
| 3 | "prompt": "The flower bud slowly opens into full bloom", |
| 4 | "first_frame_url": "https://example.com/bud.jpg", |
| 5 | "last_frame_url": "https://example.com/bloom.jpg", |
| 6 | "resolution": "480p", |
| 7 | "duration": 6 |
| 8 | } |
Video editing
| 1 | { |
| 2 | "model": "seedance-2.5", |
| 3 | "prompt": "Change the season to winter with falling snow; keep the camera motion", |
| 4 | "reference_video_urls": ["https://example.com/input-12s.mp4"], |
| 5 | "aspect_ratio": "adaptive", |
| 6 | "duration": -1, |
| 7 | "resolution": "720p" |
| 8 | } |
4K output
| 1 | { |
| 2 | "model": "seedance-2.5", |
| 3 | "prompt": "Macro shot of morning dew rolling off a green leaf", |
| 4 | "aspect_ratio": "16:9", |
| 5 | "resolution": "4k", |
| 6 | "duration": 5 |
| 7 | } |
Responses
Task created
| 1 | { |
| 2 | "code": 200, |
| 3 | "message": "success", |
| 4 | "data": { |
| 5 | "task_id": "n90a1b2c3d4e5f6sd25", |
| 6 | "status": "IN_PROGRESS", |
| 7 | "consumed_credits": 630 |
| 8 | } |
| 9 | } |
/v3/statusPoll by task_id until status is SUCCESS or FAILED. Only tasks created with /v3/generate are returned here.
Query Parameters
Task id returned by POST /v3/generate (ends with sd25).
Example Request
| 1 | curl -X GET 'https://seedanceapi.org/v3/status?task_id=n90a1b2c3d4e5f6sd25' \ |
| 2 | -H 'Authorization: Bearer YOUR_API_KEY' |
Tip: When status is SUCCESS, data.response is an array of video URLs; use data.response[0] for the first URL. Download and store the file if you need to keep it.
| 1 | const videoUrl = data.response[0]; |
Responses
| 1 | { |
| 2 | "code": 200, |
| 3 | "message": "success", |
| 4 | "data": { |
| 5 | "task_id": "n90a1b2c3d4e5f6sd25", |
| 6 | "status": "SUCCESS", |
| 7 | "consumed_credits": 630, |
| 8 | "created_at": "2026-11-19T10:30:00Z", |
| 9 | "type": "seedance-2.5-t2v", |
| 10 | "request": { |
| 11 | "model": "seedance-2.5", |
| 12 | "prompt": "A slow dolly shot…", |
| 13 | "aspect_ratio": "16:9", |
| 14 | "duration": 10 |
| 15 | }, |
| 16 | "response": [ |
| 17 | "https://cdn.example.com/videos/n90a1b2c3d4e5f6sd25.mp4" |
| 18 | ], |
| 19 | "error_message": null |
| 20 | } |
| 21 | } |
API Playground
Try the API in the browser. Replace YOUR_API_KEY with your real key. Each successful call is billed.
Error Codes
| Status | When it happens |
|---|---|
| 400 Bad Request | A parameter is missing or invalid, for example an unsupported model, resolution, aspect_ratio, duration, or media URL. The message explains which one. |
| 401 Unauthorized | API key missing or invalid. |
| 402 | Not enough credits for this task. |
| 404 Not Found | The task does not exist, or it was not created with /v3/generate. |
| 500 Internal Server Error | Server error. Retry later; failed tasks are refunded automatically. |