블로그

튜토리얼

HiAPI API로 pixverse-v6-max/text-to-video를 사용하는 방법: curl, Python 및 실행 가능한 요청 예제

Nov 13, 2026
에스프레소, 오트, 브라스 색상이 엮인 두툼한 직조 바구니 패턴이 직기 같은 격자를 이루는 플랫 커버 아트.
이 페이지에서

이 엔드포인트가 하는 일과 언제 사용하는가

pixverse-v6-max/text-to-video는 HiAPI의 텍스트-투-비디오 엔드포인트입니다. 원하는 장면을 설명하는 텍스트 프롬프트를 보내면 엔드포인트가 렌더링된 비디오를 반환합니다. 비디오 생성에는 시간이 걸리므로 이 엔드포인트는 비동기입니다. 첫 요청은 비디오를 직접 반환하지 않고, 진행 상황을 조회하고 최종 결과를 가져올 때 쓰는 작업 식별자를 반환합니다.

이 "요청—확인—폴링" 형태가 이 튜토리얼 전체의 핵심 멘탈 모델입니다. 내부 흐름은 항상 동일합니다.

  1. 프롬프트와 파라미터로 생성 작업을 제출합니다.
  2. 즉시 작업 식별자를 받습니다.
  3. 작업이 완료(또는 실패)를 보고할 때까지 해당 작업을 폴링합니다.
  4. 결과 비디오의 URL을 다운로드하거나 삽입합니다.

이 엔드포인트가 적합한 경우

설명만 있고 원본 소재가 없을 때 pixverse-v6-max/text-to-video를 선택하세요. 예를 들어 텍스트 브리핑으로 제품 티저를 만들거나, 앱용 배경 클립을 생성하거나, 스토리보드 미리보기를 제작할 때입니다. 이미 이미지가 있고 이를 움직이게 하고 싶다면 이미지-투-비디오 워크플로에 해당하며 이 엔드포인트가 아닙니다. 모델과 대화하면서 프롬프트를 반복 개선하고 싶다면 다른 상호작용 방식에 해당합니다. 이 엔드포인트는 텍스트에서 비디오로 가는 직접적이고 단일 생성 경로입니다.

생성이 비동기이므로 큐 기반 아키텍처에도 적합합니다. 웹 백엔드가 사용자 요청을 받아 작업을 제출하고, 워커 프로세스가 나중에 폴링하여 결과를 전달합니다. 전체 호출 과정에서 전체 렌더링이 끝날 때까지 블로킹되는 구간은 없습니다.

시작하기 전에: 인증과 요청 기본 사항

코드를 작성하기 전에 세 가지를 확인하세요.

1. API 키

모든 HiAPI 요청은 API 키로 인증해야 합니다. 비밀번호처럼 취급하세요. 소스 저장소에 커밋하지 말고 환경 변수에서 불러오며, 유출되면 즉시 교체하세요. 아래 예제는 HIAPI_API_KEY에서 읽으므로 먼저 셸에서 내보내세요.

export HIAPI_API_KEY="your_key_here"

2. 올바른 기본 URL

모든 요청은 HiAPI API 기본 URL에 엔드포인트 경로를 붙여 보냅니다. 블로그 글에서 호스트명을 하드코딩하지 말고 HiAPI 계정에 기록된 base URL을 사용하세요. 확실하지 않다면 대시보드의 API 참조 문서를 확인하세요. 아래 예제는 해당 값의 자리표시자로 $HIAPI_BASE_URL을 사용합니다.

3. JSON 규약

제출과 상태 조회 모두 HTTPS 기반 JSON입니다.

  • 본문이 있는 모든 요청에 Content-Type: application/json을 보냅니다.
  • 모든 요청(상태 조회 포함)에 Authorization: Bearer $HIAPI_API_KEY를 보냅니다.
  • 오류 시에도 JSON을 기대하세요. HTTP 상태 코드만 보지 말고 오류 응답 본문도 읽으세요.

빠른 정상 동작 확인

