> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toapis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# seedance-2.5-ext Video Generation

> Generate videos with the seedance-2.5-ext model, supporting reference images, reference videos, and reference audios

`seedance-2.5-ext` is the promotional-channel model in the Seedance 2.5 family, supporting text-to-video and multimodal reference generation:

* Text-to-video and reference-image generation
* Combined generation with reference videos and reference audios (video editing, extension, and first/last-frame modes are not supported)
* The API is asynchronous: submitting returns a `generation.task`; fetch results via the [video task status endpoint](../../tasks/video-status).

Requests are routed to the optimal upstream automatically: image-only or text-only requests go to the low-cost upstream; requests with reference videos, reference audios, or more than 10 reference images go to the full-capability upstream.

## Authentication

<ParamField header="Authorization" type="string" required>
  All requests require a Bearer Token. Get your key from the [API Key management page](https://toapis.com/console/token) and add it to the request header:

  ```text theme={null}
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Body

<ParamField body="model" type="string" default="seedance-2.5-ext" required>
  ToAPIs public model name. Always use `seedance-2.5-ext`.
</ParamField>

<ParamField body="prompt" type="string">
  Describe the scene, camera movement, subject actions, style, and sound atmosphere. When referencing assets, use tags like "image 1", "video 1", or "audio 1" in array order.
</ParamField>

<ParamField body="seconds" type="integer">
  Output video duration in seconds, from `10` to `30`. The compatible field `duration` is also accepted; do not pass both.

  <Warning>
    `15` seconds is not supported when the request carries reference videos, reference audios, or more than 10 reference images. Text-only requests and requests with at most 10 images are unaffected.
  </Warning>
</ParamField>

<ParamField body="size" type="string">
  Output aspect ratio. Supported: `16:9`, `9:16`, `4:3`, `3:4`, `1:1`. The compatible field `aspect_ratio` is also accepted.
</ParamField>

<ParamField body="resolution" type="string" default="720p">
  Output resolution. Fixed to `720p`.
</ParamField>

<ParamField body="reference_image" type="string">
  Public URL of a single reference image. For multiple images use `reference_images`.
</ParamField>

<ParamField body="reference_images" type="string[]">
  Array of reference image URLs, up to `30`. You can also use `image_with_roles` with `role` set to `reference_image`.
</ParamField>

<ParamField body="video_with_roles" type="object[]">
  Array of reference videos, up to `10`. Each item contains:

  * `url`: publicly accessible video URL
  * `role`: fixed to `reference_video`
</ParamField>

<ParamField body="audio_with_roles" type="object[]">
  Array of reference audios, up to `10`. Each item contains:

  * `url`: publicly accessible audio URL
  * `role`: fixed to `reference_audio`

  Audio cannot be the only input — the request must also include at least one reference image or reference video.
</ParamField>

<ParamField body="callback_url" type="string">
  ToAPIs task completion callback URL. See [Task Webhooks](/docs/en/api-reference/webhooks/task-webhooks).
</ParamField>

<ParamField body="client_business_id" type="string">
  Your order number or business task ID. Stored with the task; you can also query it via `GET /v1/videos/generations/{client_business_id}`.
</ParamField>

<ParamField body="trace_id" type="string">
  Custom trace ID for request tracking.
</ParamField>

## Media Combination Rules

| Request content | Supported | Notes |
| - | -: | - |
| Prompt only | Yes | Text-to-video |
| Up to 10 reference images | Yes | Low-cost upstream |
| 11–30 reference images | Yes | 15 seconds not supported |
| Reference video / reference audio | Yes | 15 seconds not supported; audio requires at least one image or video |
| First / last frame | No | Frame mode is not supported |
| Video edit / extend | No | Use `seedance-2-5` instead |

## Request Examples

### Text-to-Video

```bash theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "seedance-2.5-ext",
    "prompt": "Cinematic product close-up, camera slowly pushing in, natural indoor ambience.",
    "seconds": 10,
    "size": "16:9",
    "resolution": "720p"
  }'
```

### Reference Image

```bash theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "seedance-2.5-ext",
    "prompt": "The person in image 1 walks into a rainy night street, camera follows.",
    "seconds": 12,
    "size": "9:16",
    "reference_images": [
      "https://example.com/character.png"
    ]
  }'
```

### Video and Audio Combined Reference

```bash theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "seedance-2.5-ext",
    "prompt": "Use the character in image 1, the camera movement in video 1, and the rhythm of audio 1.",
    "seconds": 14,
    "size": "16:9",
    "reference_images": [
      "https://example.com/character.png"
    ],
    "video_with_roles": [
      {"url": "https://example.com/motion.mp4", "role": "reference_video"}
    ],
    "audio_with_roles": [
      {"url": "https://example.com/rhythm.mp3", "role": "reference_audio"}
    ]
  }'
```

## Response

<ResponseField name="id" type="string">Task ID for status queries.</ResponseField>
<ResponseField name="client_business_id" type="string">Returned when provided in the request.</ResponseField>
<ResponseField name="object" type="string">Fixed to `generation.task`.</ResponseField>
<ResponseField name="model" type="string">The model used for this request.</ResponseField>
<ResponseField name="status" type="string">`queued`, `in_progress`, `completed`, or `failed`.</ResponseField>
<ResponseField name="progress" type="integer">Task progress from `0` to `100`.</ResponseField>
<ResponseField name="created_at" type="integer">Creation timestamp.</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "tsk_vid_xxx",
    "object": "generation.task",
    "model": "seedance-2.5-ext",
    "status": "in_progress",
    "progress": 10,
    "created_at": 1781577600
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.