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

> [!NOTE]
>
> **Note for users in mainland China:** Please use `https://toapis.cn` as the API endpoint (Base URL). Replace `https://toapis.com` with `https://toapis.cn` in the examples in this document.

* Supports `seedance-2`, `seedance-2-fast`, and `seedance-2-mini`
* Supports text-to-video, first-frame / first-last-frame image-to-video, and multimodal reference-to-video; `seedance-2-mini` also supports frame roles and the audio generation switch
* 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

**Authorization** `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
```

## Body

**model** `string` *required* (default: seedance-2)

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

**prompt** `string`

Video content description.

Supports Chinese and English input. We recommend clearly describing the scene, camera motion, subject action, style, and audio mood.

Recommendations:

* Keep Chinese prompts within `500` characters
* Keep English prompts within `1,000` words
* When referring to reference materials, use “image 1 / video 1 / audio 1” to identify them

**client\_business\_id** `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.

**duration** `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)

**aspect\_ratio** `string`

Video aspect ratio.

Options:

* `21:9`
* `16:9`
* `4:3`
* `1:1`
* `3:4`
* `9:16`
* `adaptive`

`adaptive` lets the upstream choose an appropriate ratio from the input media.

**image\_urls** `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`.
> * For new integrations, use `image_with_roles` to explicitly mark how each image should be used.

**image\_with\_roles** `array`

Image list with explicit roles.

Supported patterns:

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

**Field details**

**url** `string` *required*

Image URL.

Supported:

* `https://...`

**role** `string` *required*

Image role.

Allowed values:

* `first_frame`
* `last_frame`
* `reference_image`

> [!WARNING]
>
> * Maximum `1` `first_frame`
> * Maximum `1` `last_frame`
> * Maximum `9` `reference_image`
> * Frame mode and reference mode cannot be mixed
> * `seedance-2-mini` also supports `first_frame`, `last_frame`, and `reference_image`

**video\_with\_roles** `array`

Video list with roles.

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

**Field details**

**url** `string` *required*

Video URL.

**role** `string` *required*

Fixed to:

* `reference_video`

Limits:

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

**audio\_with\_roles** `array`

Audio list with roles.

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

**Field details**

**url** `string` *required*

Audio URL.

**role** `string` *required*

Fixed to:

* `reference_audio`

Limits:

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

> [!WARNING]
>
> `audio_with_roles` cannot be used alone. At least one visual input is required.

**resolution** `string` (default: 720p)

Video resolution.

Options:

* `seedance-2`: `480p`, `720p`, `1080p`, `4k`
* `seedance-2-fast`: `480p`, `720p`
* `seedance-2-mini`: `480p`, `720p`

**generate\_audio** `boolean` (default: true)

Whether to generate synced audio.

`seedance-2-mini` also supports this field.

**return\_last\_frame** `boolean` (default: false)

Whether to return the generated video's last-frame image.

When set to `true`, the completed task response includes the image URL at `result.data[0].last_frame_url`.

**tools** `array`

Tools the model may call. The Seedance 2 series currently supports web search:

```json theme={null}
[{ "type": "web_search" }]
```

The model decides whether a search is needed from the prompt. The actual number of searches is returned at `usage.tool_usage.web_search`; `0` means no search was performed.

> [!WARNING]
>
> `tools` is supported only for text-to-video requests and cannot be combined with image, video, or audio inputs.

**seed** `integer`

Random seed for generation control.

**callback\_url** `string`

ToAPIs standardized completion callback. Configure the Token URL and signing secret first; request-level URLs must be same-origin. See [Task Webhooks](https://docs.toapis.com/docs/en/api-reference/webhooks/task-webhooks.md).

**trace\_id** `string`

Your tracking field. It does not depend on Webhook configuration.

**disable\_nsfw** `boolean` (default: false)

Set to `true` to disallow NSFW content generation.

## Asset review

When a request includes image, video, or audio inputs, some channels review the media automatically before submitting generation. No extra parameter is needed; pass media URLs in the existing media fields.

* An accepted request returns a video task immediately. When review is required, the task stays `queued` and generation is submitted only after all media in the request pass. First-time review can take several minutes; reusing the same URL for the same user and channel reuses the review result.
* Each media preparation round lasts up to 20 minutes by default. Rejection or preparation timeout ends the task as `failed`; see `error.message` for the reason. Failed review incurs no video generation fee.
* Media must be public HTTP(S) URLs; Base64 and local paths are not accepted. Keep images within 20 MB (some channels allow up to 30 MB) and video or audio within 100 MiB. Each model's existing format limits still apply.
* Channels that review media validate it at submission: a URL with embedded credentials or longer than 2048 bytes, the same URL used as different media types, or more than 64 media references in one request returns HTTP 400 with `error.code` `invalid_private_assets`.
* Media is identified by URL. Use a new URL after the file content changes.
* Legacy `asset://` references are retired and return HTTP 400.

## Input Combinations

Typical supported combinations:

* Text only: text-to-video
* Text + first frame: first-frame image-to-video
* Text + first frame + last frame: first-last-frame generation
* 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` also supports first-frame and first-last-frame workflows. Use `image_with_roles` with explicit `first_frame` / `last_frame` roles.

## 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-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` | `first_frame` / `last_frame` / `reference_image` |
| Video roles | `reference_video` | `reference_video` | `reference_video` |
| Audio roles | `reference_audio` | `reference_audio` | `reference_audio` |
| Frame mode | Supported | Supported | 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` | `generate_audio` |
| ToAPIs callback | `callback_url` (`trace_id` optional) | `callback_url` (`trace_id` optional) | `callback_url` (`trace_id` optional) |

> [!NOTE]
>
> `seedance-2-mini` is currently fixed to `1` output per request and does not expose `count` / `n`. Express frame control through `image_with_roles` using `first_frame` / `last_frame`.

> [!NOTE]
>
> Fetch completed results from [Video task status](https://docs.toapis.com/docs/en/api-reference/tasks/video-status.md#seedance-original-and-fallback-urls). When original URL delivery is enabled, prefer `result.data[].url` and use the optional `fallback_url` only if the primary URL cannot be accessed. Last frames use `last_frame_url` and `fallback_last_frame_url`. Fallback fields are returned only when copies are available.

## Response

**id** `string`

Task ID for status queries.

**client\_business\_id** `string`

Your business-side ID. Returned only when `client_business_id` was provided in the request.

**object** `string`

Object type, always `generation.task`.

**model** `string`

Model name used for this request.

**status** `string`

Task status: `queued`, `in_progress`, `completed`, or `failed`.

**progress** `integer`

Task progress percentage (`0-100`).

**created\_at** `integer`

Task creation timestamp.

> [!NOTE]
>
> The submit API returns the base task object. After completion, use [Get Video Task Status](https://docs.toapis.com/docs/en/api-reference/tasks/video-status.md) to fetch `completed_at`, `expires_at`, and `result.type = "video"` with `result.data[].url` and `result.data[].format`. With `return_last_frame`, the last-frame URL is at `result.data[0].last_frame_url`; with `web_search`, the search count is at `usage.tool_usage.web_search`.

```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())
```

```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
}
```


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