사용 가능한 가벼운 엔드포인트(예: models 또는 account 라우트)가 있다면 비디오 엔드포인트를 건드리기 전에 한 번 호출하세요. 그곳에서 200이 반환되면 키, base URL, 요청 헤더 형식이 모두 올바르다는 뜻이므로 이후 디버깅에서 세 가지 변수를 제거할 수 있습니다.

실행 가능한 curl 요청

다음은 전체 제출 호출입니다. 엔드포인트 경로는 pixverse-v6-max/text-to-video이며, 요청 본문에 프롬프트와 생성 파라미터를 담습니다.

curl -sS -X POST "$HIAPI_BASE_URL/pixverse-v6-max/text-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "밤, 비에 젖은 네온 골목, 느린 돌리인 샷, 영화적 분위기",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

필드별 설명

  • prompt —— 텍스트 설명. 피사체, 움직임, 카메라 이동, 분위기를 명확히 하세요. 출력 품질에 가장 큰 영향을 주는 요소입니다.
  • duration —— 요청할 클립 길이. 아래 길이와 화면 비율 섹션을 참고하세요.
  • aspect_ratio —— 출력 화면 비율. 예: 16:9, 9:16, 1:1.

반환되는 것

제출 성공 시 작업 식별자를 포함한 JSON 객체가 반환됩니다. 즉 폴링에 쓰는 핸들입니다. 구체적인 필드명은 API 참조 문서를 따르세요. 이 튜토리얼에서는 task_id라고 부르겠습니다. 이를 저장하세요.

