wan2.7-video/text-to-video@pro로 숏폼 영상 만들기: 엔드투엔드 hiapi API 워크플로

숏폼 영상의 성패는 반복 속도에 달려 있습니다. 많은 후보 클립이 필요하고, 세로 형식이어야 하며, 소리가 있어야 하고, 빨라야 합니다. 이 가이드는 바로 그 점에 초점을 맞추며, hiapi의 wan2.7-video/text-to-video@pro—알리바바 통이완샹 2.7 텍스트 투 비디오 모델로, 최대 1080P 출력, 네이티브 오디오, 클립 최대 15초를 지원합니다—를 사용합니다. 아래의 모든 요청 구조, 파라미터 경계, 오류 메시지는 이 글을 작성할 당시 실제 운영 API를 대상으로 실행 검증되었으며, 본문에 삽입된 두 개의 데모 클립도 제시된 코드로 그대로 생성된 것입니다.

모델이 제공하는 것

wan2.7-video/text-to-video@pro는 hiapi의 통합 비동기 작업 엔드포인트(/v1/tasks)를 통해 서비스됩니다. 온라인 스키마와 대조해 검증된 주요 특징은 다음과 같습니다:

• 출력: H.264 MP4, 최대 1080P, 네이티브 AAC 오디오 트랙 포함—모델이 프롬프트에 따라 환경음과 효과음을 생성하므로 별도의 오디오 단계가 필요 없습니다.
• 길이: 클립당 2–15초(정수 초).
• 화면 비율: 16:9, 9:16, 1:1, 4:3, 3:4—진정한 세로 9:16으로 Shorts/Reels/TikTok류 포맷에 맞으며 자를 필요가 없습니다.
• 과금: 출력 영상 초 단위로 과금되며, 작성 시점 기준 초당 $0.167부터 시작합니다—5초 1080P 클립은 약 $0.84입니다. 대량 생성 전에 반드시 가격 페이지에서 확인하세요.

영상에는 동기 모드가 없습니다. 작업을 생성하고, 완료될 때까지 폴링한 다음, 결과를 다운로드해야 합니다.

최소 실행 예제(curl)

작업 생성:

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-video/text-to-video@pro",
    "input": {
      "prompt": "매크로 스튜디오 촬영: 한 방울의 사파이어 블루 잉크가 맑은 물에 떨어져 슬로모션으로 피어나고, 잉크 실이 구름 모양으로 펼쳐지며, 배경은 밝은 화이트 심리스 배경, 선명한 하이키 조명, 부드러운 환경 웅웅거림",
      "ratio": "16:9",
      "resolution": "1080P",
      "duration": 4
    }
  }'

응답:

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

결과 폴링:

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01KWGGS29FDZ8NRJW49YRQZ65R" \
  -H "Authorization: Bearer sk-YOUR_KEY"

렌더링 중에는 data.status가 handling이며, 완료되면 success로 바뀌고 data.output[0].url에 MP4가 포함됩니다. 이 요청은 다음 클립을 그대로 생성했습니다:

⚠️ 출력 URL은 expireAt 타임스탬프가 있는 임시 링크입니다. 작업이 성공하면 즉시 파일을 자신의 스토리지로 다운로드하세요—직접 핫링크하거나 데이터베이스에 저장하지 마세요.

전체 입력 스키마(온라인 API와 대조 검증 완료)

API는 input을 엄격하게 검증하고 알 수 없는 필드를 거부합니다. 아래는 전체 허용 필드 목록이며, 어디서 복사한 것이 아니라 엔드포인트를 직접 탐침하여 얻은 것입니다:

필드	유형	제약	필수 여부
prompt	string	장면 설명. 생성되는 오디오도 함께 구동	✅
ratio	string	16:9, 9:16, 1:1, 4:3, 3:4 중 하나	선택
resolution	string	720P 또는 1080P	선택
duration	integer	2–15(초)	선택
negative_prompt	string	억제할 내용(예: 워터마크, 텍스트 오버레이)	선택
seed	integer	재시도 간 재현 가능	선택
watermark	boolean	서비스 제공자 워터마크 전환	선택

400 오류를 피하는 데 도움이 되는 두 가지 함정:

• 필드 이름은 ratio이며, aspect_ratio가 아닙니다—hiapi의 이미지 모델은 aspect_ratio를 사용하지만, 이 비디오 모델은 사용하지 않습니다. aspect_ratio를 보내면 additional properties 'aspect_ratio' not allowed가 반환됩니다.
• duration은 서버에서 검증됩니다: duration: minimum: got 1, want 2와 maximum: got 999, want 15는 2–15 범위를 벗어났을 때 받는 정확한 오류입니다.

엔드투엔드 Python: 프롬프트 입력, 게시 가능한 MP4 출력

이것이 전체 워크플로입니다—생성, 폴링, 다운로드—SDK 없이 requests만 사용합니다:

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY", "Content-Type": "application/json"}

def make_short(prompt: str, out_path: str, duration: int = 5,
               ratio: str = "9:16", seed: int | None = None) -> str:
    payload = {
        "model": "wan2.7-video/text-to-video@pro",
        "input": {
            "prompt": prompt,
            "ratio": ratio,               # 9:16 = 세로 숏폼 영상
            "resolution": "1080P",
            "duration": duration,          # 2..15초
            "negative_prompt": "텍스트 오버레이, 워터마크, 왜곡된 손",
        },
    }
    if seed is not None:
        payload["input"]["seed"] = seed

    task_id = requests.post(API, headers=HEADERS, json=payload).json()["data"]["taskId"]

    while True:
        task = requests.get(f"{API}/{task_id}", headers=HEADERS).json()["data"]
        if task["status"] == "success":
            break
        if task["status"] == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(10)

    video_url = task["output"][0]["url"]   # 임시 링크—즉시 다운로드하세요
    with open(out_path, "wb") as f:
        f.write(requests.get(video_url, timeout=120).content)
    return out_path

