Wan 3.0 API 연동 튜토리얼: curl, Python 및 전체 파라미터

Wan 3.0 표준판(wan3.0-video)은 HiAPI에서 통합 비동기 인터페이스를 사용합니다: POST /v1/tasks로 제출하고 taskId를 받은 뒤, GET /v1/tasks/{taskId}로 결과를 조회합니다. 프롬프트 한 줄만으로도 소리가 포함된 영상을 생성할 수 있으며, 첫 프레임, 마지막 프레임 또는 최대 10장의 레퍼런스 이미지, 5개의 레퍼런스 동영상, 5개의 레퍼런스 오디오를 함께 넣어 생성을 제어할 수도 있습니다. 이 글에서는 바로 실행 가능한 curl과 Python 예제, 현재의 전체 파라미터, 그리고 서비스 출시 전에 주의할 몇 가지 사항을 다룹니다.

가격 먼저 보기

해상도	초당	5초
480P	$0.04	$0.20
720P	$0.08	$0.40
1080P(기본값)	$0.16	$0.80

HiAPI 현재 가격, 2026년 10월 18일 기준 확인. 사운드는 기본으로 켜져 있으며 추가 요금이 없습니다.

기본값 주의: resolution을 쓰지 않으면 1080P, duration을 쓰지 않으면 5초로 한 건에 $0.80입니다. 프롬프트를 시험할 때는 반드시 "resolution": "480P"를 명시하세요.

더 빠른 생성을 원하면 고속판 wan3.0-video-prime을 쓸 수 있으며, 가격은 표준판의 두 배가 넘습니다(480P 초당 $0.0875).

실제 생성 영상 하나

480P, 16:9, 5초, 사운드 포함:

A steaming noodle stall at a night market, close on the cook's hands as she lifts a tangle of noodles from a boiling pot and swirls them into a blue-rimmed bowl; slow push-in, warm tungsten light against cool blue street glow, steam drifting through the frame. Sound: rolling boil, the clink of a ladle, crowd murmur and a scooter passing in the distance.

이 프롬프트로 생성 →

wan3.0-video, 480P, 5초, $0.20.

첫 작업 실행하기

준비: 콘솔에서 API Key를 생성하세요. 신규 사용자 가입 시 200 포인트를 지급합니다.

curl: 작업 제출

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video",
    "input": {
      "prompt": "A steaming cup of coffee on a wooden table, soft morning light, gentle steam rising. Sound: a quiet cafe.",
      "resolution": "480P",
      "duration": 5,
      "aspect_ratio": "16:9"
    }
  }'

즉시 taskId가 반환되고 생성은 백그라운드에서 진행됩니다:

{"code": 200, "message": "success", "data": {"taskId": "tk-hiapi-..."}}

curl: 결과 조회

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-... \
  -H "Authorization: Bearer $HIAPI_KEY"

data.status가 success가 되면 data.output[0].url이 영상 주소입니다. 임시 주소는 약 7일 후에 만료되므로 가능한 한 빨리 다운로드하여 저장하세요. fail은 실패를 의미하며 요금이 부과되지 않습니다.

Python

import os, time, requests

KEY = os.environ["HIAPI_KEY"]
BASE = "https://api.hiapi.ai/v1"
H = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}

r = requests.post(f"{BASE}/tasks", headers=H, json={
    "model": "wan3.0-video",
    "input": {
        "prompt": "A steaming cup of coffee on a wooden table, soft morning light, gentle steam rising. Sound: a quiet cafe.",
        "resolution": "480P",
        "duration": 5,
    },
})
task_id = r.json()["data"]["taskId"]

while True:
    d = requests.get(f"{BASE}/tasks/{task_id}", headers=H).json()["data"]
    if d["status"] in ("success", "fail"):
        break
    time.sleep(10)

print(d["output"][0]["url"] if d["status"] == "success" else d)

짧은 영상은 보통 몇 분 안에 생성되므로 폴링 간격은 10초면 충분합니다.

전체 파라미터

