> ## Documentation Index
> Fetch the complete documentation index at: https://apixo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Seedance 2.5 API: Draft-to-1080p Video Generation
> Multimodal video generation API with a cost-efficient 480p Draft-to-1080p Final workflow, dynamic duration, first-and-last-frames, and omni-reference modes
## Overview
Seedance 2.5 is a video generation model for prompt-only video, first-and-last-frame animation, and multimodal reference workflows. Use this page when you need up to 30-second video generation with optional image, video, or audio references, or when you want to review low-cost 480p Drafts before producing selected results in 1080p.
| Capability | Value |
| - | - |
| Model ID | `seedance-2-5` |
| Modes | `text-to-video`, `first_and_last_frames`, `omni_reference` |
| Prompt | Required non-empty string; no API-side maximum length |
| Resolutions | `480p`, `720p`, `1080p` |
| Durations | Any integer from `4` through `30` seconds, or `-1` for dynamic duration |
| Aspect ratios | `auto`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9` |
| Reference images | 1-2 URLs for `first_and_last_frames`; 1-30 URLs for `omni_reference` |
| Reference video/audio | 1-10 URLs each for `omni_reference`; each file 2-30 seconds, total max 30 seconds per media type |
| Draft workflow | Generate a 480p Draft with `draft=true`, then create one or more 1080p Finals with `draft_task_id` |
| Output | Video URL array in `resultJson.resultUrls` |
Prompts that describe video-editing actions may be treated as video editing by the generation system. This includes phrases such as `edit video`, `add`, `add to`, `delete`, `remove`, `modify`, `replace`, `change to`, and Chinese phrases such as `编辑视频`, `增加`, `加上`, `删除`, `去掉`, `修改`, `替换`, or `改成`. For these prompts, set `duration` to `-1` and `aspect_ratio` to `auto`.
## Endpoint and authentication
Base URL:
```text theme={null}
https://api.apixo.ai/api/v1
```
| Method | Endpoint | Purpose |
| - | - | - |
| `POST` | `/generateTask/seedance-2-5` | Submit a generation task |
| `GET` | `/statusTask/seedance-2-5?taskId={taskId}` | Poll task status and retrieve results |
All requests require your APIXO API key:
```http theme={null}
Authorization: Bearer YOUR_API_KEY
```
Submit requests also require:
```http theme={null}
Content-Type: application/json
```
## Recommended: Draft first, Final second
**Save about 57% on a four-candidate workflow and roughly double iteration efficiency.** Generate inexpensive 480p Drafts for review, then convert only the selected Draft into a 1080p Final. This avoids repeatedly paying for full-resolution candidates while preserving the Draft's generation conditions, composition, motion, duration, and aspect ratio for the Final generation.
### Step 1: Generate a 480p Draft
Set `input.draft=true`. `resolution` may be omitted because Draft generation is fixed to `480p`.
```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/seedance-2-5" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_type": "async",
"input": {
"draft": true,
"mode": "text-to-video",
"prompt": "a blue ball rolls from left to right across a white table",
"duration": -1,
"aspect_ratio": "16:9",
"sound": true
}
}'
```
Poll the returned task ID until the Draft reaches `state=success`. Keep this APIXO task ID; it is the value used as `draft_task_id` in the next step.
### Step 2: Generate the 1080p Final
Send the successful Draft task ID. `resolution` may be omitted because Final generation is fixed to `1080p`.
```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/seedance-2-5" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_type": "async",
"input": {
"draft_task_id": "DRAFT_TASK_ID",
"output_format": "mp4",
"watermark": false
}
}'
```
The Final inherits the Draft's generation conditions. Do not resend `prompt`, reference media, `mode`, `duration`, `aspect_ratio`, or `sound`. A successful Draft can be reused to create multiple independent Finals for 7 days. Each Final returns its own task ID and is charged to the API key that submits that Final request.
### Why this workflow saves about 57%
For a no-video-reference workflow that compares four candidates of the same duration:
```text theme={null}
Four direct 1080p candidates: 4 × $0.800 = $3.200 per output second
Four 480p Drafts + one 1080p Final: (4 × $0.140) + $0.800 = $1.360 per output second
Savings: ($3.200 - $1.360) / $3.200 = 57.5%
```
The exact savings depend on candidate count, output duration, and whether video references are used. The largest efficiency gain comes from reviewing several Drafts and generating 1080p only for selected results.
## Copy-paste async quickstart
This minimal request submits a text-to-video task and returns a `taskId`.
```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/seedance-2-5" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_type": "async",
"input": {
"mode": "text-to-video",
"prompt": "a cinematic night city drone shot with dramatic lighting",
"resolution": "720p",
"duration": 8,
"aspect_ratio": "16:9",
"sound": true
}
}'
```
Successful response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678"
}
}
```
Save the `taskId`; you need it to poll for the final result.
## Poll for result
```bash theme={null}
curl -X GET "https://api.apixo.ai/api/v1/statusTask/seedance-2-5?taskId=task_12345678" \
-H "Authorization: Bearer YOUR_API_KEY"
```
Processing response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"state": "processing",
"createTime": 1767965610929
}
}
```
Success response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"state": "success",
"resultJson": "{\"resultUrls\":[\"https://file.apixo.ai/video.mp4\"]}",
"createTime": 1767965610929,
"completeTime": 1767965890929,
"costTime": 280000
}
}
```
Failed response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"state": "failed",
"failCode": "GenerationError",
"failMsg": "Generation failed",
"createTime": 1767965610929,
"completeTime": 1767965620132
}
}
```
Parse `resultJson` after `state` becomes `success`:
```javascript theme={null}
const payload = JSON.parse(data.resultJson);
const videoUrls = payload.resultUrls;
```
## Request body
### Text-to-video
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "text-to-video",
"prompt": "a slow tracking shot through a foggy pine forest at dawn",
"resolution": "720p",
"duration": 10,
"aspect_ratio": "16:9",
"sound": true
}
}
```
### Dynamic duration
Use `duration=-1` when you want the generation system to decide the final output length.
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "text-to-video",
"prompt": "a continuous cooking tutorial scene with natural camera transitions",
"resolution": "720p",
"duration": -1,
"aspect_ratio": "auto",
"sound": true
}
}
```
### First-and-last-frames
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "first_and_last_frames",
"prompt": "turn the still frames into a smooth cinematic camera move",
"image_urls": [
"https://example.com/frame-start.png",
"https://example.com/frame-end.png"
],
"resolution": "720p",
"duration": 5,
"aspect_ratio": "auto",
"sound": true
}
}
```
### Omni-reference
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "omni_reference",
"prompt": "create a stylish product ad using the visual references and voice rhythm",
"image_urls": [
"https://example.com/product-shot.png"
],
"video_urls": [
"https://example.com/ref-motion.mp4"
],
"audio_urls": [
"https://example.com/ref-audio.mp3"
],
"resolution": "480p",
"duration": 6,
"aspect_ratio": "auto",
"sound": true,
"output_format": "mp4",
"watermark": false
}
}
```
## Parameters
Result delivery mode. Omit this field or use `async` for polling with `statusTask`, or use `callback` for webhook delivery.
Required when `request_type` is `callback`. Must be a public HTTPS URL that can receive the final task payload. See [Webhooks](/docs/api-reference/webhooks).
Seedance 2.5 input parameters.
Set to `true` to generate a 480p Draft. When enabled, `resolution` defaults to `480p` and any other explicit resolution is rejected. Cannot be used together with `draft_task_id`.
APIXO task ID of a successful Seedance 2.5 Draft. Creates a 1080p Final that inherits the Draft's generation conditions. The Draft must be no more than 7 days old and may be reused for multiple Finals. Cannot be used together with `draft=true`.
Generation mode. Required for ordinary generation and Draft creation; omit it when `draft_task_id` is used. Supported values: `text-to-video`, `first_and_last_frames`, `omni_reference`.
Text prompt describing the desired video. Required for ordinary generation and Draft creation; inherited and therefore prohibited when `draft_task_id` is used. The API trims whitespace and rejects empty prompts. Prompts with video-editing intent such as `edit video`, `add`, `remove`, `modify`, `replace`, `change to`, `编辑视频`, `增加`, `加上`, `删除`, `去掉`, `修改`, `替换`, or `改成` may require `duration=-1` and `aspect_ratio=auto`. Maximum length: 10000 characters.
Output resolution. Ordinary generation defaults to `720p`. Draft generation is fixed to `480p`; Final generation with `draft_task_id` is fixed to `1080p`. Values are trimmed and normalized to lowercase.
Output duration in seconds. Supports integers from `4` through `30`, including numeric strings such as `"10"`, or `-1` for dynamic duration. When `duration=-1`, the request is pre-charged as 30 seconds of output and settled by actual output duration after success.
Output aspect ratio. Supported values: `auto`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`. Use `auto` for `first_and_last_frames` and for prompts that may trigger video editing.
Whether to generate audio with the video. Must be a boolean when provided.
Output container format. Supported values: `mp4`, `mov`.
Whether to add a watermark. Must be a boolean when provided.
Enables content safety checking for this request. API requests default to `false`; the APIXO playground may use its own default. Must be a boolean when provided.
Reference image URLs. Required for `first_and_last_frames` with 1-2 images. Optional for `omni_reference` with up to 30 images.
Reference video URLs for `omni_reference`. Supports 1-10 URLs when provided. Each video must be 2-30 seconds, and total reference video duration cannot exceed 30 seconds.
Reference audio URLs for `omni_reference`. Supports 1-10 URLs when provided. Each audio file must be 2-30 seconds, and total reference audio duration cannot exceed 30 seconds.
| Mode | Required media | Optional media | Billing note |
| - | - | - | - |
| `text-to-video` | None | None | Uses the no-video-reference rate. |
| `first_and_last_frames` | `image_urls` with 1-2 images | None | Uses the no-video-reference rate and requires `aspect_ratio=auto`. |
| `omni_reference` | At least one of `image_urls`, `video_urls`, or `audio_urls` | Any supported reference media | Uses video-reference billing when `video_urls` is provided. |
### Draft and Final input rules
| Request | Required input | Allowed additional input | Fixed resolution |
| - | - | - | - |
| 480p Draft | `draft=true`, plus the normal mode-specific generation fields | All ordinary fields supported by the selected mode | `480p` |
| 1080p Final | `draft_task_id` | `resolution`, `output_format`, `watermark` | `1080p` |
For Final requests, generation fields such as `prompt`, reference URLs, `mode`, `duration`, `aspect_ratio`, `sound`, and `nsfw_checker` are inherited from the Draft and must not be resent. `draft=true` and `draft_task_id` are mutually exclusive.
In `omni_reference`, audio-only requests are supported. The video-reference rate only applies when `video_urls` is provided.
Use public, directly accessible URLs for all reference media. Video and audio durations are checked before the task is submitted.
`image_urls` examples use URL strings. The API also accepts object items with a non-empty `url` field and normalizes them to URL strings.
## Video-editing prompt behavior
Seedance 2.5 can infer a video-editing task from the prompt text. If your prompt asks the model to edit, add, remove, modify, replace, or change parts of an existing video, send the request with:
```json theme={null}
{
"duration": -1,
"aspect_ratio": "auto"
}
```
This applies even when the public `mode` is still `omni_reference`. Examples of prompt terms that can trigger this behavior include `edit video`, `add`, `add to`, `delete`, `remove`, `modify`, `replace`, `change to`, `编辑视频`, `增加`, `加上`, `删除`, `去掉`, `修改`, `替换`, and `改成`.
## Response format
### Submit task response
`POST /generateTask/seedance-2-5` returns a task ID when the task is accepted:
API status code. `200` means the task was accepted.
Human-readable status message.
Unique task identifier used with the status endpoint.
### Status response fields
Unique task identifier.
Current task state: `pending`, `processing`, `success`, or `failed`.
JSON string containing generated video URLs in `resultUrls`. Present when `state` is `success`.
Machine-readable failure code. Present when `state` is `failed`.
Human-readable failure message. Present when `state` is `failed`.
Task creation timestamp in Unix milliseconds.
Task completion timestamp in Unix milliseconds. Present after completion.
Processing duration in milliseconds. Present after completion when timing data is available.
Final billing snapshot. Present only on successful terminal responses for `seedance-2-5` tasks submitted with `duration=-1`.
Settlement status. For this final snapshot the value is always `final`.
Total duration of all input videos, in seconds, rounded half up to 3 decimal places.
Actual generated output video duration, in seconds, rounded half up to 3 decimal places.
Final billable duration in seconds. For this model, this is always `inputVideoSeconds + outputVideoSeconds`.
Duration unit. The value is `second`.
Rounding rule used for duration fields. The value is `round half up to 3 decimal places`.
Number of input videos included in `inputVideoSeconds`.
Number of output videos included in `outputVideoSeconds`.
## Webhook callback mode
Use callback mode when your backend should receive the final result automatically instead of polling.
```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/seedance-2-5" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_type": "callback",
"callback_url": "https://your-server.com/webhooks/apixo",
"input": {
"mode": "first_and_last_frames",
"prompt": "turn the still frames into a smooth cinematic camera move",
"image_urls": [
"https://example.com/frame-start.png",
"https://example.com/frame-end.png"
],
"resolution": "720p",
"duration": 5,
"aspect_ratio": "auto",
"sound": true
}
}'
```
The callback payload uses the same top-level shape as status polling with `code`, `message`, and `data`. Successful callbacks include the final `state` and `resultJson`. For `duration=-1` tasks, successful terminal callbacks include the same `data.billing` object returned by status polling. See [Webhooks](/docs/api-reference/webhooks) for delivery requirements and retry behavior.
## Billing
Seedance 2.5 is billed per second. The selected `resolution` and whether `omni_reference` includes `video_urls` determine the per-second unit price.
For iterative production, generate 480p Drafts first and create 1080p only from the selected Draft. In the four-candidate example above, this reduces generation spend by **57.5%** and can roughly double iteration efficiency by avoiding repeated full-resolution generations.
| Configuration | APIXO price |
| - | - |
| `480p`, without video reference | `$0.140 / second` |
| `480p`, with video reference | `$0.085 / second` |
| `720p`, without video reference | `$0.315 / second` |
| `720p`, with video reference | `$0.190 / second` |
| `1080p`, without video reference | `$0.800 / second` |
| `1080p`, with video reference | `$0.500 / second` |
Formula without video reference:
```text theme={null}
total cost = output duration * unit price
```
Formula with video reference:
```text theme={null}
total cost = (output duration + total reference video duration) * unit price
```
`text-to-video` and `first_and_last_frames` always use the without-video-reference rate. `omni_reference` uses the with-video-reference rate only when `video_urls` is provided.
When `duration=-1`, APIXO pre-charges the output portion as 30 seconds. After a successful task, APIXO settles by the actual generated output duration and refunds any overcharged output seconds. If `video_urls` are provided, reference video seconds are still included in billable seconds.
When the source Draft uses `duration=-1`, APIXO uses its final actual output duration for the 1080p Final, rounded half up to 3 decimal places. For example, a Draft settled at `10.080` seconds uses `10.080` output seconds when calculating the Final pre-charge. If the Draft used video references, the original total reference-video duration is added to the actual output duration before applying the 1080p video-reference rate.
Successful terminal `duration=-1` responses return the final settled seconds under `data.billing`:
```json theme={null}
{
"billing": {
"settlementState": "final",
"inputVideoSeconds": 25.371,
"outputVideoSeconds": 25.042,
"totalBillableSeconds": 50.413,
"unit": "second",
"rounding": "round half up to 3 decimal places",
"inputVideoCount": 1,
"outputVideoCount": 1
}
}
```
All duration fields in `billing` use seconds and are rounded half up to 3 decimal places. `inputVideoSeconds` is the sum of all input video durations, and `inputVideoCount` is the number of input videos included in that sum. `outputVideoSeconds` is the actual generated output duration. `totalBillableSeconds` is always `inputVideoSeconds + outputVideoSeconds`. This `billing` object appears only after successful final settlement, is also included in successful callback payloads, and remains stable on repeated polling.
For current route and market comparison pricing, see [Pricing](https://apixo.ai/pricing).
## Latency and polling
Seedance 2.5 tasks are asynchronous. Actual latency may vary by prompt complexity, duration mode, resolution, reference media accessibility, route queue load, and storage transfer time.
| Workload | Typical generation time | Recommended first poll | Poll interval |
| - | - | - | - |
| Text-to-video or first-and-last-frames | Varies by prompt, duration, and resolution | 120s after task creation | 10s-20s |
| Omni-reference with image/video/audio inputs | Varies by reference count, media duration, and accessibility | 180s after task creation | 10s-20s |
For production workloads, use callback mode to avoid frequent polling while video tasks run.
Result URLs are temporary. Download and store important outputs promptly after task completion.
Rate limits and concurrency can vary by account, API key, and route. If you receive `429`, slow down requests and retry with backoff. For account-level details, see [System APIs](/docs/api-reference/system).
## Errors and troubleshooting
### HTTP errors
| Code | Meaning | What to do |
| - | - | - |
| `400` | Invalid request body, missing `input`, unsupported `mode`, missing `prompt`, invalid `resolution`, invalid `duration`, invalid `aspect_ratio`, invalid boolean value, invalid `output_format`, or invalid media array | Fix the request before retrying |
| `401` | Missing or invalid API key | Check the `Authorization` header |
| `402` | Insufficient balance or quota | Add balance or switch account/key |
| `403` | Key or route cannot access the model | Check permissions and route strategy |
| `404` | Task not found when polling | Check the `taskId` |
| `429` | Rate limit or concurrency limit reached | Retry with exponential backoff |
| `500` | Server error or unknown task failure | Retry with backoff |
| `502` | Generation service error | Retry with backoff |
| `504` | Generation timeout | Retry or use callback mode for long-running jobs |
### Validation notes
| Condition | Backend behavior |
| - | - |
| Missing `input` | Request fails before task creation. |
| Missing, non-string, or empty `prompt` | Request fails before task creation. |
| Missing `mode` | Request fails before task creation. |
| Unsupported `mode` | Request fails before task creation. Supported values are `text-to-video`, `first_and_last_frames`, and `omni_reference`. |
| Missing `resolution` | Defaults to `720p`. |
| Unsupported `resolution` | Request fails before task creation. Supported values are `480p`, `720p`, and `1080p`. |
| Missing `duration` | Defaults to `5`. |
| `duration` outside `4` through `30` and not `-1` | Request fails before task creation. |
| `duration=-1` | The task is pre-charged as 30 seconds of output duration, then settled by actual output duration after success. |
| `draft=true` with omitted `resolution` | The request generates a 480p Draft. |
| `draft=true` with a resolution other than `480p` | Request fails before task creation. |
| `draft=true` together with `draft_task_id` | Request fails before task creation. |
| `draft_task_id` with omitted `resolution` | The request generates a 1080p Final. |
| `draft_task_id` with a resolution other than `1080p` | Request fails before task creation. |
| `draft_task_id` with inherited generation fields | Request fails before task creation. Only `resolution`, `output_format`, and `watermark` may accompany `draft_task_id` inside `input`. |
| `draft_task_id` references an unsuccessful, expired, or incompatible task | Request fails before charging the Final. |
| Missing `aspect_ratio` | Defaults to `auto`. |
| Unsupported `aspect_ratio` | Request fails before task creation. |
| Video-editing prompt intent with `duration` not set to `-1` or `aspect_ratio` not set to `auto` | The generation task can fail; use `duration=-1` and `aspect_ratio=auto` for these prompts. |
| `sound`, `watermark`, or `nsfw_checker` is not a boolean | Request fails before task creation. |
| Unsupported `output_format` | Request fails before task creation. Supported values are `mp4` and `mov`. |
| `first_and_last_frames` without `image_urls` | Request fails before task creation. |
| `first_and_last_frames` with more than 2 images | Request fails before task creation. |
| `first_and_last_frames` with `aspect_ratio` other than `auto` | Request fails before task creation. |
| `omni_reference` without `image_urls`, `video_urls`, or `audio_urls` | Request fails before task creation. |
| `omni_reference` with more than 30 images, 10 videos, or 10 audio files | Request fails before task creation. |
| Reference video or audio shorter than 2 seconds or longer than 30 seconds | Request fails before task creation. |
| Total reference video duration or total reference audio duration over 30 seconds | Request fails before task creation. |
### Task failure codes
`failCode` is generated from APIXO's mapped generation error. Common values include:
| Fail code | Meaning | What to do |
| - | - | - |
| `SensitiveContent` | Prompt or input/output content was rejected by safety checks | Change the prompt or reference media |
| `PromptInvalid` | Prompt was invalid or rejected during generation | Rewrite the prompt and retry |
| `ImageFormatIncorrect` | Reference image format could not be processed | Use a public, direct image URL in a common image format |
| `RateLimited` | Rate limit was reached | Retry with exponential backoff |
| `Timeout` | Generation timeout | Retry later or use callback mode |
| `StreamError` | A generation service error occurred | Retry with backoff |
| `Unknown error` | An unmapped failure occurred | Retry with backoff or contact support with the `taskId` |
See [Error Codes](/docs/api-reference/errors) for the full error reference.
## Related links
* [Generation API Overview](/docs/models)
* [Video Models](/docs/models/video)
* [Generate Task](/docs/api-reference/generate-task)
* [Status Task](/docs/api-reference/status-task)
* [Webhooks](/docs/api-reference/webhooks)
* [Error Codes](/docs/api-reference/errors)
* [Parameter Specification](/docs/api-reference/parameters)
* [Routing Strategies](/docs/concepts/routing-strategies)
* [Try Seedance 2.5 in the APIXO Playground](https://apixo.ai/models/seedance-2-5)
* [Pricing](https://apixo.ai/pricing)