> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Wan 2.7·3.0 비디오 생성 API: 초당 가격과 사용법

> Wan 2.7과 Wan 3.0으로 텍스트, 이미지, 참조 이미지 기반 비디오와 비디오 편집 작업을 만들고 MP4를 내려받는 방법, 청구 초를 계산하는 방식을 안내합니다.

Wan 2.7과 Wan 3.0은 DashScope 호환 비동기 작업 방식으로 호출합니다. `Wan` 그룹의 API 키(콘솔에서는 '토큰'이라고 부릅니다)가 필요하고, 비디오 길이(초)에 따라 과금됩니다.

| 항목 | 내용 |
| - | - |
| Wan 3.0 모델 | `wan3.0-video`(표준), `wan3.0-video-prime`(고속). 두 모델 모두 텍스트·이미지·참조 기반 비디오 생성과 비디오 편집을 처리 |
| Wan 2.7 모델 | `wan2.7-t2v`(텍스트 투 비디오), `wan2.7-i2v`(이미지 투 비디오), `wan2.7-r2v`(참조 투 비디오), `wan2.7-videoedit`(비디오 편집) |
| Wan 2.6 모델 | 2026년 10월 14일 종료. Wan 2.7이나 Wan 3.0을 사용하세요 |
| 작업 생성 | `POST /wan/api/v1/services/aigc/video-generation/video-synthesis` |
| 작업 조회 | `GET /v1/tasks/{task_id}` 후 `result_url`에서 MP4 다운로드 |
| 토큰 그룹 | `Wan`. 아래 Wan 토큰 만들기 절 참고 |
| 과금 | 비디오 초당 과금, Alibaba Cloud 목록 가격의 약 1.2배. 모델별 가격은 아래 과금과 가격 절 참고 |
| 결과 보관 | Alibaba Cloud가 `task_id`와 비디오 URL을 24시간 보관하므로 작업이 끝나면 바로 저장하세요 |
| 요청 규칙 | base URL, 인증, 비동기 헤더, 조회 간격, 타임아웃은 아래 엔드포인트와 요청 규칙 절 참고 |

> [!WARNING]
>
> Wan 요청을 `/v1/videos`로 보내지 마세요. 이미지 투 비디오, 참조 투 비디오, 비디오 편집 작업에는 DashScope의 `input.media[]` 페이로드가 필요하므로, 모든 Wan 작업은 위 표의 엔드포인트로 만드세요.

## Wan 토큰 만들기

