> ## 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
> ByteDance multimodal video generation API with dynamic duration, first-and-last-frames, and omni-reference workflows
## Overview
Seedance 2.5 is a ByteDance 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.
| 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` |
| 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 |
| 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
```
## 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.
Generation mode. Supported values: `text-to-video`, `first_and_last_frames`, `omni_reference`.
Text prompt describing the desired video. The API trims whitespace, rejects empty prompts, and does not enforce a maximum prompt length. Prompts with video-editing intent such as `edit video`, `add`, `remove`, `modify`, `replace`, `change to`, `编辑视频`, `增加`, `加上`, `删除`, `去掉`, `修改`, `替换`, or `改成` may require `duration=-1` and `aspect_ratio=auto`.
Output resolution. Supported values: `480p`, `720p`. 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. |
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.
## 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`. 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.
| 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` |
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.
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` and `720p`. |
| 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. |
| 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)