튜토리얼

hiapi API를 통해 veo-3.1-lite/image-to-video를 사용하는 방법

Aug 27, 2026

모델: veo-3.1-lite

Veo 3.1 Lite는 단일 참조 이미지와 텍스트 프롬프트를 짧은 영상으로 변환하며, hiapi에서는 플랫폼의 모든 모델이 공유하는 동일한 비동기 작업 API를 통해 제공됩니다. 이 가이드는 실제로 동작하는 요청 흐름을 단계별로 살펴봅니다. 키 발급, POST /v1/tasks 호출, 결과 가져오기, 그리고 이 흐름을 일회성 스크립트에서 프로덕션 환경으로 옮길 때 주의해야 할 세부 사항(콜백, 멱등성, 오류 처리)까지 다룹니다.

무엇을 만들며, 먼저 무엇을 준비해야 하는가

이미지 URL과 프롬프트를 veo-3.1-lite/image-to-video 모델에 보내면 외부에 호스팅된 .mp4 URL을 받게 됩니다. 모든 것은 hiapi의 통합 작업 엔드포인트를 통해 실행되므로 동일한 요청 구조가 플랫폼의 모든 비디오 및 이미지 모델에 적용됩니다. 달라지는 것은 model id와 input 필드뿐입니다.

시작하기 전에:

hiapi 계정을 만들고 콘솔에서 API 키를 발급받으세요. 키는 sk-... 형태입니다.
공개적으로 접근 가능한 이미지 URL을 준비하세요. API가 서버 측에서 이미지를 가져오므로 localhost 경로나 프라이빗 버킷은 사용할 수 없습니다.
실제(테스트가 아닌) 요청을 실행하기 전에 가격 페이지에서 veo-3.1-lite/image-to-video의 현재 가격을 확인하세요. 비용은 길이와 해상도에 따라 달라집니다.

무료 티어나 키 없는 모드는 없습니다. 모든 호출에는 Authorization: Bearer sk-<your-key>가 필요합니다.

최소 동작 예제

hiapi의 작업 API는 두 번의 호출로 이루어집니다. 작업을 생성한 다음, 폴링하거나 콜백으로 작업 완료 시점을 통지받으면 됩니다. 아래는 requests와 time만 사용하는 폴링 방식의 Python 코드입니다:

import time
import requests

API_KEY = "sk-your-key-here"
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

payload = {
    "model": "veo-3.1-lite/image-to-video",
    "input": {
        "prompt": "the camera slowly pushes in as steam rises from the cup",
        "image_url": "https://example.com/your-reference-image.jpg",
        "duration": 6,
        "aspect_ratio": "16:9",
    },
}

# 1. Create the task
resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task created:", task_id)

# 2. Poll until it's done
while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    status = task["status"]
    if status == "success":
        video_url = task["output"][0]["url"]
        print("done:", video_url)
        break
    if status == "fail":
        raise RuntimeError(task.get("error"))
    time.sleep(5)

와이어 상의 전송 형식만 보고 싶다면, 동일한 작업을 원시 curl로 작성하면 다음과 같습니다:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-lite/image-to-video",
    "input": {
      "prompt": "the camera slowly pushes in as steam rises from the cup",
      "image_url": "https://example.com/your-reference-image.jpg",
      "duration": 6,
      "aspect_ratio": "16:9"
    }
  }'

# then poll:
curl -s https://api.hiapi.ai/v1/tasks/<taskId> \
  -H "Authorization: Bearer sk-your-key-here"

input 스키마에 관해 특히 알아둘 점이 몇 가지 있습니다. 이 모델은 아무거나 받아주는 범용 엔드포인트보다 엄격해서, 불필요한 필드는 조용히 무시되지 않고 그대로 거부됩니다:

prompt와 image_url이 유일한 두 개의 필수 필드입니다. image_url은 단수형입니다. 이 모델은 정확히 한 장의 참조 이미지만 받으며, 배열이 아닙니다.
duration은 4, 6, 8(초)만 허용됩니다. 다른 정수는 받지 않습니다.
aspect_ratio는 auto, 16:9, 9:16을 받습니다.
resolution은 720p 또는 1080p를 받습니다.
선택적 추가 항목: seed(정수, 재현용), generate_audio(불리언), negative_prompt(문자열).

모델 id는 맨 id, 즉 veo-3.1-lite/image-to-video라는 점에 주의하세요. 여기에 접두사나 네임스페이스를 추가하지 마세요.

status가 "success"가 되면 출력 영상은 data.output[0].url에 위치합니다. 이 URL은 임시입니다(expireAt 포함). 따라서 핫링크를 저장하지 말고 즉시 다운로드하거나 다시 호스팅하세요.

프로덕션 환경 고려 사항: 콜백, 멱등성, 오류

5초마다 폴링하는 것은 스크립트에서는 괜찮지만, 많은 작업을 동시에 처리하는 서버에서는 낭비입니다. 프로덕션 트래픽에는 콜백이 더 권장됩니다. 동일한 작업 생성 요청에 callback 객체를 전달하면 hiapi가 직접 결과를 묻는 대신 최종 결과를 여러분의 엔드포인트로 POST합니다.

