Veo 3.1 API는 어떻게 사용하나요? 5분 만에 첫 영상 생성하기

TL;DR

• Veo 3.1은 Google의 영상 생성 모델로, HiAPI에서는 표준판, Fast, Lite 세 가지로 나뉘며 텍스트 투 비디오와 이미지 투 비디오를 모두 지원합니다. 모델 페이지 열기에서 바로 온라인 생성이 가능하고, 신규 사용자 가입 시 200 크레딧을 지급합니다.
• 초 단위 과금: Lite 720p 무음 초당 $0.06, Fast 720p/1080p 사운드 포함 초당 $0.25, 표준판 초당 $0.57; 4초 Lite 초안은 $0.24밖에 안 합니다.
• API는 두 단계: POST /v1/tasks로 제출하고, taskId로 결과를 조회합니다. 아래의 curl과 Python은 복사해서 바로 실행할 수 있습니다.

Veo 3.1은 무엇을 할 수 있나요?

• 네이티브 사운드: 화면과 소리가 함께 생성되며, 환경음, 효과음, 동작의 소리 모두 화면에 맞춰 나옵니다. generate_audio는 기본 활성화되어 있으며 끄면 더 저렴합니다.
• 4초, 6초, 8초 세 가지 길이, 16:9 가로 또는 9:16 세로.
• 최대 4K: 표준판과 Fast는 720p, 1080p, 4K를 지원하고, Lite는 720p, 1080p를 지원합니다.
• 이미지 투 비디오: 이미지 한 장을 첫 프레임으로 전달하면 모델이 움직이게 하며, 화면 비율은 원본 이미지를 따를 수 있습니다.

아래 6초 1080p 세로 영상은 운동화 제품 이미지 한 장으로 한 번의 요청을 통해 생성되었으며, 착지하는 둔탁한 소리와 저음 드럼 비트는 모두 모델이 직접 넣은 것입니다:

The sneaker slowly rotates about 90 degrees as the camera pushes in from a low angle. Dust particles drift through the rim light. The shoe settles onto the wet stone pedestal with a deep, satisfying thud, sending a soft ring of mist rolling off the edges. A warm light sweep travels across the suede texture. Subtle bass-heavy electronic pulse builds in the background with a low whoosh on the landing. Cinematic product commercial, smooth stabilized motion, no text overlays.

이 프롬프트로 생성하기 → (먼저 9:16 제품 이미지를 업로드하세요)

veo-3.1/image-to-video, 1080p, 6초, 사운드 포함, $3.42, 제출부터 완료까지 약 115초.

세 가지 중 어떻게 선택할까요?

등급	720p/1080p 사운드 포함	720p/1080p 무음	4K 사운드 포함	적합한 용도
Lite veo-3.1-lite	$0.1(720p) / $0.14(1080p)	$0.06(720p) / $0.1(1080p)	—	프롬프트 조정, 대량 초안
Fast veo-3.1-fast	$0.25	$0.17	$0.6	소셜 숏폼 완성본
표준판 veo-3.1	$0.57	$0.29	$0.86	광고, 브랜드 영상

단위는 모두 초당입니다. 8초 사운드 포함: Lite 1080p $1.12, Fast $2, 표준판 $4.56. 더 자세한 비용은 Veo 3.1 API 가격을 참고하세요.

두 가지 시작 방법

온라인 체험(코딩 없이)

1. Veo 3.1 Lite 텍스트 투 비디오 모델 페이지를 열고 가입하거나 로그인합니다.
2. 프롬프트를 붙여넣고 길이, 해상도, 화면 비율을 선택하고 사운드 여부를 결정합니다.
3. 생성을 클릭하고, 영상이 나오면 바로 다운로드합니다.

API 호출

1. 콘솔에서 API Key를 생성합니다.
2. POST https://api.hiapi.ai/v1/tasks로 작업을 제출하고 taskId를 반환받습니다.
3. GET /v1/tasks/{taskId}로 상태를 조회하고, status가 success일 때 output[0].url에서 영상을 다운로드합니다.

curl: 첫 번째 영상

먼저 가장 저렴한 Lite로 실행해 보세요. 4초 720p 무음 $0.24:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-lite/text-to-video",
    "input": {
      "prompt": "A matte-black wireless earbud case slowly rotates on a reflective black surface under a single overhead spotlight.",
      "duration": 4,
      "resolution": "720p",
      "aspect_ratio": "9:16",
      "generate_audio": false
    }
  }'

반환:

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

결과 조회:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-... \
  -H "Authorization: Bearer $HIAPI_KEY"