| 설정 | 값 |
| - | - |
| 콘솔 | [토큰 관리](https://api.laozhang.ai/token) → 토큰 만들기 |
| 그룹 | `Wan` |
| 과금 방식 | 사용량 우선(콘솔 표시: 按量优先, 권장) 또는 사용량 과금(按量计费) |
| 요청 헤더 | `Authorization: Bearer $LAOZHANG_API_KEY` |

Wan 모델은 `Wan` 그룹에서만 호출할 수 있으므로 토큰도 이 그룹으로 만들어야 합니다. `default`나 `SeeDance2` 같은 다른 그룹의 토큰으로는 호출할 수 없고, 사용 가능한 채널이 없다는 오류가 납니다. Wan 전용 토큰을 따로 두면 모델별, 작업별로 로그와 청구 내역을 확인하기도 쉽습니다.

## 과금과 가격

Wan 비디오는 Alibaba Cloud Model Studio 목록 가격에 20%를 더해 초 단위로 과금합니다. 추가분은 세금, 환전과 국경 간 정산, 플랫폼 운영, 기술 지원 비용에 쓰입니다. 2026년 10월 14일부터 환산 방식은 다음과 같습니다.

* 초당 USD 가격 = Alibaba Cloud 초당 위안화 목록 가격 × 0.1714 (`Wan` 그룹 배율)
* 고정 환율 1:7에서 0.1714 × 7 ≈ 1.2이므로 목록 가격의 약 1.2배를 지불합니다

호출 로그의 금액에는 이미 배율이 반영되어 있으니 다시 곱하지 마세요. 초당 가격은 다음과 같습니다.

| 모델 | 해상도 | Alibaba Cloud 목록 가격 | 초당 가격 |
| - | - | -: | -: |
| `wan3.0-video` | 480P / 720P / 1080P | ¥0.3 / ¥0.6 / ¥1.2 | \$0.0514 / \$0.1028 / \$0.2057 |
| `wan3.0-video-prime` | 480P / 720P / 1080P | ¥0.45 / ¥0.9 / ¥1.8 | \$0.0771 / \$0.1543 / \$0.3085 |
| Wan 2.7 모델 4종 | 720P / 1080P | ¥0.6 / ¥1.0 | \$0.1028 / \$0.1714 |

Wan 2.7의 텍스트 투 비디오, 이미지 투 비디오, 참조 투 비디오, 비디오 편집 모델(`wan2.7-t2v`, `wan2.7-i2v`, `wan2.7-r2v`, `wan2.7-videoedit`)은 가격이 같습니다. Alibaba Cloud 가격은 [Model Studio 가격](https://help.aliyun.com/zh/model-studio/model-pricing)(중국어)의 화북 2(베이징) 리전 기준입니다.

청구 초는 다음과 같이 계산합니다.

* **출력만 있는 작업**(텍스트 투 비디오, 이미지 투 비디오, 참조 이미지만 쓰는 작업): 생성된 비디오 길이
* **입력 비디오가 있는 작업**: Alibaba Cloud와 같은 규칙으로 입력 길이 + 출력 길이
  * `wan2.7-videoedit`: 원본 비디오 + 출력. `duration`을 2\~10초로 지정하면 원본을 앞부분부터 잘라 잘린 부분만 계산
  * 참조 비디오를 쓰는 `wan2.7-r2v`: 참조 비디오 최대 5초 + 출력
  * `reference_video`를 쓰는 Wan 3.0(참조, 편집, 연장): 입력 비디오 전체 길이 + 출력
* **`resolution` 미지정**: Wan 2.7과 Wan 3.0 모두 기본값이 1080P이므로 1080P로 과금

비용 예시입니다.

* `wan2.7-i2v`, 720P, 5초: 5 × \$0.1028 ≈ \$0.51
* `wan3.0-video`, 1080P, 10초: 10 × \$0.2057 ≈ \$2.06
* 5초 클립을 720P로 `wan2.7-videoedit`: (5 + 5) × \$0.1028 ≈ \$1.03

작업을 만들 때 요청한 길이만큼 먼저 차감하고, 작업이 끝나면 Alibaba Cloud가 보고한 초 수로 정산해 차액을 환불하거나 추가 청구합니다. 입력 비디오가 있는 Wan 3.0 작업은 30초를 먼저 차감한 뒤 차액을 환불하므로, 잔액이 이 선차감액을 감당할 수 있어야 합니다.

실패한 작업은 과금되지 않지만, 같은 작업을 두 번 제출하면 두 번 과금됩니다. 자체 업무 ID를 각 `task_id`와 연결해 두고, 조건 없는 자동 재시도는 피하세요.

작업별 실제 청구 금액은 [호출 로그](https://api.laozhang.ai/log)에 있습니다. 실패한 작업에 청구가 남아 있다면 작업 ID와 함께 [고객 지원](mailto:hi@laozhang.ai)에 문의하세요.

비용은 출력 길이와 해상도로 정해지므로, `duration`과 `resolution`을 명시하고 작업을 만들기 전에 위 표로 비용을 추정하세요. Wan 모델과 그룹은 [AI 모델 API 가격표](https://docs.laozhang.ai/ko/models.md)에서 확인할 수 있습니다.

> [!TIP]
>
> 720p 안팎의 짧은 클립을 소리와 함께 만든다면 [MiniMax H3](https://docs.laozhang.ai/ko/api-capabilities/minimax-h3-video-generation.md)는 768P 5초에 \$0.25, [Muse](https://docs.laozhang.ai/ko/api-capabilities/muse-video-generation.md)는 10초에 \$0.30이며, 둘 다 `default` 그룹 키로 호출합니다. 모든 모델은 [비디오 API 비교](https://docs.laozhang.ai/ko/api-capabilities/video-generation-guide.md)에서 비교해 보세요.

## Wan 작업 처리 흐름

**1. 작업 생성**

JSON 본문과 `X-DashScope-Async: enable` 헤더로 `POST /wan/api/v1/services/aigc/video-generation/video-synthesis`를 호출합니다. 응답의 `output.task_id`를 저장하세요.

**2. 작업 조회**

5\~10초마다 `GET /v1/tasks/{task_id}`를 호출합니다. 중첩된 업스트림 필드가 아니라 최상위 `status` 필드로 분기하세요.

**3. 비디오 다운로드**

`status`가 `completed`이면 최상위 `result_url`에서 MP4를 내려받습니다. 서명된 오브젝트 스토리지 URL이므로 LaoZhang `Authorization` 헤더를 함께 보내지 마세요.

요청 규칙, 작업 상태, 필드 설명은 예제 뒤의 엔드포인트와 요청 규칙 절부터 이어집니다.

## 환경 설정

셸 예제는 `curl`과 `jq`를 사용합니다. jq는 `brew install jq` 또는 `sudo apt-get install jq`로 설치합니다. 키와 base URL을 한 번 설정해 두세요.

```bash theme={null}
export LAOZHANG_API_KEY="YOUR_API_KEY"   # LaoZhang API 키로 바꾸세요
export BASE_URL="https://api.laozhang.ai"
```

아래 각 생성 예제는 응답을 `create.json`에 저장하며, 작업 조회와 비디오 다운로드 단계에서 이 파일을 읽습니다.

## 텍스트로 비디오 만들기

```bash theme={null}
curl -sS -X POST "$BASE_URL/wan/api/v1/services/aigc/video-generation/video-synthesis" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-DashScope-Async: enable" \
  --data-raw '{
    "model": "wan2.7-t2v",
    "input": {
      "prompt": "해 질 녘의 등대, 천천히 다가가는 영화 같은 카메라 워크, 바위에 부딪히는 파도, 멀리 보이는 바닷새들"
    },
    "parameters": {
      "resolution": "720P",
      "duration": 5,
      "prompt_extend": true,
      "watermark": true
    }
  }' | tee create.json
```

생성 응답의 `output.task_id`에 작업 ID가 들어 있습니다.

```json theme={null}
{
  "output": {
    "task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "task_status": "PENDING"
  },
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

응답에 `output.task_id`가 없으면 `create.json`의 오류 메시지를 읽고, 아래 문제 해결 표를 확인하세요.

## 이미지로 비디오 만들기

```bash theme={null}
curl -sS -X POST "$BASE_URL/wan/api/v1/services/aigc/video-generation/video-synthesis" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-DashScope-Async: enable" \
  --data-raw '{
    "model": "wan2.7-i2v",
    "input": {
      "prompt": "밤의 철교 아래에서 그래피티 캐릭터가 살아 움직이며 신나게 랩을 합니다",
      "media": [
        {
          "type": "first_frame",
          "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/wpimhv/rap.png"
        },
        {
          "type": "driving_audio",
          "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/ozwpvi/rap.mp3"
        }
      ]
    },
    "parameters": {
      "resolution": "720P",
      "duration": 10,
      "prompt_extend": true,
      "watermark": true
    }
  }' | tee create.json
```

`driving_audio`는 선택 항목입니다. Alibaba Cloud는 이 오디오로 비디오를 구동해, 위 랩 예제처럼 립싱크나 박자에 맞춘 움직임을 만듭니다. `first_frame` 이미지와 함께 쓸 때만 동작하며, 다른 미디어처럼 공개 HTTPS URL이어야 합니다.

지원하는 오디오 형식, 길이, 파일 크기는 Alibaba Cloud [Wan 2.7 이미지 투 비디오 API 레퍼런스](https://help.aliyun.com/zh/model-studio/image-to-video-general-api-reference)를 참고하세요.

## 참조 이미지로 비디오 만들기

```bash theme={null}
curl -sS -X POST "$BASE_URL/wan/api/v1/services/aigc/video-generation/video-synthesis" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-DashScope-Async: enable" \
  --data-raw '{
    "model": "wan2.7-r2v",
    "input": {
      "prompt": "참조 이미지의 드레스를 입은 소녀가 노을 진 정원을 천천히 걷습니다. 영화 같은 조명",
      "media": [
        {
          "type": "reference_image",
          "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260402/fwjpqf/wan2.7-videoedit-change-clothes.png"
        }
      ]
    },
    "parameters": {
      "resolution": "720P",
      "duration": 5,
      "prompt_extend": true,
      "watermark": true
    }
  }' | tee create.json
```

## 비디오 편집

```bash theme={null}
curl -sS -X POST "$BASE_URL/wan/api/v1/services/aigc/video-generation/video-synthesis" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-DashScope-Async: enable" \
  --data-raw '{
    "model": "wan2.7-videoedit",
    "input": {
      "prompt": "비디오 속 소녀에게 참조 이미지의 옷을 입혀 주세요",
      "media": [
        {
          "type": "video",
          "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260403/nlspwm/T2VA_22.mp4"
        },
        {
          "type": "reference_image",
          "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260402/fwjpqf/wan2.7-videoedit-change-clothes.png"
        }
      ]
    },
    "parameters": {
      "resolution": "720P",
      "prompt_extend": true,
      "watermark": true
    }
  }' | tee create.json
```

## Wan 3.0 비디오 생성

Wan 3.0은 작업 종류마다 모델 ID를 나누지 않습니다. 모델 하나가 `input.media[]` 항목을 읽고 텍스트 투 비디오, 이미지 투 비디오, 참조 투 비디오, 비디오 편집 중 어떤 작업인지 판단합니다. 두 모델의 기능은 같습니다.

* `wan3.0-video`: 표준 모델
* `wan3.0-video-prime`: 더 빠르고 초당 가격이 더 높은 모델

두 모델은 같은 생성 엔드포인트를 쓰며, 작업 조회와 다운로드 방법도 Wan 2.7과 같습니다.

| 작업 | `input.media[]` |
| - | - |
| 텍스트 투 비디오 | `media` 생략 |
| 첫 프레임, 또는 첫·마지막 프레임 | `first_frame` 1개, 선택적으로 `last_frame` |
| 참조 투 비디오 | `reference_image` 최대 10개, `reference_video`와 `reference_audio`는 각각 최대 5개이며 유형별 합계 15초 이하 |
| 비디오 편집·연장 | `reference_video` 1개. 편집이나 연장 내용은 `prompt`에 적고, 연장할 때는 `ratio`를 `adaptive`로 설정 |

참조 투 비디오 프롬프트에서는 입력을 "image 1", "video 1", "audio 1"(图1, 视频1, 音频1)처럼 가리킬 수 있습니다. 번호는 같은 유형의 입력 안에서 매겨지는 순서입니다.

일부 `parameters`는 Wan 2.7과 다르게 동작합니다.

| 필드 | 값 |
| - | - |
| `resolution` | `480P`, `720P`, `1080P`. 기본값 `1080P` |
| `duration` | 2\~30초의 정수. 기본값 5. 입력 비디오가 있으면 입력과 출력의 합이 30초를 넘을 수 없음 |
| `ratio` | `adaptive`(기본값, 입력에 맞춰 비율 선택), `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` |
| `audio` | 기본값 `true`(소리 있는 비디오). `false`면 무음 비디오이며 가격은 같음 |

최소한의 텍스트 투 비디오 요청입니다.

```bash theme={null}
curl -sS -X POST "$BASE_URL/wan/api/v1/services/aigc/video-generation/video-synthesis" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-DashScope-Async: enable" \
  --data-raw '{
    "model": "wan3.0-video",
    "input": {
      "prompt": "달빛 비치는 지붕 위를 새끼 고양이가 달려가고, 멀리서 네온사인이 깜빡입니다. 영화 같은 분위기, 부드러운 카메라 움직임"
    },
    "parameters": {
      "resolution": "720P",
      "ratio": "16:9",
      "duration": 5
    }
  }' | tee create.json
```

기존 클립의 스타일을 바꾸려면 `reference_video`로 보냅니다. 청구 초에는 입력 비디오 길이도 포함됩니다(위의 과금과 가격 절 참고).

```bash theme={null}
curl -sS -X POST "$BASE_URL/wan/api/v1/services/aigc/video-generation/video-synthesis" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-DashScope-Async: enable" \
  --data-raw '{
    "model": "wan3.0-video-prime",
    "input": {
      "prompt": "장면 전체를 클레이 애니메이션으로 바꿔 주세요",
      "media": [
        {
          "type": "reference_video",
          "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260402/ldnfdf/wan2.7-videoedit-style-change.mp4"
        }
      ]
    },
    "parameters": {
      "resolution": "720P",
      "ratio": "adaptive"
    }
  }' | tee create.json