make_short(
    "골든아워 핸드헬드 세로형 야시장 장면: 한 길거리 음식 노점상이 "
    "불꽃이 치솟는 웍에서 지글지글한 면을 볶고, 김과 주황색 불똥이 "
    "카메라 쪽으로 소용돌이치며 날아오고, 네온 간판이 흐릿한 배경에서 "
    "부드러운 핑크와 시안 빛을 발하며, 얕은 "
    "심도, 역동적인 핸드헬드 다큐멘터리 느낌, 지글지글 소리와 타닥타닥 소리 동반",
    "night-market.mp4",
    duration=5,
    seed=20260702,
)

다음은 해당 호출이 실제로 생성한 클립입니다—세로 1080×1920, 5초, 지글지글 소리는 프롬프트 텍스트로부터 생성됩니다:

제 실행에서는 4초 16:9 클립이 약 3분 만에 완료되었고, 5초 9:16 클립은 조금 더 오래 걸렸습니다—클립당 몇 분을 예상하고 약 10초마다 폴링하되, 엔드포인트를 과도하게 호출하지 마세요.

숏폼 프롬프트 요령: 움직임과 오디오 모두 프롬프트가 결정

스키마에는 카메라 제어나 움직임 파라미터가 없습니다—움직임, 리듬, 소리에 관한 모든 것은 프롬프트 언어로 유도됩니다. 제 테스트에서 효과가 있었던 방법은 다음과 같습니다:

• 카메라 동작을 명시적으로 지정: "handheld"(핸드헬드), "slow push-in"(천천히 다가가기), "macro"(매크로), "shallow depth of field"(얕은 심도)처럼. 야시장 클립의 다큐멘터리식 흔들림은 전적으로 "handheld"라는 단어에서 나왔습니다.
• 원하는 오디오를 설명: 모델은 프롬프트에 따라 소리를 생성합니다. "sizzling and crackling sounds"(지글지글 소리와 타닥타닥 소리)와 "gentle ambient hum"(부드러운 환경 웅웅거림)이 모두 출력 오디오 트랙에 나타났습니다.
• 훅을 앞에 배치: 숏폼에서는 첫 1초가 모든 것을 결정합니다. 가장 역동적인 요소(불꽃 웍질, 잉크 방울의 물방울)를 프롬프트 설명의 맨 앞에 두세요.
• negative_prompt를 방어적으로 사용: "text overlay, watermark, distorted hands"(텍스트 오버레이, 워터마크, 왜곡된 손)는 메인 프롬프트에 영향을 주지 않으면서 가장 흔한 결함을 정리합니다.
• 반복 시 seed 고정: seed를 고정하고 한 번에 프롬프트 구문 하나만 바꾸어, 그 구문이 실제로 어떤 역할을 하는지 관찰하세요.

첫 프레임 제어가 필요하신가요? 이미지 투 비디오 변형을 사용하세요

워크플로가 디자인된 키프레임—제품 이미지, 브랜드 스타일의 첫 프레임—에서 시작한다면, 텍스트 투 비디오는 이미지 입력을 받지 않습니다. 자매 모델 wan2.7-video/image-to-video@pro는 받습니다: {"url": "...", "type": "image"} 객체로 구성된 media 배열과 동일한 prompt / resolution / duration 필드를 받아, 프레임을 처음부터 생성하는 대신 제공한 프레임을 애니메이션화합니다. 동일한 작업 기반 흐름, 동일한 초 단위 과금입니다. 실용적인 파이프라인 하나: 이미지 모델로 정지 프레임을 생성하고, 검토를 통과한 프레임만 애니메이션화하세요—이렇게 하면 이미 승인된 프레임에만 영상 생성 비용을 지출하게 됩니다.

자주 발생하는 오류와 그 실제 의미

• invalid input: prompt: missing required field "prompt"—prompt는 유일한 필수 필드입니다.
• invalid input: ratio: value must be one of '16:9', '9:16', '1:1', '4:3', '3:4'—모델이 지원하지 않는 화면 비율을 전달했거나(또는 철자를 틀렸습니다).
• invalid input: <root>: additional properties '...' not allowed—알 수 없는 필드입니다. 스키마가 엄격하니 위 표를 확인하세요.
• status: "fail"과 함께 TASK_FAILED—작업이 생성 후 실패했습니다. 새 작업을 생성하세요(재현성을 유지하려면 seed를 재사용).
• 다운로드한 파일이 작거나 재생되지 않음—만료된 출력 URL을 가져왔을 가능성이 큽니다. expireAt을 다시 확인하고 success 직후에 다운로드하세요.

요약

POST 한 번, 폴링 루프 하나, 다운로드 한 번—이것이 텍스트 프롬프트에서 게시 가능한 사운드 포함 세로형 MP4까지의 전부입니다. 숏폼 파이프라인을 구축한다면 콘솔에서 API 키를 받고, 위의 Python 함수로 시작하며, 모델 카탈로그의 나머지도 살펴보세요—동일한 /v1/tasks 패턴(예: seedance-2.0-fast 가이드에 제시된)이 플랫폼의 모든 비디오 모델에 적용되므로, 이후 모델 교체는 한 줄만 바꾸면 됩니다.