Python: 제출, 폴링, 다운로드

# pip install requests；먼저 export HIAPI_KEY=你的 Key
import os, time, uuid, requests

KEY = os.environ["HIAPI_KEY"]
H = {"Authorization": f"Bearer {KEY}"}

def generate(prompt, model="veo-3.1-lite/text-to-video", timeout_s=900, **params):
    body = {"model": model, "input": {"prompt": prompt, **params}}
    # 重试提交同一个任务时带同一个 Idempotency-Key，避免重复扣费
    headers = {**H, "Idempotency-Key": str(uuid.uuid4())}
    r = requests.post("https://api.hiapi.ai/v1/tasks", json=body, headers=headers, timeout=30)
    r.raise_for_status()
    res = r.json()
    if res.get("code") != 200:
        raise RuntimeError(res)
    task_id = res["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(10)
    raise TimeoutError(task_id)

url = generate(
    "A barista pours hot water in a slow spiral over ground coffee, steam rising in morning light",
    duration=4, resolution="720p", aspect_ratio="16:9", generate_audio=True,
)
with open("clip.mp4", "wb") as f:
    f.write(requests.get(url).content)

프롬프트를 정한 후에는 model을 veo-3.1-fast/text-to-video 또는 veo-3.1/text-to-video로 바꿔 완성본을 생성하면 되고, 다른 파라미터는 그대로 둡니다.

이미지 투 비디오

모델명을 …/image-to-video로 바꾸고, input에 이미지를 추가합니다(image_url은 문자열이며 한 장만 받습니다):

{
  "model": "veo-3.1/image-to-video",
  "input": {
    "prompt": "The sneaker slowly rotates and settles onto the wet stone pedestal with a deep thud",
    "image_url": "https://your-cdn.example.com/sneaker-916.jpg",
    "aspect_ratio": "auto",
    "resolution": "1080p",
    "duration": 6
  }
}

• aspect_ratio에 auto를 쓰면 원본 이미지를 따릅니다. 16:9 또는 9:16을 지정할 수도 있으며, 다른 비율의 이미지는 잘립니다.
• 원본 이미지는 720p 이상, 16:9 또는 9:16을 권장하며 SVG는 지원하지 않습니다.
• 프롬프트에는 "다음 몇 초 동안 어떻게 움직일지"를 쓰면 되고, 이미지 전체를 다시 설명할 필요는 없습니다.

출시 전 주의사항

• 폴링 대신 콜백 사용: 요청 최상위에 "callback": {"url": "https://你的域名/hiapi/callback"}을 추가하면 작업 종료 시 HiAPI가 능동적으로 알려주며, taskId로 중복을 제거합니다.
• 즉시 저장: output[0].url은 임시 링크이므로 받은 즉시 자체 스토리지에 저장하세요.
• 파라미터 전부 기재: duration은 기본 8초이며, 표준판과 Fast의 resolution은 필수입니다. 길이, 해상도, generate_audio를 명시해야 비용이 예산과 맞습니다.
• 사운드가 필요 없으면 끄기: generate_audio: false로 설정하면 Lite 720p는 초당 $0.1에서 $0.06으로, 표준판은 $0.57에서 $0.29로 내려갑니다.
• 실패 시 자동 환불: 성공적으로 생성된 영상에 대해서만 과금합니다.

자주 묻는 질문

프롬프트를 중국어로 쓸 수 있나요?

네, 중국어와 영어 모두 가능합니다. 카메라, 동작, 사운드를 문장으로 나눠 쓰면 가장 안정적입니다.

10초 영상을 생성할 수 있나요?

한 번에는 4초, 6초, 8초만 지원합니다. 더 긴 완성본은 구간별로 생성한 후 편집하면 됩니다.

사운드를 개별적으로 제어할 수 있나요?

프롬프트에 각 사운드 레이어(가까운 동작음, 환경 인물 소리, 바람 소리)를 명확히 쓰면 모델이 각각 생성합니다. 사운드가 필요 없으면 generate_audio를 false로 설정하세요.

Lite로 조정한 프롬프트를 표준판으로 바꿀 때 무엇을 수정해야 하나요?

모델명만 바꾸면 됩니다. prompt, duration, aspect_ratio, generate_audio는 모두 공통으로 사용할 수 있으며, 4K가 필요하면 resolution을 4k로 변경하세요(Lite에는 4K가 없습니다).

바로 사용할 수 있는 프롬프트를 원하시면 Veo 3.1 프롬프트 사례를 참고하세요. 위의 운동화 프롬프트를 복사해서 모델 페이지에서 생성하기.