> ## 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 動画生成

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

> [!NOTE]
>
> **中国本土のユーザー向け：** 中国本土のユーザーは `https://toapis.cn` を API エンドポイント（Base URL）としてご利用ください。本ドキュメント内の例では `https://toapis.com` を `https://toapis.cn` に置き換えてください。

* 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 prompt.

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

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

生成動画の最終フレーム画像を返すかどうか。

`true` の場合、完了したタスクの `result.data[0].last_frame_url` に画像 URL が返されます。

**tools** `array`

モデルが使用できるツール。Seedance 2 シリーズでは現在 Web 検索をサポートします。

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

実際の検索回数は `usage.tool_usage.web_search` に返され、`0` は検索が実行されなかったことを示します。

> [!WARNING]
>
> `tools` はテキストから動画を生成するリクエスト専用で、画像・動画・音声入力とは併用できません。

**seed** `integer`

Random seed for generation control.

**callback\_url** `string`

ToAPIs 標準完了 callback。Token URL と secret を先に設定し、同一 origin のみ上書きできます。[Webhook](https://docs.toapis.com/docs/ja/api-reference/webhooks/task-webhooks.md)。

**trace\_id** `string`

呼び出し側の追跡フィールド。Webhook 設定には依存しません。

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

`true` にすると NSFW コンテンツの生成を禁止します。

## 素材審査

画像, 動画, 音声を含むリクエストでは, 一部のチャネルが生成の送信前に素材を自動で審査します. 追加のパラメーターは不要で, 従来のメディアフィールドに素材 URL を指定するだけです.

* 受理されたリクエストはすぐに動画タスクを返します. 審査が必要な場合, タスクは `queued` のままとなり, リクエスト内の全素材が通過してから生成を送信します. 初回の審査には数分かかることがあります. 同じユーザーが同じチャネルで同じ URL を再利用すると審査結果も再利用されます.
* 素材準備は 1 ラウンドあたり既定で最長 20 分です. 審査拒否または準備タイムアウトの場合, タスクは `failed` で終了し, 理由は `error.message` で確認できます. 審査を通過しなかった場合, 動画生成料金は発生しません.
* 素材は公開 HTTP(S) URL で指定してください. Base64 とローカルパスは使えません. 画像は 20 MB 以内 (一部のチャネルは最大 30 MB), 動画と音声は 100 MiB 以内です. 各モデル本来の形式制限は変わりません.
* 審査を行うチャネルは受理時に素材を検証します. URL に認証情報が含まれる, 2048 バイトを超える, 同じ URL を異なる種別で使う, 1 リクエストの素材参照が 64 個を超える場合は, HTTP 400 (`error.code` は `invalid_private_assets`) を返します.
* 素材は URL で識別されます. ファイル内容を変更した場合は新しい URL を使ってください.
* 旧 `asset://` 参照は廃止され, 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` は任意） | `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`. Express frame control through `image_with_roles` using `first_frame` / `last_frame`.

> [!NOTE]
>
> 完了結果は[動画タスクの照会](https://docs.toapis.com/docs/ja/api-reference/tasks/video-status.md)で取得します. 元の URL の配信が有効な場合は `result.data[].url` を優先し, アクセスできない場合のみ任意の `fallback_url` を使用します. 最終フレームは `last_frame_url` と `fallback_last_frame_url` に対応します. 代替フィールドはコピーが利用可能な場合のみ返されます.

## レスポンス

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

モデル 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 ステータス](https://docs.toapis.com/docs/ja/api-reference/tasks/video-status.md) to fetch `completed_at`, `expires_at`, and `result.type = "video"` with `result.data[].url` and `result.data[].format`. `return_last_frame` 使用時は `result.data[0].last_frame_url`、`web_search` 使用時は `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.