> ## 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 Video Generation

> Generate videos with seedance-2, seedance-2-fast, and seedance-2-mini

* Supports `seedance-2`, `seedance-2-fast`, and `seedance-2-mini`
* Supports text-to-video and multimodal reference-to-video; `seedance-2` and `seedance-2-fast` also support first-frame / first-last-frame workflows
* Supports combined image, video, and audio references; `seedance-2-mini` allows up to `9` images, `3` videos, and `3` audios
* Async task workflow: the submit API returns `generation.task`, and the completed result is fetched from the task status API

## Authorizations

<ParamField header="Authorization" type="string" required>
  All requests require Bearer Token authentication.

  Get your API Key from the [API Key Management Page](https://toapis.com/console/token).

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Body

<ParamField body="model" type="string" default="seedance-2" required>
  Video generation model name.

  Available models:

  * `seedance-2` - Standard version for higher quality output and the broader Seedance 2 workflow
  * `seedance-2-fast` - Faster version for previews and lower-latency iteration
  * `seedance-2-mini` - Lightweight version for lower-cost drafts and multimodal reference workflows, currently fixed to `1` result per request
</ParamField>

<ParamField body="prompt" type="string">
  Video prompt.

  We recommend clearly describing the scene, camera motion, subject action, style, and audio mood.
</ParamField>

<ParamField body="client_business_id" type="string">
  Your business-side ID, such as an order number or internal job ID. Once submitted, it is stored with the task and can be used later for status lookup:
  `GET /v1/videos/generations/{client_business_id}`.

  `metadata.client_business_id` is also accepted, but the top-level field is recommended.
</ParamField>

<ParamField body="duration" type="integer" default={0}>
  Video duration in seconds.

  Rules:

  * `seedance-2`: `4-15`
  * `seedance-2-fast`: `4-15`
  * `seedance-2-mini`: `4-15`
  * `0`: auto duration (`seedance-2` / `seedance-2-fast` only)
  * `-1`: auto duration (`seedance-2` / `seedance-2-fast` only)
</ParamField>

<ParamField body="aspect_ratio" type="string">
  Video aspect ratio.

  Options:

  * `21:9`
  * `16:9`
  * `4:3`
  * `1:1`
  * `3:4`
  * `9:16`
</ParamField>

<ParamField body="image_urls" type="string[]">
  Compatibility image URL array.

  We recommend using `image_with_roles` instead so you can explicitly mark `first_frame`, `last_frame`, or `reference_image`.

  <Warning>
    * Do not use `image_urls` together with `image_with_roles`.
    * `seedance-2-mini` does not support frame mode. Use `image_with_roles` with `reference_image` instead.
  </Warning>
</ParamField>

<ParamField body="image_with_roles" type="array">
  Image list with explicit roles.

  Supported patterns:

  * `seedance-2` / `seedance-2-fast`
    * `first_frame` for first-frame image-to-video
    * `first_frame` + `last_frame` for first-last-frame video generation
    * `reference_image` for multimodal reference generation
  * `seedance-2-mini`
    * `reference_image` only

  <Expandable title="Field details">
    <ParamField body="url" type="string" required>
      Image URL, Base64 data, or uploaded asset URI.

      Supported:

      * `https://...`
      * `data:image/<format>;base64,...`
      * `asset://<ASSET_ID>`
    </ParamField>

    <ParamField body="role" type="string" required>
      Image role.

      Allowed values:

      * `first_frame`
      * `last_frame`
      * `reference_image`
    </ParamField>
  </Expandable>

  <Warning>
    * Maximum `1` `first_frame`
    * Maximum `1` `last_frame`
    * Maximum `9` `reference_image`
    * Frame mode and reference mode cannot be mixed
    * `seedance-2-mini` supports `reference_image` only
  </Warning>
</ParamField>

<ParamField body="video_with_roles" type="array">
  Video list with roles.

  Only `reference_video` is currently supported in multimodal reference mode.

  <Expandable title="Field details">
    <ParamField body="url" type="string" required>
      Video URL or uploaded asset URI.
    </ParamField>

    <ParamField body="role" type="string" required>
      Fixed to:

      * `reference_video`
    </ParamField>
  </Expandable>

  Limits:

  * `seedance-2-mini`: up to `3` reference videos
</ParamField>

<ParamField body="audio_with_roles" type="array">
  Audio list with roles.

  Only `reference_audio` is currently supported in multimodal reference mode.

  <Expandable title="Field details">
    <ParamField body="url" type="string" required>
      Audio URL, Base64 data, or uploaded asset URI.
    </ParamField>

    <ParamField body="role" type="string" required>
      Fixed to:

      * `reference_audio`
    </ParamField>
  </Expandable>

  Limits:

  * `seedance-2-mini`: up to `3` reference audios

  <Warning>
    `audio_with_roles` cannot be used alone. At least one visual input is required.
  </Warning>
</ParamField>

<ParamField body="resolution" type="string" default="720p">
  Video resolution.

  Options:

  * `seedance-2`: `480p`, `720p`, `1080p`, `4k`
  * `seedance-2-fast`: `480p`, `720p`
  * `seedance-2-mini`: `480p`, `720p`
</ParamField>

<ParamField body="generate_audio" type="boolean" default={true}>
  Whether to generate synced audio.

  <Warning>
    `seedance-2-mini` does not expose `generate_audio`. Do not send this field for mini requests.
  </Warning>
</ParamField>

<ParamField body="seed" type="integer">
  Random seed for generation control.
</ParamField>

<ParamField body="callback_url" type="string">
  Async callback URL.
</ParamField>

<ParamField body="trace_id" type="string">
  Your pass-through trace ID. Effective when used together with `callback_url`.
</ParamField>

## Use Uploaded Assets

If you already uploaded private assets and obtained a usable `asset_id`, you do not need to send the original media URL again. Use:

* `asset://<ASSET_ID>`

Asset inputs can be used as:

* Images: `first_frame`, `last_frame`, `reference_image`
* Videos: `reference_video`
* Audios: `reference_audio`

Before use, make sure the asset has reached `active` status.

Related guides:

* [Private Avatar Assets](./private-avatar)
* [Real Avatar Assets](./real-avatar)

## Input Combinations

Typical supported combinations:

* Text only: text-to-video
* Text + first frame: first-frame image-to-video (`seedance-2` / `seedance-2-fast` only)
* Text + first frame + last frame: first-last-frame generation (`seedance-2` / `seedance-2-fast` only)
* Text + reference images: multimodal reference generation
* Text + reference video: video-reference generation
* Text + reference images + reference audio: multimodal reference generation
* Text + reference images + reference video + reference audio: multimodal reference generation

<Warning>
  `seedance-2-mini` supports reference mode only. It does not support `first_frame` or `last_frame`.
</Warning>

## Capabilities

| Item                  | seedance-2                                       | seedance-2-fast                                  | seedance-2-mini                            |
| --------------------- | ------------------------------------------------ | ------------------------------------------------ | ------------------------------------------ |
| Positioning           | Higher quality and longer runs                   | Faster generation and lower latency              | Lower-cost drafts and multimodal reference |
| Duration              | `4-15` seconds, auto duration supported          | `4-15` seconds, auto duration supported          | `4` / `8` / `10` / `12` / `15` seconds     |
| Resolution            | `480p` / `720p` / `1080p` / `4k`                 | `480p` / `720p`                                  | `480p` / `720p`                            |
| Image roles           | `first_frame` / `last_frame` / `reference_image` | `first_frame` / `last_frame` / `reference_image` | `reference_image`                          |
| Video roles           | `reference_video`                                | `reference_video`                                | `reference_video`                          |
| Audio roles           | `reference_audio`                                | `reference_audio`                                | `reference_audio`                          |
| Frame mode            | Supported                                        | Supported                                        | Not supported                              |
| Reference image limit | `9`                                              | `9`                                              | `9`                                        |
| Reference video limit | Depends on the routed channel                    | Depends on the routed channel                    | `3`                                        |
| Reference audio limit | Depends on the routed channel                    | Depends on the routed channel                    | `3`                                        |
| Synced audio field    | `generate_audio`                                 | `generate_audio`                                 | Not exposed                                |
| Callback              | `callback_url` + `trace_id`                      | `callback_url` + `trace_id`                      | `callback_url` + `trace_id`                |

<Note>
  `seedance-2-mini` is currently fixed to `1` output per request and does not expose `count` / `n`. It also does not support `media_mode=frame`, `first_frame`, `last_frame`, or `return_last_frame`.
</Note>

## Response

<ResponseField name="id" type="string">
  Task ID for status queries.
</ResponseField>

<ResponseField name="client_business_id" type="string">
  Your business-side ID. Returned only when `client_business_id` was provided in the request.
</ResponseField>

<ResponseField name="object" type="string">
  Object type, always `generation.task`.
</ResponseField>

<ResponseField name="model" type="string">
  Model name used for this request.
</ResponseField>

<ResponseField name="status" type="string">
  Task status: `queued`, `in_progress`, `completed`, or `failed`.
</ResponseField>

<ResponseField name="progress" type="integer">
  Task progress percentage (`0-100`).
</ResponseField>

<ResponseField name="created_at" type="integer">
  Task creation timestamp.
</ResponseField>

<Info>
  The submit API returns the base task object. After completion, use [Get Video Task Status](/en/api-reference/tasks/video-status) to fetch `completed_at`, `expires_at`, and `result.type = "video"` with `result.data[].url` and `result.data[].format`.
</Info>

<RequestExample>
  ```bash cURL (seedance-2-mini multimodal reference) theme={null}
  curl --request POST \
    --url https://toapis.com/v1/videos/generations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "seedance-2-mini",
      "client_business_id": "order_20260616_001",
      "prompt": "Keep the character from image 1, follow the camera motion of video 1, and match the rhythm of audio 1 for a short indoor product clip.",
      "duration": 10,
      "aspect_ratio": "16:9",
      "image_with_roles": [
        {"url": "https://example.com/ref-image-1.jpg", "role": "reference_image"}
      ],
      "video_with_roles": [
        {"url": "https://example.com/ref-video-1.mp4", "role": "reference_video"}
      ],
      "audio_with_roles": [
        {"url": "https://example.com/ref-audio-1.mp3", "role": "reference_audio"}
      ],
      "resolution": "480p"
    }'
  ```

  ```bash cURL (first-last-frame generation) theme={null}
  curl --request POST \
    --url https://toapis.com/v1/videos/generations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "seedance-2",
      "prompt": "Slowly push from the bouquet by the window toward the dining table, keeping a warm and soft look.",
      "duration": 5,
      "aspect_ratio": "16:9",
      "image_with_roles": [
        {"url": "https://example.com/first-frame.png", "role": "first_frame"},
        {"url": "https://example.com/last-frame.png", "role": "last_frame"}
      ],
      "resolution": "720p",
      "generate_audio": false
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://toapis.com/v1/videos/generations",
      headers={
          "Authorization": "Bearer your-ToAPIs-key",
          "Content-Type": "application/json",
      },
      json={
          "model": "seedance-2-mini",
          "prompt": "Keep the same character and use the reference image and video rhythm to create a short indoor ad clip",
          "duration": 8,
          "aspect_ratio": "16:9",
          "resolution": "720p",
          "image_with_roles": [
              {"url": "https://example.com/ref.png", "role": "reference_image"}
          ],
          "video_with_roles": [
              {"url": "https://example.com/ref.mp4", "role": "reference_video"}
          ],
      },
  )

  print(response.json())
  ```
</RequestExample>

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