HiAPI
블로그

튜토리얼

veo-3.1 텍스트-투-비디오 API 호출 방법: curl 및 Python 예제

개발자를 위한 실전 통합 가이드

Nov 17, 2026
veo-3.1 텍스트-투-비디오 API 튜토리얼을 위한 짙은 페트롤, 틸, 말라카이트 색조의 평면 다면 광물 단면 커버 아트.
이 페이지에서

veo-3.1/text-to-video가 할 수 있는 일

veo-3.1/text-to-video는 HiAPI 통합 API를 통해 외부에 제공되는 텍스트-투-비디오 생성 모델입니다. 텍스트 프롬프트를 보내고 몇 가지 출력 옵션을 선택하면 생성된 비디오를 받게 됩니다. 다른 생성 엔드포인트와 함께 HiAPI에 있으므로, 이미 플랫폼에서 이미지나 채팅 기능을 사용하고 있다면 이 통합 방식이 익숙하게 느껴질 것입니다: 인증이 포함된 HTTP 요청 한 번이 작업을 반환하고, 작업이 완료될 때까지 폴링합니다.

장면에 대한 텍스트 설명이 있고 인프라를 직접 관리하지 않으면서 짧은 비디오를 생성하고 싶을 때 이 엔드포인트가 적합합니다. GPU 할당, 모델 가중치, 대기열을 직접 처리할 필요가 없습니다. 대가는 생성이 비동기적이라는 점입니다: 작업을 제출한 다음 나중에 결과를 확인합니다. 이는 비디오에서 일반적입니다. 렌더링에 단일 요청/응답 주기보다 더 오랜 시간이 걸리기 때문입니다.

핵심 입력이 프롬프트일 때는 텍스트-투-비디오를 사용하세요. 나중에 이미지 조건 또는 비디오 조건 생성을 원한다면 모델 카탈로그에서 해당 엔드포인트를 확인하세요. 여기의 요청 구조(인증, 작업 제출, 폴링)는 HiAPI 미디어 엔드포인트에서 재사용하게 될 패턴과 동일하므로 한 번 배우면 오래 활용할 수 있습니다. 전체 모델 세부 정보는 veo-3.1/text-to-video 모델 페이지에서 확인할 수 있습니다.

엔드포인트, 인증 및 요청 구조

모든 HiAPI 요청은 HTTPS와 bearer token을 사용합니다. API 키는 하드코딩하지 말고 환경 변수에 보관하고, Authorization 요청 헤더에 담아 전송하세요:

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

텍스트-투-비디오 요청은 model 필드와 input 객체를 포함하는 JSON 객체입니다. input 객체에는 프롬프트와 임의의 출력 제어 항목이 들어갑니다. 최소 요청 본문은 다음과 같습니다:

{
  "model": "veo-3.1/text-to-video",
  "input": {
    "prompt": "비에 젖은 네온 골목을 밤에 지나가는 느린 돌리인 샷"
  }
}

반환되는 것은 최종 비디오가 아니라 작업 봉투입니다. 일반적으로 작업 식별자, 상태 필드, 타임스탬프를 포함합니다. 구조는 대략 다음과 같습니다:

{
  "id": "job_abc123",
  "status": "queued",
  "created_at": "2025-01-01T00:00:00Z"
}

필드의 정확한 이름은 실제 응답을 기준으로 하되, 구조는 일관됩니다: 폴링하려면 id가 필요하고, status는 작업이 대기 중인지, 실행 중인지, 완료되었는지 알려줍니다. 제출 호출이 200을 반환했다고 해서 작업이 완료된 것으로 간주하지 마세요. 그것은 작업이 수락되었을 뿐입니다.

파라미터 선택: 네이티브 오디오와 해상도 티어

프롬프트 외에 텍스트-투-비디오에서 가장 중요한 파라미터는 네이티브 오디오 생성 여부와 대상 해상도 티어입니다. 둘 다 생성 시간과 출력 특성에 영향을 미치므로, 기본값을 맹목적으로 사용하지 말고 의식적으로 선택하세요.

네이티브 오디오

