블로그

튜토리얼

HiAPI API로 gemini-omni-flash/text-to-video 사용하는 방법: curl 및 Python 가이드

Nov 12, 2026
커버 이미지: 겹겹이 쌓인 베이지색 종이 조각들이 어긋나게 펼쳐져 있고, 적갈색 종이 한 장이 포인트로 더해져 절제된 층리의 리듬을 이룹니다.
이 페이지에서

이 엔드포인트가 하는 일과 사용 시점

gemini-omni-flash/text-to-video는 HiAPI의 생성 엔드포인트로, 텍스트 프롬프트를—선택적으로 첫 프레임 이미지를 기준점으로 삼아—짧은 영상으로 변환합니다. 요청을 보내면 HiAPI가 폴링 가능한 작업을 반환하고, 작업이 완료되면 다운로드하거나 스트리밍할 수 있는 영상 URL을 받습니다.

다음 상황에서 이 엔드포인트가 적합합니다:

  • 빠른 콘셉트 클립. 한두 문장 설명만으로 짧은 마케팅 티저, 스토리보드 미리보기, 소셜 미디어 전환 소재를 생성합니다.
  • 이미지 기반 모션. 제품 사진, 캐릭터 디자인, 일러스트레이션 같은 정지 이미지가 이미 있고, 이를 처음부터 새로 생성하지 않고 움직이게 하고 싶을 때.
  • 파이프라인에서의 대량 생성. 생성이 비동기이므로 백엔드 워커에서 수많은 작업을 한꺼번에 제출하고 나중에 결과를 수집할 수 있으며, 요청 연결을 유지할 필요가 없습니다.

긴 영상, 프레임 단위의 정밀 편집, 또는 특정 장면의 결정론적 재현에는 적합하지 않습니다. 빠른 생성형 초안으로 생각하세요: 반복 비용이 낮고, 검토하기 충분하며, 엔드투엔드로 스크립트화할 수 있습니다.

아래의 모든 내용은 동일한 HiAPI 인터페이스를 사용합니다—하나의 API key, 하나의 기본 URL, 하나의 요청 구조—따라서 여기서 작성한 코드는 인증이나 폴링을 다시 배우지 않고도 다른 생성 엔드포인트로 옮길 수 있습니다.

첫 요청을 보내기 전에

첫 호출이 성공하기 전에 네 가지를 준비해야 합니다.

1. API key

HiAPI 계정에서 key를 생성하고 소스 코드가 아닌 환경 변수에 저장하세요:

export HIAPI_API_KEY="your_key_here"

2. 기본 URL과 엔드포인트 경로

모든 요청은 HiAPI 기본 URL로 전송되며, 모델 식별자는 경로에 포함됩니다. 코드에서 기본 URL을 단일 상수로 취급하면 한 곳만 수정하면 됩니다:

export HIAPI_BASE_URL="https://api.hiapi.ai"

3. JSON 요청 본문

요청은 POST이며 Content-Type: application/json을 사용하고, Authorization 헤더에 bearer token을 담습니다. URL로 첫 프레임 이미지를 제공하지 않는 한 폼 인코딩도, multipart 업로드도 없습니다.

4. 첫 프레임 이미지 (선택 사항)

이미지로 생성을 유도할 계획이라면 먼저 해당 이미지가 공개 HTTPS URL로 접근 가능한지 확인하세요. 로컬 파일 시스템 경로는 사용할 수 없습니다—API가 서버 측에서 이미지를 가져옵니다.

비용 의식에 관한 실용적인 팁: 이 엔드포인트는 생성한 출력에 대해 과금되며—해상도 등급과 클립 길이가 모두 반영됩니다. 현재 단가는 HiAPI 가격 패널에서 확인하세요. 따라서 대량 작업을 확장하기 전에 그곳에서 확인하는 것이 좋습니다. 중요한 습관은 최소 설정으로 프로토타입을 만들고, 프롬프트가 원하는 결과를 낼 때 설정을 올리는 것입니다.

생성 요청 구성하기

요청은 개념적으로 세 부분으로 구성됩니다: 모델 경로, 프롬프트(및 선택적 이미지), 생성 옵션. 구조는 다음과 같습니다:

{
  "prompt": "A slow dolly-in on a glass coffee cup as steam curls upward, morning light, shallow depth of field",
  "image": "https://your-bucket.example.com/first-frame.jpg",
  "resolution": "720p",
  "duration": 5,
  "audio": false
}

