완샹 Wan 2.7 비디오 API 사용법? 텍스트→비디오, 이미지→비디오 중국어 튜토리얼

TL;DR

• 완샹 Wan 2.7은 알리의 비디오 모델로, HiAPI에서 텍스트→비디오 wan2.7-video/text-to-video와 이미지→비디오 wan2.7-video/image-to-video를 제공하며, 한 편당 2–15초입니다.모델 페이지 열기만 하면 온라인에서 생성할 수 있고, 신규 사용자 가입 시 200 크레딧을 드립니다.
• 초 단위 과금이며 텍스트→비디오와 이미지→비디오 가격이 같습니다: 720P 초당 $0.10, 1080P 초당 $0.167. 5초 720P는 $0.50입니다.
• 흔히 빠지기 쉬운 함정 두 가지: 해상도는 대문자 720P / 1080P로 써야 하며 기본값은 1080P입니다; 텍스트→비디오의 화면 비율 파라미터 이름은 aspect_ratio가 아니라 ratio입니다.

먼저 결과물 보기

텍스트→비디오, 모델 페이지 예시, 중국어 프롬프트:

一位穿着白色毛衣的年轻女子坐在咖啡馆窗边，窗外是雨天的街道，她轻轻端起咖啡杯，目光望向窗外，暖黄色灯光映照在她的脸上，雨滴顺着玻璃缓缓流下，电影级浅景深，35mm胶片质感，温暖色调，慢镜头特写

이 프롬프트로 생성하기 →（1080P, 16:9）

wan2.7-video/text-to-video 모델 페이지 예시, 1080P, 약 8초, 현재 가격 기준 약 $1.336.

이미지→비디오, 클레이 스타일 농장 이미지를 첫 프레임으로 사용:

黏土动画风格，欢乐农场场景缓缓活起来。奶牛妈妈慢慢咀嚼嘴里的青草，小牛好奇地歪头张望。身后的母鸡们低头啄食地上的谷粒，小狗摇着尾巴朝镜头方向小跑几步。泥坑里的小猪满足地打了个滚，溅起小小的泥花。远处红色谷仓的风车缓缓转动，绿色山丘上白云悠悠飘过。地面上的小花随微风轻轻摇摆，整个画面充满温暖的午后阳光，定格动画质感，童趣十足。

이 프롬프트로 생성하기 →（첫 프레임 이미지 업로드）

wan2.7-video/image-to-video 모델 페이지 예시, 1080P, 약 8초, 현재 가격 기준 약 $1.336.

이미지→비디오의 프롬프트는 「누가 무엇을 하는지」를 하나씩 적습니다: 젖소가 풀을 씹고, 암탉이 쪼아 먹고, 강아지가 종종걸음치고, 아기 돼지가 뒹굽니다. 화면 속 각 캐릭터에 작은 동작을 하나씩 주면 그림 전체가 살아납니다.

두 가지 시작 방법

온라인 체험(코딩 없이)

1. Wan 2.7 텍스트→비디오 모델 페이지를 열고 회원가입 또는 로그인합니다.
2. 프롬프트를 붙여넣고 길이, 해상도, 화면 비율을 선택합니다.
3. 생성을 누르고 결과가 나오면 바로 다운로드합니다.

API 호출

1. 콘솔에서 API Key를 생성합니다.
2. POST https://api.hiapi.ai/v1/tasks로 작업을 제출하면 taskId가 반환됩니다.
3. GET /v1/tasks/{taskId}로 상태를 조회하고, status가 success이면 output[0].url에서 비디오를 다운로드합니다.

curl: 첫 번째 비디오

5초 720P, $0.50:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-video/text-to-video",
    "input": {
      "prompt": "一只橘猫趴在洒满阳光的窗台上打哈欠，尾巴轻轻摆动，暖色调，浅景深",
      "resolution": "720P",
      "ratio": "16:9",
      "duration": 5
    }
  }'

반환값:

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

결과 조회:

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

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

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

KEY = os.environ["HIAPI_KEY"]
H = {"Authorization": f"Bearer {KEY}"}

