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

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

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

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

<Warning>
  **첫/마지막 프레임 모드와 레퍼런스 에셋 모드는 함께 사용할 수 없습니다.**

  요청에 `first_frame` 또는 `last_frame` 이 포함된 경우 레퍼런스 이미지, 레퍼런스 비디오, 레퍼런스 오디오, 파일 또는 웹 링크를 함께 전달할 수 없습니다. 레퍼런스 이미지, 레퍼런스 비디오, 레퍼런스 오디오끼리는 조합하여 사용할 수 있습니다.
</Warning>

## 인증

<ParamField header="Authorization" type="string" required>
  Bearer Token 인증을 사용합니다:

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

## 요청 파라미터

<ParamField body="model" type="string" default="wan3.0-video" required>
  모델 이름. `wan3.0-video` 로 고정됩니다.
</ParamField>

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

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

<ParamField body="duration" type="integer" default="5">
  출력 길이. `2` \~ `30` 초를 지원합니다. `-1`을 전달하면 스마트 길이 모드로, 모델이 프롬프트와 소재에 따라 출력 길이를 자동으로 결정합니다.
</ParamField>

<ParamField body="ratio" type="string" default="adaptive">
  출력 화면 비율. 다음을 지원합니다:

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

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

<ParamField body="resolution" type="string" default="1080p">
  출력 해상도. `480p`, `720p`, `1080p` 를 지원합니다.
</ParamField>

<ParamField body="audio" type="boolean" default={true}>
  오디오 생성 여부. 기본값은 활성화입니다.
</ParamField>

<ParamField body="watermark" type="boolean" default={false}>
  워터마크 추가 여부. 기본값은 비활성화입니다.
</ParamField>

<ParamField body="seed" type="integer">
  선택적 랜덤 시드입니다. 동일한 파라미터와 시드를 사용하면 비슷한 결과를 재현하기 쉽습니다.
</ParamField>

<ParamField body="image_with_roles" type="object[]">
  첫/마지막 프레임 제어 배열입니다. 각 항목은 다음을 포함합니다:

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

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

<ParamField body="reference_images" type="string[]">
  레퍼런스 이미지 URL 배열입니다. 최대 `10` 장. `image_with_roles` 의 첫/마지막 프레임과 함께 사용할 수 없습니다.
</ParamField>

<ParamField body="video_list" type="object[]">
  레퍼런스 비디오 배열입니다. 최대 `5` 개, 총 길이 `15` 초 이내. 각 항목은 다음 구조를 사용합니다:

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

<ParamField body="audio_with_roles" type="object[]">
  레퍼런스 오디오 배열입니다. 최대 `5` 개, 총 길이 `15` 초 이내. 각 항목은 다음을 포함합니다:

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

<ParamField body="metadata" type="object">
  파일 또는 웹 페이지 레퍼런스는 `metadata.media` 로 전달합니다.

  <Expandable title="metadata.media 구조 보기">
    `media` 는 객체 배열이며 각 항목은 `type` 과 `url` 을 포함합니다:

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

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

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

## 에셋 조합 규칙

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

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

```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"
        }
      ]
    }
  }'
```

## 응답

<ResponseField name="id" type="string">
  비디오 태스크 ID. 태스크 상태 조회에 사용합니다.
</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": "wan3.0-video",
    "status": "in_progress",
    "progress": 10,
    "created_at": 1781577600
  }
  ```
</ResponseExample>


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