프롬프트

prompt 필드는 장면 설명을 담습니다. 감독 노트처럼 작성하세요: 피사체, 카메라 동작, 조명, 분위기. 구체적인 동작 동사("slow dolly-in", "camera pans left", "steam curls upward")가 형용사만 나열하는 것보다 결과를 더 안정적으로 유도합니다.

선택적 첫 프레임

image 필드는 선택 사항입니다. 생략하면 모델이 텍스트만으로 전체 클립을 생성합니다. 포함하면 클립이 해당 프레임에서 시작하고 프롬프트는 그다음에 무슨 일이 일어나야 하는지 설명합니다. 이는 일관성에 가장 큰 영향을 주는 요소입니다: 순수 텍스트 프롬프트는 매 실행마다 장면을 새로 구상하지만, 첫 프레임을 고정하면 여러 반복에 걸쳐 구도를 안정적으로 유지할 수 있습니다.

둘 다 제공하는 경우 서로 일치하는지 확인하세요. 사막 풍경의 첫 프레임에 비 오는 도시 거리 프롬프트를 붙이면 혼란스러운 결과가 나옵니다—모델이 서로 모순되는 두 지시를 조화시켜야 하기 때문입니다.

옵션 위치

resolution, duration, audio는 prompt, image와 함께 동일한 JSON 본문의 최상위에 위치합니다. 중첩된 options 객체를 기억할 필요가 없습니다. 요청 본문을 평평하고 읽기 쉽게 유지하세요—이렇게 하면 대량 작업을 디버깅할 때 로깅과 요청 차이 비교가 훨씬 쉬워집니다.

해상도와 길이 선택하기

두 매개변수는 출력 모양과 작업 비용을 모두 좌우합니다: 해상도 등급과 클립 길이.

해상도 등급

HiAPI는 이 엔드포인트를 여러 해상도 등급으로 제공합니다. 낮은 등급은 프롬프트 개발 단계의 적절한 기본값입니다—렌더링이 더 빨라서 버릴 세부 사항에 비용을 지불하지 않고 문구를 반복할 수 있습니다. 프롬프트가 원하는 구도를 안정적으로 만들어내면 최종 렌더링을 위해 등급을 올리세요.

실용적인 워크플로:

  1. 최저 등급에서 프롬프트를 초안 작성합니다.
  2. 두세 가지 변형을 생성하고 비교합니다.
  3. 프롬프트를 확정한 뒤 더 높은 등급에서 다시 렌더링합니다.

클립 길이

길이는 초 단위로 지정되며, 이 엔드포인트는 짧은 클립을 중심으로 설계되었습니다. 길이를 적당하게 유지하세요: 짧은 클립은 개별 작업이 더 빠르고 실패 시 재시도 비용이 낮으며, 나중에 더 긴 시퀀스가 필요하면 여러 클립을 이어 붙일 수 있습니다. 한 장면에 8초의 화면 시간이 필요하다면 4초 생성 두 번이 긴 생성 한 번보다 보통 더 관리하기 쉽습니다.

예산에 매핑하는 방법

이 엔드포인트는 생성한 출력에 대해 과금되며—더 높은 해상도와 더 긴 길이는 모두 개별 작업의 과금 대상 출력을 늘립니다. 가격은 생성 단위로 계산되고 등급은 시간이 지나며 변할 수 있으므로, 예상을 하드코딩하지 말고 HiAPI 가격 패널의 실시간 숫자를 읽으세요. 어떤 가격 변동에도 유효한 계획 규칙: 예상 작업 수에 출력 규모를 곱하고, 최소 설정으로 프로토타입을 만들고, 마지막에 해상도를 확장하세요.

네이티브 오디오 제어

audio 플래그는 반환된 영상에 화면과 함께 생성된 네이티브 오디오 트랙이 포함되는지 결정합니다.

{
  "prompt": "Rain hammering a tin roof, a door creaks open slowly",
  "audio": true
}

켜면 무엇이 달라지나

audio: true를 사용하면 모델이 프롬프트에 설명된 장면과 어울리는 소리—앰비언스, 환경 질감, 동작이 암시하는 사운드 이벤트—를 생성합니다. 출력 영상에 오디오 스트림이 포함되므로 다운로드한 파일이 이미 완전하며 별도의 음향 처리 작업이 필요 없습니다.

끄면 무엇이 달라지나