def generate(model, timeout_s=900, **params):
    body = {"model": model, "input": params}
    # 重试提交同一个任务时带同一个 Idempotency-Key，避免重复扣费
    headers = {**H, "Idempotency-Key": str(uuid.uuid4())}
    r = requests.post("https://api.hiapi.ai/v1/tasks", json=body, headers=headers, timeout=30)
    r.raise_for_status()
    res = r.json()
    if res.get("code") != 200:
        raise RuntimeError(res)
    task_id = res["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"https://api.hiapi.ai/v1/tasks/{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)

url = generate(
    "wan2.7-video/text-to-video",
    prompt="一只橘猫趴在洒满阳光的窗台上打哈欠，尾巴轻轻摆动，暖色调，浅景深",
    resolution="720P", ratio="9:16", duration=5,
)
with open("clip.mp4", "wb") as f:
    f.write(requests.get(url).content)

이미지→비디오: media로 소재 전달

이미지→비디오는 image_url이 아니라 media 배열을 사용하며, 각 항목에 유형과 주소를 명시합니다. 1–3개:

{
  "model": "wan2.7-video/image-to-video",
  "input": {
    "prompt": "镜头缓慢推进，花瓣被风吹起，人物转头微笑",
    "media": [
      {"type": "first_frame", "url": "https://your-cdn.example.com/start.jpg"},
      {"type": "last_frame", "url": "https://your-cdn.example.com/end.jpg"}
    ],
    "resolution": "720P",
    "duration": 5
  }
}

type은 네 가지입니다:

type	역할
first_frame	첫 프레임 이미지
last_frame	마지막 프레임 이미지, 첫 프레임과 함께 전환에 사용
driving_audio	드라이빙 오디오, 소리에 맞춰 화면이 움직이게 함
first_clip	첫 구간 비디오, 이것에 이어서 생성

파라미터 한눈에 보기

파라미터	값	설명
prompt	문자열, 필수	최대 5000자, 중국어와 영어 모두 가능
negative_prompt	문자열	원하지 않는 내용, 최대 500자
resolution	720P / 1080P, 기본값 1080P	대문자, 가격을 직접 결정
ratio	16:9 9:16 1:1 4:3 3:4, 기본값 16:9	텍스트→비디오 전용
duration	2–15의 정수, 기본값 5	단위 초
audio_url	wav/mp3, 2–30초, 최대 15 MB	텍스트→비디오 전용, 선택
prompt_extend	기본값 true	프롬프트 자동 최적화; 원문 그대로 생성하려면 false로 설정
seed	0–2147483647	시드 고정으로 재현 용이
watermark	기본값 false	AI 생성 워터마크 추가 여부

비용 계산해 보기

길이	720P($0.10/초)	1080P($0.167/초)
2초	$0.20	$0.334
5초	$0.50	$0.835
10초	$1.00	$1.67
15초	$1.50	$2.505

$10으로 720P에서 100초를 생성할 수 있습니다. resolution 기본값은 1080P이므로 프롬프트를 조정할 때는 720P를 쓰면 40%를 절약할 수 있습니다.

출시 전 유의 사항

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

자주 묻는 질문

해상도를 소문자 720p로 쓸 수 있나요?

안 됩니다. 소문자는 바로 400을 반환합니다: resolution: value must be one of '720P', '1080P'.

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

Wan 2.7 텍스트→비디오의 화면 비율 파라미터 이름은 ratio입니다. aspect_ratio를 전달하면 400을 반환합니다: additional properties 'aspect_ratio' not allowed.

이미지→비디오의 화면 비율은 어떻게 설정하나요?

이미지→비디오에는 화면 비율 파라미터가 없으며 첫 프레임을 따릅니다.

15초 비디오를 생성할 수 있나요?

가능합니다. duration 범위는 2–15초입니다.

Wan 2.7과 Wan 3.0 중 무엇을 선택해야 하나요?

HiAPI의 Wan 3.0은 참조→비디오로, 참조 이미지를 사용해 인물과 상품을 고정합니다; 텍스트→비디오나 이미지→비디오만 필요하다면 Wan 2.7을 사용하세요.

더 많은 작성법은 Wan 2.7 텍스트→비디오 프롬프트 사례(영문)를 참고하세요. 먼저 한 편 시험해 보려면 모델 페이지에서 생성하기를 이용하세요.