> ## 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 시리즈는 현재 웹 검색을 지원합니다.

```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/ko/api-reference/webhooks/task-webhooks.md).

**trace\_id** `string`

호출자 추적 필드이며 Webhook 설정과 무관합니다.

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

`true`로 설정하면 NSFW 콘텐츠 생성을 금지합니다.

## 소재 심사

요청에 이미지, 동영상, 오디오 소재가 있으면 일부 채널은 생성 제출 전에 소재를 자동으로 심사합니다. 추가 파라미터는 필요 없으며 기존 미디어 필드에 소재 URL을 전달하면 됩니다.

* 요청이 접수되면 즉시 동영상 작업을 반환합니다. 심사가 필요하면 작업은 `queued` 상태를 유지하며, 요청의 모든 소재가 통과한 뒤에 생성을 제출합니다. 최초 심사에는 몇 분이 걸릴 수 있으며, 같은 사용자가 같은 채널에서 같은 URL을 다시 사용하면 심사 결과를 재사용합니다.
* 소재 준비는 라운드당 기본 최대 20분입니다. 심사 거부 또는 준비 시간 초과 시 작업은 `failed`로 종료되며 사유는 `error.message`에서 확인할 수 있습니다. 심사를 통과하지 못하면 동영상 생성 요금은 청구되지 않습니다.
* 소재는 공개 HTTP(S) URL이어야 하며 Base64와 로컬 경로는 지원하지 않습니다. 이미지는 20 MB 이하(일부 채널은 최대 30 MB), 동영상과 오디오는 100 MiB 이하로 준비하세요. 각 모델의 기존 형식 제한은 그대로 적용됩니다.
* 심사를 진행하는 채널은 접수 시 소재를 검증합니다. URL에 인증 정보가 있거나 2048바이트를 넘는 경우, 같은 URL을 다른 타입으로 사용한 경우, 한 요청의 소재 참조가 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/ko/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/ko/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.