> ## 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 비디오 생성

> seedance-2.5-ext 모델로 비디오 생성 — 레퍼런스 이미지·비디오·오디오 지원

<Note>
  **중국 본토 사용자 안내:** 중국 본토 사용자는 `https://toapis.cn` 를 API 엔드포인트(Base URL)로 사용해 주세요. 본 문서의 예시에서 `https://toapis.com` 을 `https://toapis.cn` 로 바꿔 주세요.
</Note>

`seedance-2.5-ext` 는 Seedance 2.5 패밀리의 프로모션 채널 모델로, 텍스트-투-비디오와 멀티모달 레퍼런스 생성을 지원합니다:

* 텍스트-투-비디오 및 레퍼런스 이미지 생성
* 레퍼런스 비디오와 레퍼런스 오디오 결합 생성(비디오 편집, 연장, 첫/마지막 프레임 모드는 미지원)
* API는 비동기 작업입니다: 제출하면 `generation.task` 가 반환되고, 완료 후 [비디오 작업 상태 API](../../tasks/video-status)로 결과를 가져옵니다.

요청 내용에 따라 최적의 업스트림으로 자동 라우팅됩니다: 이미지만 있거나 텍스트만 있는 요청은 저비용 업스트림으로, 레퍼런스 비디오·레퍼런스 오디오·11장 이상의 레퍼런스 이미지가 포함된 요청은 전체 기능 업스트림으로 전달됩니다.

## 인증

<ParamField header="Authorization" type="string" required>
  Bearer Token으로 인증합니다:

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

## 요청 파라미터

<ParamField body="model" type="string" default="seedance-2.5-ext" required>
  ToAPIs 공개 모델명. 항상 `seedance-2.5-ext` 를 사용하세요.
</ParamField>

<ParamField body="prompt" type="string">
  장면, 카메라 움직임, 피사체 동작, 스타일, 사운드 분위기를 설명합니다. 에셋을 참조할 때는 배열 순서에 맞춰 "이미지1", "비디오1", "오디오1" 같은 태그를 사용할 수 있습니다.
</ParamField>

<ParamField body="seconds" type="integer">
  출력 비디오 길이(초). `10`–`30` 범위. 호환 필드 `duration` 도 사용할 수 있으며, 둘을 함께 전달하지 마세요.

  <Warning>
    레퍼런스 비디오, 레퍼런스 오디오 또는 11장 이상의 레퍼런스 이미지가 포함된 요청에서는 `15` 초를 지원하지 않습니다. 텍스트만 있거나 이미지가 10장 이하인 요청은 영향을 받지 않습니다.
  </Warning>
</ParamField>

<ParamField body="size" type="string">
  출력 화면 비율. `16:9`, `9:16`, `4:3`, `3:4`, `1:1` 을 지원합니다. 호환 필드 `aspect_ratio` 도 사용할 수 있습니다.
</ParamField>

<ParamField body="resolution" type="string" default="720p">
  출력 해상도. `720p` 고정입니다.
</ParamField>

<ParamField body="reference_image" type="string">
  단일 레퍼런스 이미지의 공개 URL. 여러 장일 경우 `reference_images` 를 사용하세요.
</ParamField>

<ParamField body="reference_images" type="string[]">
  레퍼런스 이미지 URL 배열. 최대 `30` 장. `image_with_roles`(`role` 은 `reference_image`)로 명시적으로 전달할 수도 있습니다.
</ParamField>

<ParamField body="video_with_roles" type="object[]">
  레퍼런스 비디오 배열. 최대 `10` 개. 각 항목:

  * `url`: 공개 접근 가능한 비디오 URL
  * `role`: `reference_video` 고정
</ParamField>

<ParamField body="audio_with_roles" type="object[]">
  레퍼런스 오디오 배열. 최대 `10` 개. 각 항목:

  * `url`: 공개 접근 가능한 오디오 URL
  * `role`: `reference_audio` 고정

  오디오는 단독 입력으로 사용할 수 없습니다. 요청에 레퍼런스 이미지 또는 레퍼런스 비디오가 하나 이상 포함되어야 합니다.
</ParamField>

<ParamField body="callback_url" type="string">
  ToAPIs 작업 완료 콜백 URL. 자세한 내용은 [작업 Webhook](/docs/ko/api-reference/webhooks/task-webhooks)을 참조하세요.
</ParamField>

<ParamField body="client_business_id" type="string">
  고객 측 주문 번호 또는 비즈니스 작업 ID. 작업과 함께 저장되며 `GET /v1/videos/generations/{client_business_id}` 로도 조회할 수 있습니다.
</ParamField>

<ParamField body="trace_id" type="string">
  호출자가 정의하는 트레이스 ID.
</ParamField>

## 에셋 조합 규칙

| 요청 내용 | 지원 | 비고 |
| - | -: | - |
| 프롬프트만 | 예 | 텍스트-투-비디오 |
| 레퍼런스 이미지 10장 이하 | 예 | 저비용 업스트림 |
| 레퍼런스 이미지 11–30장 | 예 | 15초 미지원 |
| 레퍼런스 비디오 / 레퍼런스 오디오 | 예 | 15초 미지원. 오디오는 이미지 또는 비디오와 함께 필요 |
| 첫 / 마지막 프레임 | 아니오 | 프레임 모드 미지원 |
| 비디오 편집 / 연장 | 아니오 | `seedance-2-5` 를 사용하세요 |

## 요청 예시

### 텍스트-투-비디오

```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": "영화 같은 제품 클로즈업, 카메라가 천천히 다가감. 자연스러운 실내 환경음 유지.",
    "seconds": 10,
    "size": "16:9",
    "resolution": "720p"
  }'
```

### 레퍼런스 이미지로 생성

```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": "이미지1의 인물이 비 오는 밤거리로 걸어 들어감. 카메라가 따라감.",
    "seconds": 12,
    "size": "9:16",
    "reference_images": [
      "https://example.com/character.png"
    ]
  }'
```

### 비디오와 오디오 결합 레퍼런스

```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": "이미지1의 인물, 비디오1의 카메라 움직임, 오디오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"}
    ]
  }'
```

## 응답

<ResponseField name="id" type="string">상태 조회용 작업 ID.</ResponseField>
<ResponseField name="client_business_id" type="string">요청에 지정한 경우 반환됩니다.</ResponseField>
<ResponseField name="object" type="string">항상 `generation.task` 입니다.</ResponseField>
<ResponseField name="model" type="string">이 요청에 사용된 모델명.</ResponseField>
<ResponseField name="status" type="string">`queued`, `in_progress`, `completed` 또는 `failed`.</ResponseField>
<ResponseField name="progress" type="integer">`0`–`100` 의 작업 진행률.</ResponseField>
<ResponseField name="created_at" type="integer">생성 타임스탬프.</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.