```

앞에서처럼 `create.json`에서 `TASK_ID`를 읽고, 다음 절의 방법으로 조회하고 내려받으세요. 문서(`file`)나 웹 페이지(`link`) 같은 다른 입력은 Alibaba Cloud [Wan3.0 비디오 생성 API 레퍼런스](https://help.aliyun.com/zh/model-studio/wan3-video-generation-api-reference)(중국어)를 참고하세요.

## 작업 조회와 비디오 다운로드

`create.json`에서 작업 ID를 읽어 작업 상태를 확인합니다.

```bash theme={null}
TASK_ID=$(jq -r '.output.task_id' create.json)

curl -sS "$BASE_URL/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" | tee task.json | jq '{status, progress}'
```

`status`가 `submitted`나 `in_progress`가 아닐 때까지 5\~10초마다 다시 요청하세요.

완료된 작업은 다음과 같습니다. 최상위 `status`와 `result_url` 필드를 기준으로 처리하세요.

```json theme={null}
{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "object": "task",
  "platform": "wan",
  "action": "text_to_video",
  "task_type": "text_to_video",
  "status": "completed",
  "progress": "100%",
  "result_url": "https://dashscope-xxx.oss-accelerate.aliyuncs.com/...",
  "result": {
    "data": {
      "model": "wan2.7-t2v",
      "parameters": {
        "resolution": "720P",
        "duration": 5,
        "prompt_extend": true,
        "watermark": true
      }
    }
  }
}
```

비디오는 `Authorization` 헤더 없이 내려받으세요. `result_url`은 서명된 오브젝트 스토리지 URL이라, 인증 헤더를 추가하면 403 오류가 날 수 있습니다.

```bash theme={null}
RESULT_URL=$(jq -r '.result_url' task.json)
curl -L -o wan-output.mp4 "$RESULT_URL"
```

## Python 클라이언트

Python 표준 라이브러리만 쓰는 클라이언트입니다(Python 3.8 이상). 텍스트 투 비디오 작업을 만들고 최대 20분 동안 조회한 뒤 MP4를 저장합니다.

```python theme={null}
import json
import os
import time
import urllib.request
from urllib.error import HTTPError