TASK_ID=$(curl -sS -X POST "$HIAPI_BASE_URL/pixverse-v6-max/text-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"밤, 비에 젖은 네온 골목, 느린 돌리인 샷, 영화적 분위기","duration":5,"aspect_ratio":"16:9"}' \
  | python -c 'import sys,json; print(json.load(sys.stdin)["task_id"])')
echo "$TASK_ID"

응답에 없는 것에 주목하세요. 바로 비디오입니다. 생성은 백그라운드에서 실행됩니다. 제출 응답은 결과가 아니라 영수증으로 취급하세요.

동일한 요청의 Python 버전

Python 버전은 curl 호출과 완전히 대응합니다. 간결성을 위해 requests를 사용하지만 httpx나 urllib도 동일하게 동작합니다. 요구 사항은 동일한 요청 헤더와 JSON 본문뿐입니다.

import os
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 = {
    "prompt": "밤, 비에 젖은 네온 골목, 느린 돌리인 샷, 영화적 분위기",
    "duration": 5,
    "aspect_ratio": "16:9",
}

resp = requests.post(
    f"{BASE_URL}/pixverse-v6-max/text-to-video",
    headers=headers,
    json=payload,
    timeout=30,
)

if resp.status_code >= 400:
    # 서버의 오류 응답 본문을 출력하세요. 보통 어떤 필드가 문제인지 알려줍니다.
    raise RuntimeError(f"submit failed {resp.status_code}: {resp.text}")

data = resp.json()
task_id = data["task_id"]
print("submitted:", task_id)

그대로 따를 만한 핵심

  • json=payload는 요청 본문을 자동으로 직렬화하고 콘텐츠 타입을 설정합니다. data=json.dumps(payload)를 대신 쓴다면 명시적인 Content-Type 헤더를 유지해야 합니다.
  • 제출 시 클라이언트 타임아웃을 설정하면 연결이 멈추는 것을 방지합니다. 생성 시간을 제한하는 것은 아닙니다. 생성은 서버에서 일어나므로 폴링이 필요합니다.
  • 파싱 전에 상태 코드를 확인하세요. 4xx 응답 본문은 보통 상태 코드 자체보다 더 많은 정보를 제공합니다. 출력하세요.
  • API 키를 절대 로그에 남기지 마세요. 대신 task_id를 기록하세요. 안전하게 저장할 수 있고 디버깅 핸들이 됩니다.

길이와 화면 비율 파라미터

이 두 필드는 요청이 거부되는 가장 흔한 원인이므로 주의 깊게 다룰 가치가 있습니다.

duration

duration은 요청할 클립 길이를 초 단위로 설정합니다. 요청 가능한 값은 엔드포인트 지원 범위로 제한되며, 범위를 벗어난 값을 보내면 클립이 조용히 잘리는 것이 아니라 보통 파라미터 검증 오류가 발생합니다. API 참조 문서에 기록된 지원 값 중에서 선택하고 정수로 유지하세요. 클립이 길수록 렌더링 시간도 길어지므로 개발 단계에서는 지원되는 가장 짧은 길이를 우선 사용하세요. 검증하는 것은 파이프라인이지 예술 작품이 아닙니다.

aspect_ratio

aspect_ratio는 W:H 형식의 문자열입니다. 비디오가 최종적으로 표시될 위치와 일치시키세요.

  • 16:9 —— 가로형: 웹사이트 히어로 영역, YouTube 스타일 플레이어, 데스크톱 배경.
  • 9:16 —— 세로형: 모바일 숏폼 피드와 스토리.
  • 1:1 —— 정사각형: 그리드 레이아웃과 썸네일.

여기서 잘못된 형태를 선택하면 수정 비용은 낮지만 늦게 발견하면 비용이 큽니다. 다시 렌더링해야 하므로 전체 생성 주기가 한 번 더 소모됩니다. 따라서 제출 전에 대상 표시 환경을 결정하세요.

거부될 때 점검할 것

  • 타입 불일치 —— duration을 숫자가 아닌 문자열("5")로 쓰거나 aspect_ratio를 두 숫자로 쓰는 경우. duration은 수치, aspect ratio는 문자열로 유지하세요.
  • 지원되지 않는 값 —— 길이 또는 비율이 문서화된 범위를 벗어난 경우. 참조 목록과 항목별로 대조하세요.
  • 필드 이름 —— aspectRatio 또는 durationSeconds 같은 오타는 최선의 경우 알 수 없는 필드로 조용히 처리됩니다. 참조 문서에서 필드 이름을 복사하세요.

문제 필드를 빠르게 찾는 방법: 먼저 prompt만으로 다시 제출한 다음 파라미터를 하나씩 다시 추가하세요. 첫 번째 거부가 문제 필드를 알려줄 것입니다.

비디오가 준비될 때까지 비동기 작업 폴링

폴링은 세 가지 규칙을 따르는 루프입니다. 상태 확인, 대기, 종료 상태에서 중지. 여기에 상한을 추가해 멈춘 작업이 무한히 공회전하지 않도록 하세요.

import time
import requests

def wait_for_video(task_id, base_url, api_key, timeout=600):
    headers = {"Authorization": f"Bearer {api_key}"}
    url = f"{base_url}/tasks/{task_id}"   # 상태 라우트는 API 참조 문서를 확인하세요
    deadline = time.time() + timeout
    delay = 2

    while time.time() < deadline:
        r = requests.get(url, headers=headers, timeout=30)
        r.raise_for_status()
        task = r.json()
        status = task["status"]

        if status == "succeeded":
            return task["result"]["video_url"]
        if status == "failed":
            raise RuntimeError(f"generation failed: {task.get('error')}")

        time.sleep(delay)
        delay = min(delay * 1.5, 15)   # 완만한 백오프, 상한 설정

    raise TimeoutError(f"task {task_id} not finished in {timeout}s")

백오프가 중요한 이유

1분 걸리는 생성 작업을 매초 고정 간격으로 폴링하면 수십 번의 요청을 낭비합니다. 작은 간격에서 시작해 점차 늘리세요. 위의 상한 배수는 빈번하게 API를 때리지 않으면서 편안한 간격으로 안정화됩니다. 작업을 많이 실행한다면 요청마다 루프를 두는 것보다 큐와 단일 폴링 워커를 쓰는 것이 더 우호적입니다.

결과 처리

작업이 성공하면 응답에 비디오 URL이 포함됩니다. 즉시 가져오고, 결과를 보존해야 한다면 자체 스토리지로 복사하세요. 서명된 URL은 영구적이지 않습니다. 파일을 사용자에게 전달하기 전에 다운로드 시 콘텐츠 타입과 크기를 확인하고, task_id를 저장된 자산과 함께 기록해 두어 향후 어떤 문제든 정확한 생성 기록으로 추적할 수 있게 하세요.

흔한 오류 해결

호출이 실패하면 이 체크리스트를 항목별로 점검하세요. 대부분의 실패는 다음 네 가지 범주 중 하나입니다.

인증과 접근

  • 401 / unauthorized —— 키가 없거나, 형식이 잘못되었거나, 전송되지 않았습니다. 요청 헤더가 정확히 Authorization: Bearer <key>인지, 호출을 수행하는 셸 또는 프로세스에 해당 환경 변수가 실제로 할당되었는지 확인하세요.
  • 403 / forbidden —— 키는 유효하지만 이 엔드포인트에 접근할 권한이 없습니다. 대시보드에서 해당 키의 권한 범위를 확인하세요.

요청 검증

  • 400 / 422 —— JSON 형식 오류 또는 잘못된 필드 값. 전체 오류 응답 본문을 출력하세요. 보통 해당 필드를 알려줍니다. duration 타입과 aspect_ratio 문자열 형식을 다시 확인하세요.
  • 제출 시 404 —— 엔드포인트 경로 오류. 경로가 정확히 pixverse-v6-max/text-to-video인지, base URL에 중복되거나 누락된 경로 세그먼트가 없는지 확인하세요.

작업 수준 실패

  • 상태가 failed —— 작업은 수락되었지만 생성이 실패했습니다. 작업의 오류 메시지를 읽으세요. 콘텐츠 거부와 내부 장애를 구분할 수 있습니다. 프롬프트 거부는 API 문제가 아니라 프롬프트 문제이므로 수정 후 다시 제출하세요.
  • 실행 상태에서 멈춤 —— 폴링에 마감 시간을 설정하고, 타임아웃을 서비스가 중단되는 예외가 아니라 처리해야 할 실패로 간주하세요.

운영 문제

  • 429 / 속도 제한 —— 진행 중인 제출 또는 폴링이 너무 많습니다. 동시성을 낮추고 응답의 재시도 안내를 따르세요.
  • 제출 시 연결 타임아웃 —— 생성 문제가 아니라 네트워크 또는 프록시 문제입니다. 중복 작업이 생겨도 감수할 수 있는 경우에만 백오프로 제출을 재시도하세요.
  • 다운로드 시 비디오 URL 404 —— URL이 만료되었습니다. 이전 URL을 재사용하지 말고 작업 결과를 다시 가져오세요.

반복 가능한 습관

모든 실패마다 세 가지 값을 기록하세요. HTTP 상태 코드, 응답 본문, 그리고 (있는 경우) task_id. 이 세 가지가 "고장 났다"를 "여기서 고장 났다"로 바꿔 주며, 이것이 디버깅을 빠르게 만드는 유일한 핵심입니다.

다음 단계

이제 전체 사이클을 익혔습니다. 인증, 제출, 작업 식별자 획득, 백오프를 포함한 폴링, 그리고 결과 가져오기입니다. 프로덕션에 투입하려면 제출과 폴링을 작은 클라이언트 클래스로 캡슐화하고, task_id와 프롬프트를 각 자산과 함께 저장해 추적 가능하게 하며, 폴링을 백그라운드 워커로 옮겨 사용자 대상 요청이 렌더링 때문에 절대 블로킹되지 않게 하세요.

다음으로 HiAPI 참조 문서의 인접 엔드포인트를 탐색해 보세요. 기존 정지 이미지에 애니메이션을 추가하는 이미지-투-비디오와, 전체 생성을 투입하기 전에 화면 스타일을 다듬을 수 있는 프롬프트 반복 상호작용 방식이 있습니다. 여기서 배운 요청 형태는 거의 그대로 옮겨 쓸 수 있습니다.

영구 AI 아티팩트로 빌드 시작하기

API 키를 받아 태스크 기반의 하나의 API로 이미지, 비디오, 오디오 모델을 호출하세요.

API 문서 보기