일부 비디오 모델은 화면 외에 오디오 트랙을 생성할 수 있습니다. 해당 엔드포인트가 네이티브 오디오 스위치를 제공한다면, 활성화하면 생성된 클립에 동기화된 사운드가 포함됩니다. 오디오 자체가 경험의 일부인 장면—환경 소음, 음악, 동작에 맞는 음향 효과—에 유용합니다. 나중에 자체 사운드트랙이나 내레이션을 추가할 계획이라면, 출력이 화면에 집중되도록 끄세요. 오디오 생성도 처리 시간을 늘리므로 정말 필요할 때만 활성화하세요.

해상도 티어

해상도 티어는 화면 충실도와 비용, 지연 사이에서 절충할 수 있게 해줍니다. 더 높은 티어는 더 선명한 출력을 생성하지만 시간이 더 오래 걸리고 리소스를 더 많이 소비합니다. 전달 목표를 충족하는 가장 낮은 티어를 선택하세요: 반복과 검토에는 초안 티어, 최종 렌더링에는 더 높은 티어. 하나의 프롬프트로 많은 후보를 생성할 경우 낮은 티어로 탐색한 다음, 승자를 전체 품질로 다시 생성하세요. 과금은 생성한 출력을 따르므로 티어를 의식적으로 선택하는 것이 주된 제어 수단입니다.

해당 엔드포인트가 현재 어떤 값을 허용하는지 확실하지 않다면, 프롬프트만으로 요청을 보낸 다음 응답이나 오류 메시지를 확인하세요. HiAPI는 허용 가능한 필드를 나열한 구조화된 검증 오류를 반환하므로 추측 없이 조정할 수 있습니다.

실행 가능한 curl 요청

이 curl 명령은 텍스트-투-비디오 작업을 제출합니다. JSON 콘텐츠 타입을 설정하고, 환경 변수에서 bearer token을 전달하며, model과 input을 포함한 요청 본문을 보냅니다.

curl -X POST https://api.hiapi.ai/v1/videos/generations \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1/text-to-video",
    "input": {
      "prompt": "비에 젖은 네온 골목을 밤에 지나가는 느린 돌리인 샷",
      "duration": 5,
      "resolution": "720p"
    }
  }'

호출에 성공하면 작업 id와 status를 포함한 JSON 객체가 반환됩니다. 이 id를 기록해 두세요. 폴링할 때 필요합니다. 스크립트를 작성하는 경우 출력을 JSON 처리기로 파이프하여 id를 추출할 수 있습니다:

JOB_ID=$(curl -s -X POST https://api.hiapi.ai/v1/videos/generations \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"veo-3.1/text-to-video","input":{"prompt":"비에 젖은 네온 골목을 밤에 지나가는 느린 돌리인 샷"}}' \
  | jq -r '.id')
echo "$JOB_ID"

실제 API가 기대하는 대로 엔드포인트 경로, 파라미터 이름, 임의의 선택 필드를 조정하세요. JSON 요청 본문을 POST하고 응답에서 id를 읽는 이 패턴이 이후 모든 예제의 기초입니다.

Python으로 동일한 요청 보내기

Python 버전은 표준 requests 라이브러리로 동일한 작업을 수행합니다. 환경에서 키를 읽고, payload를 구성한 다음 제출합니다.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "veo-3.1/text-to-video",
    "input": {
        "prompt": "비에 젖은 네온 골목을 밤에 지나가는 느린 돌리인 샷",
    },
}

response = requests.post(
    f"{BASE_URL}/videos/generations",
    headers=headers,
    json=payload,
    timeout=60,
)
response.raise_for_status()

job = response.json()
job_id = job["id"]
print(f"작업 제출됨: {job_id} (상태: {job.get('status')})")

두 가지를 강조할 가치가 있습니다. 첫째, response.raise_for_status()는 HTTP 오류를 예외로 변환하여 손상된 payload가 조용히 흘러가는 대신 실패가 즉시 드러나게 합니다. 둘째, timeout=60은 연결이 중단되어 스크립트가 차단되는 것을 방지합니다. 제출 자체는 빠릅니다. 실제 비디오는 비동기로 렌더링되므로 여기서 파일을 기다리지 않습니다. 다음으로 job_id를 사용해 완료 여부를 폴링합니다.

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