BASE_URL = "https://api.laozhang.ai"
API_KEY = os.environ["LAOZHANG_API_KEY"]
POLL_INTERVAL = 10   # 상태 조회 간격(초)
TIMEOUT = 20 * 60    # 20분이 지나면 대기를 중단합니다


def request(method, path, body=None, extra_headers=None):
    headers = {"Authorization": f"Bearer {API_KEY}"}
    if extra_headers:
        headers.update(extra_headers)
    data = None
    if body is not None:
        headers["Content-Type"] = "application/json"
        data = json.dumps(body).encode("utf-8")
    req = urllib.request.Request(BASE_URL + path, data=data, method=method, headers=headers)
    try:
        with urllib.request.urlopen(req, timeout=60) as resp:
            return json.loads(resp.read().decode("utf-8"))
    except HTTPError as exc:
        error_body = exc.read().decode("utf-8", errors="replace")
        raise RuntimeError(f"HTTP {exc.code}: {error_body}") from exc


created = request(
    "POST",
    "/wan/api/v1/services/aigc/video-generation/video-synthesis",
    {
        "model": "wan2.7-t2v",
        "input": {"prompt": "해 질 녘의 등대, 영화 같은 조명, 천천히 다가가는 카메라"},
        "parameters": {"resolution": "720P", "duration": 5, "prompt_extend": True},
    },
    {"X-DashScope-Async": "enable"},
)
task_id = created["output"]["task_id"]
print("작업 ID:", task_id)

