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

# Wan 3.0 올인원 비디오 생성

> Wan 3.0 All-in-One 모델로 비디오 생성 — 텍스트-투-비디오, 첫/마지막 프레임 제어, 이미지·비디오·오디오 등 멀티모달 레퍼런스 지원

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

Wan 3.0의 공개 모델명은 `wan3.0-video` 입니다. 하나의 모델로 다음 생성 방식을 지원합니다:

* 텍스트-투-비디오
* 첫 프레임 또는 첫/마지막 프레임 제어
* 레퍼런스 이미지, 레퍼런스 비디오, 레퍼런스 오디오 결합 생성
* 파일 또는 공개 웹 페이지 레퍼런스

API는 비동기 태스크입니다. 제출에 성공하면 태스크 ID가 반환되며, [비디오 태스크 상태](https://docs.toapis.com/docs/ko/api-reference/tasks/video-status.md) 엔드포인트로 진행 상황과 결과를 조회할 수 있습니다.

> [!WARNING]
>
> **첫/마지막 프레임 모드와 레퍼런스 에셋 모드는 함께 사용할 수 없습니다.**
>
> 요청에 `first_frame` 또는 `last_frame` 이 포함된 경우 레퍼런스 이미지, 레퍼런스 비디오, 레퍼런스 오디오, 파일 또는 웹 링크를 함께 전달할 수 없습니다. 레퍼런스 이미지, 레퍼런스 비디오, 레퍼런스 오디오끼리는 조합하여 사용할 수 있습니다.

## 인증

**Authorization** `string` *required*

Bearer Token 인증을 사용합니다:

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

## 요청 파라미터

**model** `string` *required* (default: wan3.0-video)

모델 이름. `wan3.0-video` 로 고정됩니다.

**prompt** `string`

비디오 내용, 피사체 동작, 카메라 워크, 사운드에 대한 설명입니다. `prompt` 와 미디어 에셋 중 최소 하나를 제공해야 합니다.

멀티모달 레퍼런스를 사용할 때는 배열 순서에 맞춰 프롬프트에 "이미지1", "비디오1", "오디오1" 과 같이 작성할 수 있습니다.

**duration** `integer` (default: 5)

출력 길이. `2` \~ `30` 초를 지원합니다. `-1`을 전달하면 스마트 길이 모드로, 모델이 프롬프트와 소재에 따라 출력 길이를 자동으로 결정합니다.

**ratio** `string` (default: adaptive)

출력 화면 비율. 다음을 지원합니다:

* `adaptive`: 레퍼런스 에셋에 맞게 자동 조정
* `16:9`
* `9:16`
* `1:1`
* `4:3`
* `3:4`

호환 필드 `aspect_ratio` 도 사용할 수 있습니다. 두 필드를 동시에 전달할 필요는 없습니다.

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

출력 해상도. `480p`, `720p`, `1080p` 를 지원합니다.

**audio** `boolean` (default: true)

오디오 생성 여부. 기본값은 활성화입니다.

**watermark** `boolean` (default: false)

워터마크 추가 여부. 기본값은 비활성화입니다.

**seed** `integer`

선택적 랜덤 시드입니다. 동일한 파라미터와 시드를 사용하면 비슷한 결과를 재현하기 쉽습니다.

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

첫/마지막 프레임 제어 배열입니다. 각 항목은 다음을 포함합니다:

* `url`: 공개적으로 접근 가능한 이미지 URL
* `role`: `first_frame` 또는 `last_frame`

첫 프레임과 마지막 프레임은 각각 최대 1개씩 제공할 수 있습니다. `last_frame` 을 사용하려면 `first_frame` 도 함께 제공해야 합니다.

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

레퍼런스 이미지 URL 배열입니다. 최대 `10` 장. `image_with_roles` 의 첫/마지막 프레임과 함께 사용할 수 없습니다.

**video\_list** `object[]`

레퍼런스 비디오 배열입니다. 최대 `5` 개, 총 길이 `15` 초 이내. 각 항목은 다음 구조를 사용합니다:

```json theme={null}
{
  "video_url": "https://example.com/reference.mp4"
}
```

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

레퍼런스 오디오 배열입니다. 최대 `5` 개, 총 길이 `15` 초 이내. 각 항목은 다음을 포함합니다:

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

**metadata** `object`

파일 또는 웹 페이지 레퍼런스는 `metadata.media` 로 전달합니다.

**metadata.media 구조 보기**

`media` 는 객체 배열이며 각 항목은 `type` 과 `url` 을 포함합니다:

* 파일: `{ "type": "file", "url": "https://example.com/brief.pdf" }`
* 웹 페이지: `{ "type": "link", "url": "https://example.com/article" }`

한 번의 요청에는 파일 하나 또는 웹 페이지 하나만 제공할 수 있으며 둘을 함께 사용할 수 없습니다. 파일과 웹 페이지는 첫/마지막 프레임 모드와도 함께 사용할 수 없습니다.

> [!NOTE]
>
> 로컬 이미지나 비디오는 먼저 업로드하여 공개 URL을 얻어야 합니다. 생성 요청에 로컬 파일 경로나 base64 데이터를 직접 전달하지 마세요.

## 에셋 조합 규칙

| 요청 내용 | 지원 여부 | 설명 |
| - | -: | - |
| 프롬프트만 | 예 | 텍스트-투-비디오 |
| 첫 프레임만 | 예 | 첫 프레임 제어 |
| 첫 프레임과 마지막 프레임 | 예 | 마지막 프레임은 단독으로 사용 불가 |
| 레퍼런스 이미지와 레퍼런스 비디오 | 예 | 함께 레퍼런스 가능 |
| 레퍼런스 이미지, 비디오, 오디오 | 예 | 함께 레퍼런스 가능 |
| 첫 프레임과 레퍼런스 비디오 | 아니요 | 첫/마지막 프레임 모드와 레퍼런스 에셋 모드는 상호 배타적 |
| 첫/마지막 프레임과 레퍼런스 이미지 | 아니요 | 첫/마지막 프레임 모드와 레퍼런스 에셋 모드는 상호 배타적 |
| 파일과 웹 링크 | 아니요 | 둘은 상호 배타적 |

다음 오류가 발생하는 경우:

```text theme={null}
Wan 3.0 cannot mix first/last frames with reference assets/files/web pages in the same request.
```

첫/마지막 프레임을 삭제하고 레퍼런스 에셋을 유지하거나, 모든 레퍼런스 에셋을 삭제하고 첫/마지막 프레임만 유지하세요.

## 요청 예시

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

```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": "wan3.0-video",
    "prompt": "비가 그친 도쿄 거리를 달리는 주황색 고양이, 영화적인 카메라 워크",
    "duration": 5,
    "ratio": "16:9",
    "resolution": "1080p",
    "audio": true,
    "watermark": false
  }'
```

### 첫/마지막 프레임 비디오 생성

```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": "wan3.0-video",
    "prompt": "카메라가 자연스럽게 다가가고 인물이 서 있는 상태에서 미소를 지으며 손을 흔드는 모습으로 전환",
    "duration": 8,
    "ratio": "adaptive",
    "resolution": "1080p",
    "image_with_roles": [
      {
        "url": "https://example.com/first-frame.png",
        "role": "first_frame"
      },
      {
        "url": "https://example.com/last-frame.png",
        "role": "last_frame"
      }
    ]
  }'
```

### 레퍼런스 비디오로 비디오 생성

이 요청에서는 `first_frame` 이나 `last_frame` 을 함께 전달하지 마세요.

```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": "wan3.0-video",
    "prompt": "비디오1의 카메라 워크와 인물 동작을 참고하여 새로운 스트릿 댄스 비디오 생성",
    "duration": 10,
    "ratio": "adaptive",
    "resolution": "720p",
    "audio": true,
    "video_list": [
      {
        "video_url": "https://example.com/reference-video.mp4"
      }
    ]
  }'
```

### 이미지, 비디오, 오디오 결합 레퍼런스

```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": "wan3.0-video",
    "prompt": "이미지1의 캐릭터, 비디오1의 동작, 오디오1의 리듬을 사용하여 비디오 생성",
    "duration": 10,
    "ratio": "16:9",
    "resolution": "720p",
    "audio": true,
    "reference_images": [
      "https://example.com/character.png"
    ],
    "video_list": [
      {
        "video_url": "https://example.com/motion.mp4"
      }
    ],
    "audio_with_roles": [
      {
        "url": "https://example.com/music.mp3",
        "role": "reference_audio"
      }
    ]
  }'
```

### 파일 레퍼런스

```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": "wan3.0-video",
    "prompt": "파일 내용을 바탕으로 간결한 제품 소개 비디오 생성",
    "duration": 10,
    "ratio": "16:9",
    "resolution": "1080p",
    "metadata": {
      "media": [
        {
          "type": "file",
          "url": "https://example.com/product-brief.pdf"
        }
      ]
    }
  }'
```

## 응답

**id** `string`

비디오 태스크 ID. 태스크 상태 조회에 사용합니다.

**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": "wan3.0-video",
  "status": "in_progress",
  "progress": 10,
  "created_at": 1781577600
}
```


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