제출 후 상태가 완료 또는 실패를 나타낼 때까지 작업 엔드포인트를 폴링합니다. 짧은 대기가 포함된 간단한 루프로 시작하기에 충분합니다.

import time

while True:
    res = requests.get(
        f"{BASE_URL}/videos/generations/{job_id}",
        headers=headers,
        timeout=30,
    )
    res.raise_for_status()
    state = res.json().get("status")
    print(f"상태: {state}")

    if state == "succeeded":
        video_url = res.json().get("output", {}).get("url")
        print(f"비디오 준비됨: {video_url}")
        break
    if state == "failed":
        raise RuntimeError(f"작업 실패: {res.json()}")

    time.sleep(5)

몇 가지 실용적 개선 사항: 짧은 간격으로 시작한 다음 점진적으로 백오프하여 낭비되는 요청을 줄이고, 최대 시도 횟수나 마감 시간을 추가하여 멈춘 작업이 무한 루프되지 않도록 하며, 예상치 못한 상태를 "계속 기다리라"는 의미로 가정하지 말고 신중하게 처리하세요. 일반적인 상태 값으로는 queued, running, succeeded, failed가 있습니다. 작업이 성공하면 응답은 보통 출력 URL을 담고 있습니다. 서명된 URL은 만료될 수 있으므로 파일을 즉시 다운로드하여 저장하세요.

폴링을 멱등하게 만들고 각 상태에서 작업 id를 기록하세요. 프로세스가 재시작되면 다시 제출하지 않고 id로 복구할 수 있습니다. 프로덕션에서는 플랫폼이 webhook을 제공한다면 사용을 고려하고 폴링을 대체 수단으로 두세요.

일반적인 오류 해결

대부분의 실패는 몇 가지 범주에 속합니다. 무작정 재시도하지 말고 아래 체크리스트를 순서대로 확인하세요.

인증 실패(401/403)

Authorization 헤더가 존재하고 Bearer <key> 형식으로 올바르게 지정되었는지, 그리고 해당 환경 변수가 실제로 요청을 보내는 shell이나 프로세스에 설정되어 있는지 확인하세요. 흔한 함정은 한 shell에는 키가 있고 다른 환경에는 없는 곳에서 스크립트를 실행하는 것입니다.

검증 오류(400/422)

이러한 오류는 어느 필드가 잘못되었는지에 대한 구조화된 세부 정보를 반환합니다. 일반적인 원인: prompt 누락, 지원되지 않는 resolution 또는 duration 값, 또는 잘못된 파라미터 중첩 수준. 오류 메시지를 문자 그대로 이해하세요. 보통 문제가 있는 필드를 지적합니다. 최소 payload를 먼저 보낸 다음 한 번에 하나씩 파라미터를 추가하세요.

속도 제한(429)

요청을 너무 빠르게 보내고 있습니다. 지수 백오프와 재시도 상한을 구현하세요. 많은 작업을 시작할 경우 제출 시간을 분산하고 진행 중인 작업을 추적하세요.

타임아웃 및 네트워크 오류

제출 시 클라이언트 타임아웃은 작업 자체의 문제인 경우가 드뭅니다. 작업은 서버에서 실행됩니다. 제출과 폴링 요청 모두에 합리적인 타임아웃을 사용하고 멱등한 GET 요청을 재시도하세요. 원래 작업이 생성되었는지 확인하지 않고 POST를 맹목적으로 재시도하지 마세요.

작업이 완료되지 않음

작업이 예상보다 훨씬 오래 queued 또는 running에 머문다면, 다시 제출하지 말고 상태 코드와 메시지를 확인하세요. 긴 프롬프트나 더 높은 해상도 티어는 더 오래 걸립니다. 이는 정상입니다. 작업이 failed를 보고하면 전체 응답 본문을 기록하세요. 오류 메시지가 보통 원인을 지적합니다.

확실하지 않을 때는 가능한 한 최소한의 요청으로 재현하고 모든 응답을 확인하세요. 한 번에 여러 파라미터를 변경한 뒤 어느 것이 중요한지 추측하는 것보다 훨씬 낫습니다. 엔드포인트별 세부 사항은 모델 페이지를 참조하세요.

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

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

API 문서 보기