deadline = time.monotonic() + TIMEOUT
while True:
    task = request("GET", f"/v1/tasks/{task_id}")
    status = str(task.get("status", "")).lower()
    print("상태:", status, task.get("progress", ""))

    if status == "completed":
        # result_url은 서명 URL이므로 Authorization 헤더 없이 내려받습니다.
        urllib.request.urlretrieve(task["result_url"], "wan-output.mp4")
        print("wan-output.mp4 저장 완료")
        break
    if status not in ("submitted", "in_progress"):
        # failed 또는 그 밖의 최종 상태
        detail = task.get("error") or task.get("fail_reason") or task
        raise RuntimeError(f"작업 {task_id}이(가) {status!r} 상태로 끝났습니다: {detail}")
    if time.monotonic() > deadline:
        raise TimeoutError(f"작업 {task_id}이(가) 20분 안에 끝나지 않았습니다")
    time.sleep(POLL_INTERVAL)
```

## 엔드포인트와 요청 규칙

```text theme={null}
작업 생성        POST /wan/api/v1/services/aigc/video-generation/video-synthesis
작업 상태 조회   GET  /v1/tasks/{task_id}
MP4 다운로드     GET  {result_url}   (서명 URL, Authorization 헤더 없이)
```

| 설정 | 값 |
| - | - |
| base URL | `https://api.laozhang.ai` |
| 인증 | `Authorization: Bearer $LAOZHANG_API_KEY` |
| 생성 요청 본문 | `application/json` |
| 생성 시 필수 헤더 | `X-DashScope-Async: enable` |
| 조회 간격 | 5\~10초 |
| 클라이언트 타임아웃 | 20분 |

## 작업 상태

`GET /v1/tasks/{task_id}`가 반환하는 최상위 `status` 필드로 분기하세요.

| 상태 | 최종 여부 | 할 일 |
| - | - | - |
| `submitted` | 아니요 | 작업이 접수되었습니다. 계속 조회하세요. |
| `in_progress` | 아니요 | 비디오를 생성하는 중입니다. 계속 조회하세요. |
| `completed` | 예 | `result_url`에서 MP4를 내려받으세요. |
| `failed` | 예 | `error.message` 또는 `fail_reason`을 읽고 조회를 멈추세요. |
| 그 밖의 값 | 예 | 조회를 멈추고 응답 전체를 저장하세요. 비디오가 아직 필요하면 새 작업을 만드세요. |

생성 응답에는 DashScope 원래 상태인 `output.task_status`도 있으며, 새 작업이면 보통 `PENDING`입니다. 이 값은 작업이 접수되었는지 확인하는 데만 쓰고, 이후에는 `GET /v1/tasks/{task_id}`의 최상위 `status`로 분기하세요.

`submitted`나 `in_progress`일 때만 계속 조회하세요. 작업이 취소되었거나 24시간이 지난 뒤 조회한 경우처럼 그 밖의 값은 모두 최종 상태로 처리해야, 예상하지 못한 상태 때문에 클라이언트가 끝없이 조회하는 일을 막을 수 있습니다.

Wan의 진행률은 단계가 거칩니다. `progress`가 한동안 `30%`에 머물다가 `100%`로 뛸 수 있습니다.

## 모델과 입력 방식

| 모델 ID | 작업 | `input.media[]` |
| - | - | - |
| `wan2.7-t2v` | 텍스트 투 비디오 | `media` 생략 |
| `wan2.7-i2v` | 이미지 투 비디오, 오디오 구동 선택 가능 | `first_frame` 1개. `last_frame`, `driving_audio`는 선택 |
| `wan2.7-r2v` | 참조 투 비디오 | `reference_image`와 `reference_video` 합계 1\~5개 |
| `wan2.7-videoedit` | 비디오 편집 | `video` 1개(2\~10초), 선택적으로 `reference_image` 최대 4개 |
| `wan3.0-video`, `wan3.0-video-prime` | 텍스트·이미지·참조 투 비디오, 비디오 편집과 연장 | 작업에 따라 다름. 위의 Wan 3.0 비디오 생성 절 참고 |

