> ## 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` 로 바꿔 주세요.

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

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

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

## 인증

**Authorization** `string` *required*

Bearer Token으로 인증합니다:

```text theme={null}
Authorization: Bearer YOUR_API_KEY
```

## 요청 파라미터

**model** `string` *required* (default: seedance-2.5-ext)

ToAPIs 공개 모델명. 항상 `seedance-2.5-ext` 를 사용하세요.

**prompt** `string`

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

**seconds** `integer`

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

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

**size** `string`

출력 화면 비율. `16:9`, `9:16`, `4:3`, `3:4`, `1:1` 을 지원합니다. 호환 필드 `aspect_ratio` 도 사용할 수 있습니다.

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

출력 해상도. `720p` 고정입니다.

**reference\_image** `string`

단일 레퍼런스 이미지의 공개 URL. 여러 장일 경우 `reference_images` 를 사용하세요.

**reference\_images** `string[]`

레퍼런스 이미지 URL 배열. 최대 `30` 장. `image_with_roles`(`role` 은 `reference_image`)로 명시적으로 전달할 수도 있습니다.

**video\_with\_roles** `object[]`

레퍼런스 비디오 배열. 최대 `10` 개. 각 항목:

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

**audio\_with\_roles** `object[]`

레퍼런스 오디오 배열. 최대 `10` 개. 각 항목:

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

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

**callback\_url** `string`

ToAPIs 작업 완료 콜백 URL. 자세한 내용은 [작업 Webhook](https://docs.toapis.com/docs/ko/api-reference/webhooks/task-webhooks.md)을 참조하세요.

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

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

**trace\_id** `string`

호출자가 정의하는 트레이스 ID.

## 에셋 조합 규칙

| 요청 내용 | 지원 | 비고 |
| - | -: | - |
| 프롬프트만 | 예 | 텍스트-투-비디오 |
| 레퍼런스 이미지 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"}
    ]
  }'
```

## 응답

**id** `string`

상태 조회용 작업 ID.

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

요청에 지정한 경우 반환됩니다.

**object** `string`

항상 `generation.task` 입니다.

**model** `string`

이 요청에 사용된 모델명.

**status** `string`

`queued`, `in_progress`, `completed` 또는 `failed`.

**progress** `integer`

`0`–`100` 의 작업 진행률.

**created\_at** `integer`

생성 타임스탬프.

```json 200 theme={null}
{
  "id": "tsk_vid_xxx",
  "object": "generation.task",
  "model": "seedance-2.5-ext",
  "status": "in_progress",
  "progress": 10,
  "created_at": 1781577600
}
```


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