audio: false를 사용하면 무음 영상을 얻습니다. 다음과 같은 경우에 적합합니다:

  • 편집기에서 클립에 자체 음악이나 내레이션을 얹을 예정입니다.
  • 클립이 더 큰 합성 작업의 배경 요소입니다.
  • 화면만 반복하고 오디오 생성이 루프에 들어오는 것을 원하지 않습니다.

오디오를 위한 프롬프트 작성

오디오를 활성화하는 경우 화면을 설명하듯 음향 풍경도 설명하세요. 프롬프트의 소리 단서—빗소리, 발소리, 기계음, 특정 방의 분위기—가 오디오 모델에 근거를 제공합니다. 순수 시각 프롬프트도 오디오를 생성하지만, 장면에 맞는 소리가 아니라 일반적인 환경음이 됩니다.

일찍 테스트할 만한 주의점: 오디오는 클립의 성격을 크게 바꿉니다. 같은 프롬프트를 켜고 끈 플래그로 각각 생성하여 둘 다 보고, 이를 중심으로 대량 작업을 구축하기 전에 프로젝트에 실제로 어떤 모드가 필요한지 결정하세요.

비동기 작업 수명 주기 처리

영상 생성은 일반적인 HTTP 요청이 연결을 열어 두어야 하는 시간보다 오래 걸리므로 이 엔드포인트는 비동기입니다. 모든 호출은 동일한 세 단계 루프를 따릅니다.

1단계: 제출

JSON 본문을 엔드포인트로 POST합니다. 성공적으로 제출되면 즉시 작업 식별자—보통 작업 id—와 작업이 대기열에 있거나 처리 중임을 나타내는 상태를 반환합니다. 이 시점에는 아직 아무것도 렌더링되지 않았습니다.

2단계: 폴링

작업 id를 받아 고정 간격으로 작업 상태 엔드포인트를 조회합니다. 각 폴링은 현재 상태(queued, processing, completed, failed)를 반환합니다. 네 가지 상태를 모두 처리해야 합니다. 간단한 지수 백오프—약 2초에서 시작하고 간격에 상한을 두기—를 사용하면 긴 작업에서 API를 과도하게 호출하지 않으면서도 짧은 작업은 빠르게 포착할 수 있습니다.

3단계: 가져오기

상태가 완료를 보고하면 응답에 완성된 영상 URL과 해당 작업의 메타데이터가 포함됩니다. 이를 다운로드하거나 저장하거나 프런트엔드에 URL을 넘기세요. 상태가 실패를 보고하면 응답에서 오류 정보를 캡처하고 프롬프트를 수정하여 재시도할지, 아니면 실패를 노출할지 결정합니다.

내장해야 할 보호 장치

  • 시간 초과 상한. 총 폴링 시간(예: 몇 분)을 제한하고, 무한 루프에 빠지는 대신 자체 코드에서 작업을 실패로 표시하세요.
  • 최대 폴링 횟수. 상태가 계속 불명확할 때 통제 불능 루프를 방지하세요.
  • 작업 id 영속화. 받는 즉시 데이터베이스나 로그에 기록하세요. 프로세스가 폴링 도중 중단되면 다시 생성하여 두 번 비용을 지불하는 대신 복구할 수 있습니다.
  • 멱등 제출. 첫 요청이 실패했다고 확인되기 전에는 네트워크 흔들림 때문에 다시 제출하지 마세요; 중복 작업은 실제 출력을 소비합니다.

이 루프를 한 번 제대로 구현하면 HiAPI의 모든 비동기 엔드포인트에 적용할 수 있습니다.

실행 가능한 curl 및 Python 예제

curl: 제출, 폴링, 가져오기

환경 변수로 key와 기본 URL을 설정한 다음 제출하세요:

curl -sS -X POST "$HIAPI_BASE_URL/v1/models/gemini-omni-flash/text-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A slow dolly-in on a glass coffee cup as steam curls upward, morning light, shallow depth of field",
    "image": "https://your-bucket.example.com/first-frame.jpg",
    "resolution": "720p",
    "duration": 5,
    "audio": false
  }'

응답에는 작업 id가 포함됩니다. 응답에서 상태 엔드포인트를 가져와 폴링하세요:

curl -sS "$HIAPI_BASE_URL/v1/tasks/<TASK_ID>" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

상태가 completed가 될 때까지 반복한 다음 응답 본문에서 영상 URL을 꺼내 다운로드하세요:

curl -sS -o clip.mp4 "<VIDEO_URL>"

Python: 동일한 루프를 함수로 감싸기

import os
import time
import requests

BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}


def generate_video(prompt, image_url=None, resolution="720p",
                   duration=5, audio=False, timeout=300):
    payload = {
        "prompt": prompt,
        "resolution": resolution,
        "duration": duration,
        "audio": audio,
    }
    if image_url:
        payload["image"] = image_url

    resp = requests.post(
        f"{BASE}/v1/models/gemini-omni-flash/text-to-video",
        headers=HEADERS, json=payload, timeout=30,
    )
    resp.raise_for_status()
    task_id = resp.json()["id"]
    print(f"submitted: {task_id}")

    deadline = time.time() + timeout
    interval = 2
    while time.time() < deadline:
        status_resp = requests.get(
            f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30
        )
        status_resp.raise_for_status()
        data = status_resp.json()
        state = data.get("status")

        if state == "completed":
            return data["video_url"]
        if state == "failed":
            raise RuntimeError(f"job failed: {data}")

        time.sleep(interval)
        interval = min(interval * 1.5, 10)

    raise TimeoutError(f"job {task_id} did not finish in {timeout}s")


if __name__ == "__main__":
    url = generate_video(
        "A slow dolly-in on a glass coffee cup as steam curls upward, "
        "morning light, shallow depth of field",
    )
    print("video ready:", url)

이 스크립트는 순수 텍스트 작업을 제출하고, 백오프를 적용해 폴링하며, 시간 초과 상한을 강제하고, 완료된 URL을 반환합니다. image_url=을 전달하면 생성을 첫 프레임에 고정하고, audio=True로 설정하면 네이티브 사운드를 포함합니다. 여기서부터 generate_video를 워커 큐, FastAPI 라우트, 또는 대량 루프에 넣을 수 있습니다—이 함수는 자체 포함적이며 생성한 작업 id 외에는 상태가 없습니다.

흔한 실패 지점과 회피 방법

대부분의 실패한 통합은 다음 다섯 가지 문제 중 하나에 걸립니다.

제출 시 잘못된 매개변수로 거부됨

가장 흔한 원인은 API가 요청 본문을 파싱할 수 없는 경우입니다: prompt 누락, 지원 범위를 벗어난 길이, 또는 지원되지 않는 해상도 문자열. 엔드포인트 참조에서 허용 값을 확인하고 먼저 로컬에서 검증하세요. 호출 전에 허용 값을 검사하는 작은 도구가 한 번의 왕복과 혼란스러운 오류를 절약합니다.

첫 프레임 이미지에 접근 불가

API는 서버 측에서 image를 가져오므로 브라우저에서 동작하는 URL도 실패할 수 있습니다—비공개 버킷, 만료되는 서명 링크, 핫링크 방지가 모두 이 문제를 일으킵니다. 공개적으로 읽을 수 있는 HTTPS URL을 사용하고, 제출 전에 네트워크 외부에서도 확인할 수 있는지 검증하세요.

폴링 포기

같은 실수의 두 가지 변형: 첫 processing 응답을 받고 포기하여 실패로 가정하거나, 너무 공격적으로 폴링하여 속도 제한에 도달하는 경우. 위에서 보여준 상한이 있는 백오프 루프로 둘 다 해결하세요: 일정에 따라 폴링하고, 비종료 상태를 정상으로 간주하며, 명확한 실패나 시간 초과에서만 예외를 던지세요.

작업 id 분실

제출 후 결과를 저장하기 전에 프로세스가 종료되면 작업은 이미 지불되었지만 접근할 수 없게 됩니다. 제출 직후 작업 id를 영속 저장소에 기록하고, 시작 시 진행 중인 id가 있는지 확인한 뒤 새 작업을 제출하세요.

규모 확장 시 출력 과다

높은 해상도와 긴 길이로 대량 생성하면 출력량이 빠르게 커지며, 생성된 파일은 저장 비용이 높고 제공 속도가 느립니다. 소규모로 프로토타입을 만들고 최종 렌더링은 한 번만 하며, 저장 수명 주기 규칙을 유지하세요. 과금이 생성 출력과 연동되므로 가장 저렴한 해결책은 거의 항상 더 작은 프로토타입 반복 루프입니다.

프리프로덕션 환경에서 이 체크리스트를 한 번 훑으면 프로덕션 경로가 원활해집니다.

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

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

API 문서 보기