Wan 2.6 모델(`wan2.6-t2v`, `wan2.6-i2v`, `wan2.6-r2v`, `wan2.6-r2v-flash`)은 2026년 10월 14일에 종료되었습니다. 아직 호출하고 있다면 대응하는 Wan 2.7 모델이나 Wan 3.0으로 바꾸세요.

모델 ID는 2026년 10월 14일 기준 LaoZhang API 공개 가격표를 따랐습니다. `wan2.7-image-pro`는 이미지 모델이라 이 비디오 엔드포인트에서는 동작하지 않습니다.

## 요청 본문

| 필드 | 타입 | 필수 | 설명 |
| - | - | - | - |
| `model` | string | 예 | 모델 ID. 예: `wan2.7-t2v` |
| `input.prompt` | string | 모델에 따라 다름 | 자연어 프롬프트. 텍스트 투 비디오와 참조 투 비디오는 필수, 이미지 투 비디오와 비디오 편집은 선택 |
| `input.media` | array | 모델에 따라 다름 | 텍스트 투 비디오는 생략, 다른 작업은 필수 |
| `parameters.resolution` | string | 아니요 | Wan 2.7은 `720P` 또는 `1080P`, Wan 3.0은 `480P`도 가능. 대문자 `P` 사용 |
| `parameters.duration` | integer | 아니요 | 초 단위 정수. `wan2.7-t2v`는 2\~15. 문자열이 아닌 숫자로 보내세요 |
| `parameters.prompt_extend` | boolean | 아니요 | 모델이 프롬프트를 보강하도록 허용 |
| `parameters.watermark` | boolean | 아니요 | AI 생성 워터마크 추가 |
| `parameters.seed` | integer | 아니요 | 결과 재현성을 높이는 시드 |