payload = {
    "model": "veo-3.1-lite/image-to-video",
    "input": {
        "prompt": "the camera slowly pushes in as steam rises from the cup",
        "image_url": "https://example.com/your-reference-image.jpg",
    },
    "callback": {
        "url": "https://yourapp.example.com/hooks/hiapi",
        "when": "final",
    },
}

여기서 핵심 설정은 when: "final"입니다. 이는 작업이 종료 상태(success 또는 fail)에 도달했을 때 한 번만 알림을 받고, 중간 상태가 바뀔 때마다 알림을 받지 않는다는 뜻입니다. 웹훅 핸들러는 작업 id를 검증한 다음, 처음 POST /v1/tasks를 호출할 때 생성한 로컬 작업 레코드를 조회해야 합니다.

멱등성. 서비스가 작업 생성 호출을 재시도할 수 있다면(타임아웃, 최소 1회 전달 등), 최대 255바이트의 Idempotency-Key 헤더를 추가하세요:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Idempotency-Key: order-42-veo-submit" \
  -H "Content-Type: application/json" \
  -d '{...}'

동일한 계정에서 같은 키로 재시도하면 두 번째(과금 가능한) 작업이 생성되는 대신 원래 taskId가 반환됩니다. 따라서 고객에게 중복 청구될 걱정 없이 재시도 루프에서 안심하고 호출할 수 있습니다.

폴링 대 콜백, 간단히 말하면: 스크립트, 노트북, 낮은 트래픽의 내부 도구처럼 어차피 결과를 기다리며 블로킹하는 경우에는 폴링을 사용하세요. 서버 측에서 동시 처리가 필요한 모든 상황에서는 콜백을 사용하세요. 연결을 열어둘 필요가 없고, 작업마다 폴링 루프를 돌리지 않고도 다수의 진행 중 작업으로 확장할 수 있습니다.

오류 처리. 오류가 있거나 폐기된 키는 HTTP 401과 error.code: "permission_denied"를 반환합니다. 2xx가 아닌 모든 응답이 영상 생성 자체의 실패를 의미한다고 가정하지 말고 이 부분을 별도로 확인하세요. 형식이 잘못된 input(prompt 누락, duration이 허용 범위를 벗어남, 인식할 수 없는 필드)은 HTTP 400과 error_code: "INVALID_REQUEST"를 반환하며, 문제가 되는 필드를 명시한 메시지를 함께 줍니다. 이 메시지는 삼키지 말고 여러분의 로그에 그대로 노출할 가치가 있습니다. 무엇을 고쳐야 하는지 정확히 알려주기 때문입니다. 작업이 접수된 후 생성 측 실패는 폴링/콜백 페이로드의 status: "fail"과 error 객체로 나타납니다. 메시지가 업스트림의 일시적 문제임을 나타낼 때만 재시도 가능으로 처리하고, 스키마 문제라면 그렇게 하지 마세요.

자주 묻는 질문

image_url을 data URI나 base64로 전달해야 하나요? 아니요. image_url은 hiapi 서버가 가져올 수 있는 공개 HTTP(S) URL이어야 합니다. 이 모델은 base64로 인코딩된 이미지를 받지 않습니다.

참조 이미지 없이 영상을 생성할 수 있나요? veo-3.1-lite/image-to-video로는 안 됩니다. 이 모델은 이미지-투-비디오 모델이며 image_url이 필수입니다. 순수 텍스트 생성이 필요하다면 텍스트-투-비디오 모델을 사용하세요. 비-lite Veo 3.1 모델 페이지에 사용 가능한 모드가 나열되어 있습니다.

필수 필드를 모두 넣었는데 왜 여전히 400이 반환되나요? 추가 필드가 있는지 확인하세요. 이 모델의 입력 스키마는 허용 목록(prompt, image_url, duration, aspect_ratio, resolution, seed, generate_audio, negative_prompt)에 없는 모든 것을 거부합니다. 오류 메시지는 인식하지 못한 정확한 필드를 알려줍니다.

생성에 실제로 얼마나 걸리나요? 지속 시간과 현재 큐 깊이에 따라 달라집니다. 그래서 고정된 대기 시간을 가정하지 말고 짧은 간격의 폴링이나 콜백을 사용하는 것이 올바른 접근입니다.

출력에 오디오를 넣을 수 있나요? 네, generate_audio 불리언을 통해 가능합니다. 현재 기본값과 비용에 미치는 영향은 모델 문서를 확인하세요.

작업 완료 시 콜백 엔드포인트가 다운되어 있었다면 어떻게 되나요? 콜백 도착에만 의존하지 마세요. 생성 호출이 반환한 taskId를 보관하고, 합리적인 시간 내에 콜백을 받지 못하면 GET /v1/tasks/<id> 폴링으로 전환하세요.