튜토리얼
HiAPI API로 wan2.7-video 텍스트→비디오 호출하기: curl과 Python
이 페이지에서
이 튜토리얼에서 만들 것
이 가이드를 마치면 HiAPI API를 통해 wan2.7-video/text-to-video에 텍스트→비디오 작업을 제출하는 작지만 동작하는 파이프라인을 갖게 됩니다. 먼저 curl로 한 번, 그다음 Python으로 한 번 구현한 뒤 비디오 생성이 완료될 때까지 기다립니다.
두 호출은 의도적으로 동등하게 유지됩니다. curl 버전은 참조 구현으로, 터미널에 붙여 넣어 자격 증명과 요청 본문이 올바른지 확인할 수 있습니다. Python 버전은 동일한 요청을 함수로 감싸 스크립트나 서비스에 넣기 쉽게 만들고, 폴링, 오류 처리, 합리적인 기본값을 포함합니다.
비디오 생성은 채팅 완성보다 훨씬 느리기 때문에 전체 흐름은 비동기입니다. 작업을 제출하고 식별자를 받은 다음, 작업이 종료 상태를 보고할 때까지 폴링합니다. 아래 내용은 모두 이 생명주기를 중심으로 구성되므로, 나중에 이미지→비디오로 바꾸거나 같은 엔드포인트 계열의 다른 비디오 모델을 사용해도 전체 구조는 그대로 적용됩니다.
첫 요청을 보내기 전에
첫 호출이 성공하려면 먼저 세 가지 조건을 충족해야 합니다.
자격 증명
HiAPI API 키가 필요하며, Authorization 요청 헤더에 bearer 토큰 형태로 전송합니다. 소스 코드에 쓰지 말고 환경 변수에 두세요:
export HIAPI_API_KEY="your-key-here"
알려진 모델 식별자
모델 식별자는 정확한 문자열입니다. 이 튜토리얼에서 값은 wan2.7-video/text-to-video이며, 작업 접미사를 포함합니다. wan2.7-video나 wan2.7/text-to-video 같은 유사한 표기는 거부되므로, 기억에 의존해 직접 쓰지 말고 모델 목록에서 식별자를 복사하세요.
평가할 수 있는 프롬프트
비디오 생성을 맹목적으로 반복하는 것은 비용이 큽니다. 피사체, 동작, 카메라 동작, 조명, 스타일을 구체적으로 담은 프롬프트를 미리 작성해 두면, 결과가 돌아왔을 때 조정해야 할 것이 설정인지 문구인지 판단할 수 있습니다.
또한 HTTP 클라이언트와 JSON을 읽는 방법이 필요합니다. 셸 쪽에서는 curl과 jq, 스크립트 쪽에서는 Python과 requests를 사용합니다.
요청 본문 구조 분석
텍스트→비디오 요청은 JSON 객체 하나이며, 필드는 세 그룹으로 나눌 수 있습니다.
식별
model— 정확한 모델 식별자, 즉wan2.7-video/text-to-video.
콘텐츠
prompt— 원하는 비디오를 설명하는 텍스트. 가장 핵심적인 필드이므로 형용사를 나열하기보다 움직임, 구도, 스타일을 구체적으로 설명하세요.negative_prompt— 선택 사항. 나타나서는 안 되는 내용을 설명합니다. 흔한 결함을 억제하는 데 유용하지만 잘 작성된 프롬프트를 대체하지는 못합니다.
생성 설정
duration— 출력 클립의 길이.resolution— 출력의 크기/해상도 등급.seed— 선택 사항. 고정된 출발점에서 두 프롬프트나 두 설정 변경을 비교하고 싶을 때 고정하세요.
최소 요청 본문에는 model과 prompt만 필요하며, 플랫폼이 나머지 필드에 기본값을 적용합니다. 하지만 기본값은 당신이 내린 선택이 아닙니다. 프로덕션 환경에서 명시적으로 설정해야 하는 이유는 아래 길이와 해상도 섹션을 참고하세요.
요청 본문은 평평하고 얕게 유지하세요. 실제로 하위 객체에 속하는 필드에만 중첩하면 요청을 더 읽기 쉽게 만들고 schema 오류를 더 쉽게 발견할 수 있습니다.
curl로 작업 제출하기
다음은 완전한 제출 예제입니다. 이 엔드포인트는 JSON을 받고 비디오 자체가 아니라 작업 핸들을 반환합니다.
curl -X POST "$HIAPI_BASE_URL/v1/video/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "wan2.7-video/text-to-video",
"prompt": "밤비에 젖은 네온 골목을 천천히 밀고 들어가는 추적 샷, 바닥에 반사되는 물웅덩이, 얕은 심도, 영화 같은 색보정",
"duration": 5,
"resolution": "720p"
}'
제출에 성공하면 작업 또는 잡 식별자와 상태를 담은 객체가 반환됩니다. 구조는 대략 다음과 같습니다:
{
"id": "job_abc123",
"status": "queued",
"model": "wan2.7-video/text-to-video"
}
두 가지에 주목하세요. 첫째, status가 succeeded가 아닙니다. 이 시점에는 아직 아무것도 렌더링되지 않았습니다. 둘째, 응답에 비디오 URL이 없습니다. 해당 URL은 작업이 종료 상태에 도달한 뒤에만 나타납니다.
폴링 단계에서 사용할 수 있도록 식별자를 셸 세션에 남기려면:
JOB_ID=$(curl -s -X POST "$HIAPI_BASE_URL/v1/video/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @payload.json | jq -r '.id')
echo "$JOB_ID"
요청 본문을 payload.json으로 옮기면 명령을 짧게 유지하고 여러 실행 사이에 프롬프트를 조정하기 쉬워집니다.
Python으로 작업 제출하기
Python 버전은 동일한 요청을 더 편하게 사용하는 것입니다. curl에서 요청 헤더나 JSON 키였던 것이 여기서는 키워드 인자가 됩니다.
import os
import time
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"model": "wan2.7-video/text-to-video",
"prompt": (
"밤비에 젖은 네온 골목을 천천히 밀고 들어가는 추적 샷, "
"바닥에 반사되는 물웅덩이, 얕은 심도, 영화 같은 색보정"
),
"duration": 5,
"resolution": "720p",
}
resp = requests.post(
f"{BASE_URL}/v1/video/generations",
headers=HEADERS,
json=payload,
timeout=30,
)
resp.raise_for_status()
job = resp.json()
print(job["id"], job["status"])
셸 버전과의 대응 관계는 일대일입니다:
-H "Authorization: ..."→HEADERS딕셔너리.-d '<json>'→json=payload. 문자열이 아닌 딕셔너리를 전달하면requests가 직렬화를 담당하므로 잘못된 형식의 JSON을 보낼 일이 없습니다.jq로 추출한.id→job["id"].
지금부터 들여야 할 Python 특유의 습관 두 가지가 있습니다. 제출 호출에는 항상 timeout을 설정하세요. 이 요청은 작고 빠르게 반환되어야 하므로 오래 걸린다면 렌더링이 아니라 연결에 문제가 있다는 뜻입니다. 그리고 응답 본문을 읽기 전에 raise_for_status()를 호출하세요. 그러면 HTTP 계층 실패가 명확한 traceback으로 나타나고, job["id"]에서 혼란스러운 KeyError가 발생하지 않습니다.
비동기 작업과 폴링 처리
폴링은 대부분의 통합이 견고해지거나 불안정해지는 지점입니다. 작업에는 생명주기가 있습니다. 보통 대기, 처리 중, 그리고 성공 또는 실패의 종료 상태이며, 루프는 이 세 가지를 모두 처리해야 합니다.
def wait_for_job(job_id, interval=5, max_attempts=120):
url = f"{BASE_URL}/v1/video/generations/{job_id}"
for attempt in range(max_attempts):
r = requests.get(url, headers=HEADERS, timeout=30)
r.raise_for_status()
data = r.json()
status = data.get("status")
if status == "succeeded":
return data
if status in ("failed", "cancelled"):
raise RuntimeError(f"Job {job_id} ended as {status}: {data.get('error')}")
time.sleep(interval)
raise TimeoutError(f"Job {job_id} still not finished after {max_attempts} polls")
이 루프에는 겉보기보다 중요한 설계 포인트가 몇 가지 있습니다:
종료 상태를 명시적으로 확인하세요. succeeded가 아닌 모든 상태를 "계속 대기"로 취급하면 실패한 작업이 조용히 폴링 예산을 모두 소진하게 됩니다. 실패 상태를 매칭하고 예외를 던져야 합니다.
폴링 간격을 의식적으로 선택하세요. 비디오 렌더링은 수십 초에서 수 분이 걸립니다. 200밀리초마다 폴링하면 부하만 늘고 새로운 정보는 얻지 못합니다. 약 5초에서 시작하고, 작업이 자주 오래 걸린다면 시도 횟수를 늘리기보다 간격을 늘리세요.
항상 루프에 상한을 두세요. max_attempts 상한은 무한 대기를 진단 가능한 TimeoutError로 바꿔 줍니다. 작업 ID도 함께 기록하세요. 문제를 조사할 때 필요한 값입니다.
속도 제한을 준수하세요. 배치로 제출할 때 모든 폴링 요청을 동시에 보내지 마세요. 고정 간격으로 실행되는 공유 폴러나 간단한 클라이언트 측 스로틀링을 사용하면 제한 안에 머물 수 있습니다.
성공하면 응답에 완료된 자산의 위치가 포함됩니다. 작업 기록을 영구 저장소로 여기지 말고 즉시 다운로드하세요.
길이와 해상도 선택하기
이 두 설정은 다른 어떤 파라미터보다 출력에 큰 영향을 주며, 둘 다 작업 실행 시간과 비용에 영향을 줍니다. 과금用量은 출력 초 단위로 계산되고, 해상도는 초당 작업량을 결정합니다. 따라서 둘 다 기본값으로 남겨 둘 필드가 아니라 구체적인 사용 사례에 맞춘 의도적인 선택으로 보세요.
길이
더 긴 클립은 동작이 발전할 공간을 주지만, 매 초의 추가 길이는 더 많은 렌더링과 더 높은 비용을 의미하며, 긴 생성은 일관성 문제가 생기기 쉽습니다. 실용적인 조언:
- 짧게 (몇 초) — 소셜 루프, 제품 키비주얼, B-roll. 반복 비용이 가장 낮고 판단하기 가장 쉽습니다.
- 중간 — 내러티브 비트, 설정 샷.
- 길게 — 이야기가 정말로 필요할 때만 사용하세요. 긴 비디오가 필요하다면 여러 짧은 클립을 생성해 편집으로 조합하는 것을 고려하세요. 보통 한 번의 긴 렌더링보다 저렴하고 더 많은 제어권을 줍니다.
프롬프트를 반복할 때는 모델이 허용하는 가장 짧은 클립을 생성하세요. 그 길이에서 구도와 움직임을 판단하고, 만족하면 길이를 늘리세요.
해상도
더 높은 해상도는 프레임당 더 많은 픽셀, 더 긴 렌더링 시간, 더 높은 비용을 의미합니다. 하지만 작은 화면에서는 생각보다 중요하지 않습니다. 1080p 마스터는 고객에게 전달할 때 적합하고, 720p(또는 그 이하) 초안은 프롬프트가 효과가 있는지 판단할 때 적합합니다.
효율적인 패턴은 2단계 워크플로입니다. 낮은 해상도에서 프롬프트와 길이를 확정한 다음, 최종 작업을 전달 해상도로 다시 실행하세요. 최고 설정에서 반복하지 마세요. 대부분의 예산을 버려질 소재에 쓰게 됩니다.
흔한 오류 해결하기
대부분의 실패는 모델 자체가 아니라 요청을 구성하는 방식에서 비롯됩니다. 모델 능력에 대해 결론을 내리기 전에 다음 범주를 순서대로 점검하세요.
401 / 403 — 자격 증명 문제
키가 프로세스에서 실제로 볼 수 있는 환경에 설정되어 있는지(한 셸에서 export한 키는 systemd 서비스에서 보이지 않습니다), 요청 헤더가 Authorization: Bearer <key>인지, 변수에 후행 공백이 없는지 확인하세요. 디버깅할 때는 키의 처음 몇 글자만 출력하고 전체 키는 절대 출력하지 마세요.
404 — 경로 또는 모델 오류
엔드포인트 경로와 모델 식별자는 별개이며 둘 다 정확해야 합니다. POST하는 URL을 확인하고, wan2.7-video/text-to-video가 모델 목록에서 문자 단위로 복사되었는지 확인하세요. 유효한 키에 잘못된 모델 문자열을 쓰면 여전히 not-found류 오류가 반환됩니다.
400 — 요청 본문 형식 오류
가장 흔한 범주입니다. 흔한 원인으로는 duration 같은 숫자 필드를 문자열 "5"로 보내는 경우, 프롬프트를 문자열이 아닌 리스트로 보내는 경우, 요청 본문이 실수로 이중 인코딩된 경우가 있습니다. 가장 빠른 분류 방법은 똑같은 curl 명령을 다시 보내는 것입니다. 셸 호출은 성공하는데 Python 호출이 실패한다면 문제는 요청 자체가 아니라 스크립트가 딕셔너리를 구성하는 방식에 있습니다.
422 / 검증 오류
문법은 유효하지만 의미에 문제가 있습니다. 지원 범위를 벗어난 길이, 알 수 없는 해상도 등급, 또는 필수 필드 누락입니다. 오류 메시지를 읽으세요. 보통 문제가 된 필드를 지목합니다.
제출 후 작업 실패
제출 호출은 성공했지만 렌더링이 성공하지 못했습니다. 콘텐츠 정책 거부일 수도 있고 일시적 렌더링 실패일 수도 있습니다. 작업 ID와 오류 페이로드를 기록하고, 일시적 문제라면 동일한 페이로드를 다시 제출하는 것이 합리적인 첫 단계입니다. 같은 프롬프트에서 반복된다면 같은 요청을 계속 재시도하지 말고 프롬프트 문구나 생성 설정을 바꾸세요.
폴링이 끝나지 않음
작업이 비슷한 작업보다 훨씬 오래 처리 중 상태에 머문다면 폴링을 중단하고 작업 ID를 기록한 뒤 실패 작업으로 취급하세요. 롱테일 상황은 충분히 드물기 때문에 명확한 오류 메시지를 가진 제한된 타임아웃이 열린 루프보다 낫습니다.
새로운 문제를 만날 때마다 curl 참조 구현부터 시작하세요. 그것이 당신의 코드를 문제에서 제외시켜, 문제가 요청에 있는지 클라이언트에 있는지 분리해 줍니다.