허용 값은 모델마다 다릅니다. 위 범위는 Alibaba Cloud [텍스트 투 비디오 API 레퍼런스](https://help.aliyun.com/zh/model-studio/text-to-video-api-reference)를 따랐습니다. 다른 모델은 해당 모델의 Alibaba Cloud 레퍼런스(중국어)를 확인하세요.

* [Wan 2.7 이미지 투 비디오](https://help.aliyun.com/zh/model-studio/image-to-video-general-api-reference)
* [Wan 2.7 참조 투 비디오](https://help.aliyun.com/zh/model-studio/wan-video-to-video-api-reference)
* [Wan 2.7 비디오 편집](https://help.aliyun.com/zh/model-studio/wan-video-editing-api-reference)
* [Wan 3.0 비디오 생성](https://help.aliyun.com/zh/model-studio/wan3-video-generation-api-reference)

### 미디어 입력

| `type` | 용도 |
| - | - |
| `first_frame` | 이미지 투 비디오의 첫 프레임. `wan2.7-r2v`도 1개 받음 |
| `last_frame` | 마지막 프레임. 선택한 모델이 지원할 때 |
| `reference_image` | 참조 투 비디오나 비디오 편집의 참조 이미지 |
| `reference_video` | 참조 비디오. `wan2.7-r2v`에서는 피사체와 목소리를 제공하고, Wan 3.0에서는 편집·연장할 클립이기도 함 |
| `reference_audio` | Wan 3.0의 참조 오디오 |
| `driving_audio` | `wan2.7-i2v` 이미지 투 비디오 작업을 구동하는 오디오 |
| `video` | `wan2.7-videoedit` 비디오 편집의 원본 비디오 |
| `file`, `link` | Wan 3.0의 참조 문서 또는 공개 웹 페이지. 둘 중 하나만 보냄 |

모든 미디어 `url`은 Alibaba Cloud가 직접 가져올 수 있는 공개 HTTPS 링크여야 합니다. 로그인이나 쿠키가 필요한 링크, 사설 네트워크 주소, 작업이 실행되기 전에 만료되는 링크는 작업 실패의 원인이 됩니다.

## 운영 환경 팁

* **작업 ID부터 저장하세요.** 생성 호출이 반환되면 바로 `output.task_id`를 자체 작업 ID와 함께 저장해, 워커가 재시작되어도 중복 작업을 만들지 않고 조회를 이어 가게 하세요.
* **생성 호출을 재시도하기 전에 확인하세요.** 접수된 생성 요청은 각각 별도의 작업이 됩니다. 생성 요청이 타임아웃되면 다시 보내기 전에 자체 기록과 호출 로그를 확인하세요.
* **조회에 한도를 두세요.** 5\~10초마다 확인하고 20분이 지나면 멈추며, `submitted`나 `in_progress`가 아닌 상태는 모두 최종 상태로 처리하세요.
* **바로 내려받으세요.** Alibaba Cloud는 작업 ID와 비디오 URL을 24시간 보관합니다. MP4를 자체 저장소에 복사하고, 사용자에게는 서명 링크가 아닌 자체 URL을 제공하세요.
* **입력에 계속 접근할 수 있게 하세요.** 미디어는 작업이 끝날 때까지 열리는 공개 HTTPS URL에 두세요.
* **비용을 관리하세요.** `duration`과 `resolution`을 명시하고, 호출 로그에서 작업별 청구 금액을 확인하세요.
* **앱마다 토큰을 따로 쓰세요.** 애플리케이션이나 환경마다 전용 `Wan` 토큰을 두면 로그와 청구 내역을 확인하기 쉽습니다.

## 문제 해결

| 증상 | 가능한 원인 | 해결 방법 |
| - | - | - |
| `未提供令牌`(토큰이 제공되지 않음) | `Authorization` 헤더 누락 | `Authorization: Bearer $LAOZHANG_API_KEY`를 보내세요 |
| `Current group Wan has no available channels for model ...` | 잘못된 모델 ID, Wan 2.6 같은 종료된 모델, 또는 `Wan` 그룹에 라우팅되지 않은 모델 | 모델 표와 ID를 대조하세요. ID가 맞다면 모델 ID와 요청 시각을 적어 [고객 지원](mailto:hi@laozhang.ai)에 문의하세요 |
| `[InvalidParameter] Field required: input.media` | `media` 누락, 또는 요청을 `/v1/videos`로 보냄 | Wan 작업 엔드포인트를 쓰고 `input.media[]`를 보내세요 |
| `任务不存在`(작업이 존재하지 않음) | 잘못된 작업 ID, 또는 생성 후 24시간 경과 | 정확한 `output.task_id`를 쓰고, 만료되었다면 새 작업을 만드세요 |
| 다운로드 시 403 | `Authorization` 헤더를 보냈거나 URL이 24시간 경과 | `Authorization` 없이 내려받고, URL이 만료되었다면 새 작업을 만드세요 |

## 자주 묻는 질문

### 5초 비디오는 얼마인가요?

2026년 10월 14일 기준 가격으로, 비디오만 출력하는 작업의 비용입니다.

* `wan3.0-video`: 720P 약 \$0.51, 1080P 약 \$1.03
* `wan3.0-video-prime`: 720P 약 \$0.77, 1080P 약 \$1.54
* Wan 2.7: 720P 약 \$0.51, 1080P 약 \$0.86

비용은 길이에 비례하므로 10초면 대략 두 배입니다. `resolution`을 지정하지 않으면 1080P로 과금되고, 입력 비디오가 있는 작업은 입력 길이가 더해집니다. 자세한 내용은 위의 과금과 가격 절을 참고하세요.

### `X-DashScope-Async: enable`을 꼭 보내야 하나요?

네, 모든 생성 요청에 보내야 합니다. Wan HTTP API는 비동기로만 동작하며, 이 헤더 없이 생성 `POST`를 보내면 `current user api does not support synchronous calls` 오류가 납니다.

`GET /v1/tasks/{task_id}` 조회와 `result_url` 다운로드에는 필요 없습니다.

### `resolution`과 `duration`을 생략하면 어떻게 되나요?

1080P로 출력됩니다. Alibaba Cloud API 레퍼런스에 따르면 Wan 2.7 모델 4종(`wan2.7-t2v`, `wan2.7-i2v`, `wan2.7-r2v`, `wan2.7-videoedit`)과 Wan 3.0의 기본값은 모두 1080P입니다.

* 텍스트 투 비디오, 이미지 투 비디오, 참조 투 비디오는 기본 5초입니다.
* Wan 2.7 비디오 편집은 원본 비디오 길이를 유지합니다.

따라서 파라미터 없는 텍스트 투 비디오 작업은 1080P 5초로 과금됩니다.

* Wan 2.7: 약 \$0.86
* `wan3.0-video`: 약 \$1.03
* `wan3.0-video-prime`: 약 \$1.54

이 페이지의 예제는 `720P`를 명시합니다. 비용을 예측할 수 있도록 모든 요청에 `resolution`과 `duration`을 지정하고, 위의 과금과 가격 절로 가격을 추정하세요.

### 세로나 정사각형 비디오는 어떻게 만드나요?

텍스트 투 비디오와 참조 투 비디오는 `parameters.ratio`로 지정하고, 다른 작업은 입력의 비율을 따릅니다.

* **텍스트 투 비디오, 참조 투 비디오:** 아래 비율 중 하나
  * `16:9`(기본값)
  * `9:16`(예: 720P에서는 720×1280 비디오)
  * `1:1`
  * `4:3`
  * `3:4`
* **이미지 투 비디오:** `ratio`를 받지 않고 첫 프레임의 비율을 따름
* **비디오 편집:** `ratio`를 지정하지 않으면 원본 비디오의 비율 유지
* **Wan 3.0:** 기본값 `adaptive`(입력에 맞춰 비율 선택)이며 `21:9`도 지원

가격은 해상도 단계와 출력 초 수로만 정해지므로, 같은 단계라면 가로, 세로, 정사각형 비디오의 가격이 같습니다. 모델별 허용 값은 Alibaba Cloud [텍스트 투 비디오 API 레퍼런스](https://help.aliyun.com/zh/model-studio/text-to-video-api-reference)(중국어)를 참고하세요.

### 비디오에 소리가 있나요? 내 오디오로 캐릭터가 말하게 할 수 있나요?

둘 다 가능합니다. Alibaba Cloud에 따르면 Wan 2.7은 기본적으로 소리가 있는 비디오를 출력하며, 화면에 맞는 배경 음악, 효과음, 목소리를 생성합니다.

내 오디오에 입 모양을 맞추려면 위의 이미지로 비디오 만들기 예제처럼 `wan2.7-i2v`를 쓰고 `input.media[]`에 `driving_audio` 항목을 추가하세요. 오디오는 WAV 또는 MP3, 길이 2\~30초여야 하며 `duration`보다 긴 부분은 잘립니다.

Wan 3.0도 기본적으로 소리를 출력합니다. 무음 비디오가 필요하면 `"audio": false`를 보내세요. 가격은 같습니다.

참조 투 비디오는 참조 비디오의 목소리를 재사용할 수 있고, 비디오 편집은 원본 비디오의 소리를 유지할 수 있습니다. 관련 파라미터는 [Wan 2.7 참조 투 비디오 API 레퍼런스](https://help.aliyun.com/zh/model-studio/wan-video-to-video-api-reference)와 [Wan 2.7 비디오 편집 API 레퍼런스](https://help.aliyun.com/zh/model-studio/wan-video-editing-api-reference)(모두 중국어)를 참고하세요.

### "AI 生成" 워터마크는 어떻게 없애나요?

`parameters`에 `"watermark": false`를 보내거나 `watermark`를 생략하세요. Alibaba Cloud는 기본적으로 워터마크를 넣지 않습니다. 이 페이지의 예제는 `true`를 보내므로 비디오 오른쪽 아래에 워터마크가 들어갑니다. 운영 환경에서 예제를 쓰기 전에 바꾸세요.

### 클라이언트 타임아웃이나 실패 후 작업을 다시 제출해도 되나요?

먼저 작업을 확인하세요. 클라이언트 타임아웃은 작업 실패를 뜻하지 않습니다. 같은 `task_id`를 24시간까지 계속 조회하세요. 새 생성 요청은 두 번째 작업을 만들어 다시 과금됩니다. `status`가 `failed`나 다른 최종 값이 된 뒤에만 요청을 고쳐 새 작업을 만드세요.

실패한 작업은 과금되지 않으며, 작업별 실제 청구 금액은 [호출 로그](https://api.laozhang.ai/log)에 있습니다. 위의 과금과 가격 절과 작업 상태 절을 참고하세요.

### 호출 로그에 작업 하나가 두 번 청구된 이유는 무엇인가요?

작업을 만들 때 요청한 길이만큼 차감하고, 작업이 끝나면 정산합니다.

* Alibaba Cloud가 같은 초 수를 보고하면 로그에는 한 줄만 남습니다.
* 초 수가 다르면 두 번째 줄("Wan 任务完成，按实际时长调整")에서 차액을 환불하거나 추가 청구합니다.

보통은 입력 비디오 때문이며, 입력 비디오 길이도 청구에 포함됩니다. 입력 비디오가 있는 Wan 3.0 작업은 30초를 먼저 차감하고 나중에 차액을 환불합니다. 두 줄을 더한 값이 작업의 실제 비용입니다. 위의 과금과 가격 절을 참고하세요.

### `progress`가 30%에서 멈추면 작업이 멈춘 건가요?

아닙니다. 업스트림 서비스가 진행률을 큰 단계로 보고하므로 `30%`에서 잠시 머무는 것은 정상입니다. 최상위 `status`가 `in_progress`인 동안 계속 조회하세요. 위의 작업 상태 절을 참고하세요.

## 관련 문서

* [Seedance 2.0 / 2.5 비디오 생성 API](https://docs.laozhang.ai/ko/api-capabilities/seedance2-video-generation.md): LaoZhang API의 또 다른 비디오 모델 계열
* [Sora 2 API 종료: Wan 또는 Seedance로 이전](https://docs.laozhang.ai/ko/api-capabilities/sora2/official-forward.md)
* [AI 모델 API 가격표](https://docs.laozhang.ai/ko/models.md)
* [모델 사용 가능 여부 확인 방법](https://docs.laozhang.ai/en/faq/model-availability.md)
* [호출 로그 확인 방법](https://docs.laozhang.ai/en/faq/call-logs.md)
* [데이터와 로그의 범위](https://docs.laozhang.ai/en/faq/data-security.md)
* Alibaba Cloud(중국어): [텍스트 투 비디오 API 레퍼런스](https://help.aliyun.com/zh/model-studio/text-to-video-api-reference), [Wan 2.7 이미지 투 비디오 API 레퍼런스](https://help.aliyun.com/zh/model-studio/image-to-video-general-api-reference), [Model Studio 가격](https://help.aliyun.com/zh/model-studio/model-pricing)


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