Wan 3.0 Prime API 한국어 튜토리얼: 텍스트 생성, 첫·마지막 프레임, 참조 기반 영상 생성

TL;DR

• Wan 3.0 Prime(万相 3.0 가속판)은 알리바바 Wan 3.0의 고속 라인으로, 모델명은 wan3.0-video-prime입니다. 하나의 모델로 텍스트 기반 영상 생성, 첫·마지막 프레임 기반 영상 생성, 참조 기반 영상 생성을 모두 할 수 있으며, 참조 소재로 이미지, 오디오, 심지어 문서나 웹페이지까지 사용할 수 있습니다. 길이는 2–30초, 기본으로 소리가 포함됩니다. 모델 페이지 열기에서 온라인으로 생성할 수 있습니다.
• 초 단위 과금: 480P 초당 $0.0875, 720P $0.18, 1080P $0.36. 5초 480P는 단 $0.4375.
• 두 가지 함정: 해상도는 반드시 대문자로 480P / 720P / 1080P를 써야 하며, 기본값은 1080P입니다. 그리고 Prime은 참조 영상을 받지 않습니다.

먼저 결과 보기

텍스트 기반 영상 생성, 480P, 5초, 소리 포함(소리를 켜면 빗소리, 차량 소음, 구이판 지글거리는 소리가 들립니다):

Rain streaking down a narrow neon-lit alley at night; a slow dolly-forward past
steaming street-food stalls, magenta and cyan reflections rippling in the wet
pavement, a tabby cat darting between crates mid-shot. Ambient sound: steady
rain, distant traffic hiss, the sizzle of a grill and a low synth drone.

이 프롬프트로 생성하기 → (5초, 480P, 16:9, 소리 켬)

wan3.0-video-prime, 480P, 5초, 소리 포함, $0.4375.

참조 기반 영상 생성: 도자기 여우 장식품 이미지를 전달해 움직이게 하되, 외형은 그대로 유지합니다.

Bring the referenced ceramic fox figurine to life: it slowly turns its head
toward camera, blinks, and tilts with a curious expression; subtle idle
breathing, a light breeze stirring the tiny scarf, soft studio key light on a
clean seamless backdrop, smooth loopable motion.

이 프롬프트로 생성하기 → (참조 이미지를 업로드, 5초, 480P, 9:16)

wan3.0-video-prime, 참조 이미지, 480P, 5초, 9:16, $0.4375.

curl: 첫 번째 영상

5초 480P, $0.4375:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video-prime",
    "input": {
      "prompt": "一只橘猫趴在洒满阳光的窗台上打哈欠，尾巴轻轻摆动，镜头缓慢推近，暖色调",
      "resolution": "480P",
      "duration": 5,
      "aspect_ratio": "16:9",
      "audio": false
    }
  }'

data.taskId가 반환되면 GET /v1/tasks/{taskId}로 status가 success인지 확인한 뒤 output[0].url을 다운로드합니다.

Python: 제출, 폴링, 다운로드

# pip install requests；先 export HIAPI_KEY=你的 Key
import os, time, uuid, requests

API = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def generate(timeout_s=900, **inp):
    # 重试提交同一个任务时带同一个 Idempotency-Key，避免重复扣费
    r = requests.post(API, json={"model": "wan3.0-video-prime", "input": inp},
                      headers={**H, "Idempotency-Key": str(uuid.uuid4())}, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(10)
    raise TimeoutError(task_id)

# 参考生视频：让参考图里的产品动起来，480P 5 秒（$0.4375）
url = generate(
    prompt="让参考图里的香水瓶在黑色大理石上缓慢旋转，侧逆光扫过瓶身，镜头缓慢推近",
    reference_image_urls=["https://your-cdn.example.com/perfume.jpg"],
    resolution="480P", duration=5, aspect_ratio="9:16", audio=False,
)
with open("clip.mp4", "wb") as f:
    f.write(requests.get(url).content)

세 가지 사용법

사용법	전달할 것	설명
텍스트 기반 영상 생성	prompt만 전달
첫·마지막 프레임	first_frame_url, 선택적으로 last_frame_url 추가 가능	참조 소재와 동시에 사용할 수 없음
참조 기반 영상 생성	reference_image_urls(최대 10장), reference_audio_urls(최대 5개, 이미지와 함께 사용해야 함), reference_file_urls 또는 reference_link_urls(각 최대 1개, 둘 중 하나만)	프롬프트에서 순서대로 Image1, Audio1로 소재를 지칭

참조 문서와 웹페이지는 Wan 3.0의 특징입니다. 브랜드 가이드 PDF나 상품 페이지 링크를 모델에 넘겨 그 안의 정보대로 영상을 만들 수 있습니다. 웹페이지는 로그인 없이 열 수 있어야 합니다.

파라미터 일람

파라미터	값	설명
prompt	문자열, 필수	장면, 동작, 카메라, 조명, 소리를 작성
resolution	480P / 720P / 1080P, 기본 1080P	대문자, 가격을 직접 결정
duration	2–30의 정수, 기본 5	단위 초
aspect_ratio	adaptive 16:9 4:3 1:1 3:4 9:16, 기본 adaptive	adaptive는 소재와 프롬프트에 따라 자동 선택
audio	기본 true	동기 오디오 트랙, 추가 요금 없음
seed	0–2147483647	시드 고정으로 재현 용이
first_frame_url / last_frame_url	이미지 주소	첫·마지막 프레임
reference_image_urls 등	위 표 참조	참조 기반 영상 생성

비용 계산

길이	480P($0.0875/초)	720P($0.18/초)	1080P($0.36/초)
5초	$0.4375	$0.90	$1.80
10초	$0.875	$1.80	$3.60
30초	$2.625	$5.40	$10.80

먼저 480P로 프롬프트를 조정하고, 확정되면 720P나 1080P로 올리세요. 시간이 촉박하지 않다면 Wan 3.0 표준판(wan3.0-video)은 720P 초당 단 $0.08이며 참조 영상도 전달할 수 있습니다. 전체 가격은 Wan 3.0 Prime API 가격을 참고하세요.

출시 전 주의사항

• 폴링 대신 콜백 사용: 요청 최상위(input과 같은 레벨)에 "callback": {"url": "https://你的域名/hiapi/callback"}를 추가하고, taskId로 중복을 제거하세요.
• 즉시 전송·보관: output[0].url은 임시 링크입니다.
• 재시도 시 멱등 키 사용: 요청 헤더에 Idempotency-Key를 추가하면 같은 키로 재시도해도 작업은 한 번만 생성됩니다.
• 실패 시 자동 환불: 성공적으로 생성된 영상에 대해서만 과금됩니다.

자주 묻는 질문

720p를 전달하면 왜 오류가 나나요?

해상도는 대문자로 써야 합니다. 소문자로 전달하면 400이 반환됩니다: resolution: value must be one of '480P', '720P', '1080P'.

참조 영상을 전달할 수 있나요?

Prime은 불가능하며 reference_video_urls 파라미터를 받지 않습니다. 참조 영상이 필요하면 Wan 3.0 표준판 wan3.0-video로 바꾸세요.

소리를 끌 수 있나요?

네, audio: false로 가능합니다. 기본은 켜짐이며 가격은 동일합니다.

Prime과 Wan 3.0 표준판의 차이는 무엇인가요?

파라미터와 출력 사양은 같으며 Prime은 고속 라인입니다. 표준판에도 480P 등급($0.04/초)이 있지만 720P와 1080P는 초당 두 배 이상 비싸고, 참조 영상도 받지 않습니다.

더 많은 프롬프트 작성법은 Wan 3.0 Prime 프롬프트 사례를, 이전 세대와의 비교는 Wan 3.0과 Wan 2.7 선택 방법을 참고하세요. 바로 모델 페이지에서 비 오는 밤 골목 영상 생성하기도 가능합니다.