필드	필수	값	설명
prompt	예	텍스트	장면, 동작, 카메라, 조명, 사운드를 모두 여기에 작성하며, 레퍼런스 모드에서는 Image1, Video1, Audio1로 소재를 지칭합니다
resolution	아니오	480P / 720P / 1080P(기본값)	초당 단가를 결정합니다
duration	아니오	정수 2–30, 기본값 5	레퍼런스 동영상 총 길이에 출력 길이를 더해 30초를 넘을 수 없습니다
aspect_ratio	아니오	adaptive(기본값) / 16:9 / 4:3 / 1:1 / 3:4 / 9:16	adaptive는 소재와 프롬프트에 따라 자동 선택합니다
audio	아니오	불리언, 기본값 true	동기화된 오디오 트랙 포함 여부
seed	아니오	0–2147483647	고정하면 재현이 용이합니다
first_frame_url	아니오	이미지 URL 1개	첫 프레임 모드
last_frame_url	아니오	이미지 URL 1개	첫 프레임과 함께 사용하여 마지막 프레임을 지정합니다
reference_image_urls	아니오	최대 10개	레퍼런스 이미지
reference_video_urls	아니오	최대 5개, 개별 1–15초, 합계 ≤15초	레퍼런스 동영상
reference_audio_urls	아니오	최대 5개 WAV/MP3	이미지 또는 동영상과 함께 사용해야 합니다
reference_file_urls	아니오	최대 1개	문서 또는 프레젠테이션
reference_link_urls	아니오	최대 1개	로그인이 필요 없는 웹페이지

두 모드는 함께 사용할 수 없습니다: 첫/마지막 프레임 모드와 reference_* 레퍼런스 모드는 상호 배타적이며, 한 번의 요청에는 하나만 선택할 수 있습니다.

레퍼런스 모드 작성 예시:

{
  "model": "wan3.0-video",
  "input": {
    "prompt": "Use Image1 as the product: slow quarter orbit around it on a wooden counter, soft morning window light. Sound: gentle pouring water.",
    "reference_image_urls": ["https://example.com/product.jpg"],
    "resolution": "480P",
    "duration": 5
  }
}

자주 나오는 오류

모두 제출 시 동기적으로 HTTP 400이 반환되며, 작업이 생성되지 않고 요금도 부과되지 않습니다:

• duration: maximum: got 99, want 30: 길이가 30초를 초과했습니다.
• resolution: value must be one of '480P', '720P', '1080P': 해상도의 P는 대문자여야 합니다.
• additional properties 'negative_prompt', 'image_urls' not allowed: 이 모델에는 네거티브 프롬프트가 없으며, 레퍼런스 이미지 필드 이름은 image_urls가 아니라 reference_image_urls입니다.
• API Key 오류는 HTTP 401, 잔액 부족은 402를 반환합니다.

작업 생성 후 실패한 경우 결과 조회에서 status: "fail"로 표시되며 HTTP 상태 코드는 여전히 200이므로 data.status를 확인해야 합니다.

서비스 출시 전 주의

• 폴링 대신 콜백 사용: 요청 본문 최상위에 "callback": {"url": "https://당신의도메인/hiapi/callback", "when": "final"}을 추가하면 작업 종료 시 HiAPI가 능동적으로 알려줍니다. callback은 최상위에 두고 input 안에 넣지 마세요.
• 중복 과금 방지: 제출 시 Idempotency-Key 요청 헤더를 포함하세요. 네트워크 타임아웃으로 재시도할 때 동일한 key를 사용하면 원래의 taskId가 반환되며 작업이 중복 생성되지 않습니다.
• 즉시 저장: 임시 주소는 약 7일 후 만료됩니다. 장기 보관이 필요하면 생성 시 "storage": "persistent"를 전달하거나 이후에 영구 저장소로 전환하세요. 자세한 내용은 작업 생성 문서를 참고하세요.

자주 묻는 질문

레퍼런스 이미지 없이도 사용할 수 있나요?

가능합니다. prompt만 작성해도 영상을 생성할 수 있으며, 레퍼런스 소재는 선택 사항입니다.

사운드에 추가 요금이 있나요?

없습니다. audio는 기본으로 켜져 있으며, 가격은 해상도와 초 수에만 따라 결정됩니다. 사운드가 필요 없으면 false를 전달하세요.

세로 화면을 원하나요?

aspect_ratio에 9:16을 전달하세요.

첫 프레임과 레퍼런스 이미지를 함께 사용할 수 있나요?

불가능합니다. 둘 중 하나만 선택하세요.

더 많은 프롬프트 작성법은 Wan 3.0 프롬프트 모음에서 확인할 수 있으며, 4개 장면 모두 실제 생성 영상이 첨부되어 있습니다. 위의 국수 가판대 프롬프트를 그대로 복사해서 $0.20으로 한 편 생성할 수도 있습니다.