블로그

튜토리얼

HiAPI API를 통해 gemini-omni-flash로 동영상을 생성하는 방법

텍스트-투-비디오와 이미지-투-비디오의 요청 경로, 모델 선택, 그리고 사용 가능한 통합 체크리스트

Nov 9, 2026
세이지와 짙은 소나무 톤의 분할 프리즘으로 구성된 기하학적 표지로, 기사의 표지를 나타냅니다.
이 페이지에서

gemini-omni-flash에 동영상 엔드포인트가 두 개인 이유

첫 줄의 코드를 작성하기 전에 가장 중요한 결정은 이것입니다. 실제로 두 동영상 엔드포인트 중 어느 것이 필요한가입니다. gemini-omni-flash는 HiAPI에서 모드 플래그가 있는 단일 엔드포인트가 아니라 두 개의 별도 모델로 제공됩니다:

  • gemini-omni-flash/text-to-video — 텍스트 프롬프트만으로 동영상을 생성합니다.
  • gemini-omni-flash/image-to-video — 제공된 소스 이미지를 시각적 기준점으로 삼고 텍스트 프롬프트의 안내를 받아 동영상을 생성합니다.

이렇게 분리된 이유는 두 작업의 입력이 다르고, 검증 규칙이 다르며, 실패 유형도 다르기 때문입니다. 텍스트-투-비디오는 프롬프트 문자열 하나만 검증하면 됩니다. 이미지-투-비디오는 소스 이미지를 가져와 디코딩해야 하므로 텍스트 경로에서는 전혀 나타나지 않는 오류(URL 접근 불가, 지원되지 않는 형식, 리소스 크기 초과)가 한 종류 더 생깁니다.

경험칙: 이미 정지 이미지가 있다면—제품 사진, 스토리보드 프레임, 사진—이미지-투-비디오를 사용하세요. 모델이 시각적 콘텐츠에서 출발하기 때문입니다. 아이디어만 있고 참조 자료가 없다면 텍스트-투-비디오를 사용하세요.

첫날부터 코드베이스에서 두 모델 ID를 구분하세요. 이 둘을 하나의 "동영상" 개념으로 취급하고 나중에 if has_image 플래그를 덧붙이는 방식이 바로 통합이 엉망인 페이로드와 이해하기 어려운 버그로 끝나는 이유입니다.

변하지 않는 것

두 엔드포인트는 동일한 인증 방식, 동일한 기본 URL, 동일한 일반 요청/응답 규약, 동일한 청구 모델(동영상은 요청 횟수가 아니라 생성된 출력 기준으로 청구)을 공유합니다. 바로 이 공통 부분 덕분에 단일 요청 빌더가 실현 가능한 방식이 됩니다—뒤에서 자세히 설명합니다.

다른 것

페이로드 구조와 입력 검증만 다릅니다. 차이는 전체 통합 코드를 중복하지 않고도 두 엔드포인트를 모두 지원할 수 있을 만큼 작습니다.

사전 준비와 API 설정

첫 호출 전에 세 가지가 필요합니다.

1. API 키

HiAPI 계정에서 키를 생성하고 하드코딩하지 말고 환경 변수로 저장하세요:

export HIAPI_API_KEY="your_key_here"

모든 요청은 Authorization 헤더의 bearer 토큰으로 인증됩니다. 별도의 서명 단계도, 요청별 nonce도 없습니다.

2. 기본 URL과 모델 명명 규칙

모든 호출은 동일한 HiAPI 기본 URL로 전송되며, 모델은 요청 본문의 model 필드로 선택됩니다. 모델 ID는 family/variant 패턴을 따르므로 동영상 모델은 gemini-omni-flash/text-to-video와 gemini-omni-flash/image-to-video로 표기됩니다. 엔드포인트를 전환하려면 호스트를 바꾸는 것이 아니라 문자열 하나만 바꾸면 됩니다.

3. 요청을 보낼 도구

curl은 연결성을 검증하기에 충분하고, Python(requests 사용)은 실제 통합을 구축하기에 충분합니다. 둘 다 벤더 전용 SDK가 필요 없습니다—이 API는 그저 HTTPS 위의 일반 JSON입니다.

연결성 확인

동영상을 생성하기 전에 먼저 가벼운 엔드포인트(예: 사용 가능한 모델 목록)를 호출하여 키가 유효하고 네트워크 경로가 정상인지 확인하세요. 그 단계에서 실패하면 디버깅 대상은 자격 증명이나 연결성이지 동영상 생성이 아닙니다—어느 쪽인지 파악하는 것만으로도 많은 시간을 절약할 수 있습니다.

빠른 체크리스트:

  • 키가 요청을 실행할 셸에 내보내져 있습니다.
  • 기본 URL이 기록되어 있고 일관되게 사용됩니다(스크립트 간에 끝 슬래시가 달라지지 않게).
  • 모든 POST에 Content-Type: application/json이 설정되어 있습니다.
  • 원시 JSON 응답을 잘리지 않고 볼 수 있는 방법이 있습니다.

텍스트-투-비디오 요청 보내기

성공 가능성이 있는 가장 작은 요청부터 시작하세요. 처음부터 모든 선택적 매개변수를 채우지 마세요—최소 요청이 실패하면 문제가 구조적임을 알 수 있고, 성공하면 이후 추가하는 매개변수마다 개별적으로 원인을 추적할 수 있는 변경이 됩니다.

최소 구조

텍스트-투-비디오 요청은 모델 ID와 프롬프트를 전송합니다:

{
  "model": "gemini-omni-flash/text-to-video",
  "prompt": "비에 젖은 네온 거리에서 천천히 다가가는 카메라, 젖은 아스팔트 위의 반사, 시네마틱"
}

이것이 전체 페이로드입니다. 이것을 전송하고 성공 응답 객체를 받는 것을 확인한 다음에야 내용을 풍부하게 만드세요.

요청을 단계적으로 발전시키기

최소 호출이 성공하면 한 번에 매개변수 하나씩 추가하고, 추가할 때마다 다시 검증하세요. 텍스트 경로에서 흔히 추가하는 항목:

  • 프롬프트 세부 사항 — 피사체, 움직임, 카메라 동작, 조명, 분위기. 모호한 프롬프트는 모호한 움직임을 낳습니다. 무엇이 움직이고 카메라가 어떻게 움직이는지 설명하세요.
  • 길이 / 출력 크기 — 동영상은 생성된 출력 기준으로 청구되므로 길이가 비용에 직접 영향을 줍니다. 아직 확인하지 않은 기본값에 의존하지 말고 명시적으로 고정하세요.
  • 가로세로 비율 또는 해상도(모델이 지원하는 경우)로 다운스트림 플레이어나 소셜 미디어 형식에 맞추세요.

정말 중요한 프롬프트 작성 요령

텍스트-투-비디오의 품질은 주로 프롬프트의 구체성에 의해 결정됩니다. 세 가지 좋은 습관:

  1. 내용만이 아니라 움직임을 설명하세요. "종이배가 배수로를 따라 흘러내려 간다"는 모델에게 애니메이션할 것을 줍니다. "종이배"는 아무것도 주지 않습니다.
  2. 카메라를 명시하세요. 고정, 팬, 돌리인, 핸드헬드—카메라 언어는 많은 모호함을 제거합니다.
  3. 하나의 장면으로 제한하세요. 짧은 단일 클립에서 여러 장면을 설명하면 종종 뭉개진 결과가 나옵니다.

텍스트-투-비디오 결과가 좋지 않으면 먼저 프롬프트를 바꾸고, 그 다음에 기술적 매개변수를 건드리세요.

이미지-투-비디오 요청 보내기

이미지 경로는 구조적으로 텍스트 경로와 동일하며 한 가지만 더 있습니다: 소스 이미지. 여기서도 배운 "최소 우선" 테스트 방법이 그대로 적용됩니다.

최소 구조

{
  "model": "gemini-omni-flash/image-to-video",
  "prompt": "부드러운 핸드헬드 드리프트, 피사체가 카메라 쪽으로 살짝 돌아봄, 부드러운 창가 빛",
  "image": "https://your-cdn.example.com/source-frame.jpg"
}

이때 프롬프트는 장면 내용이 아니라 이미지에 상대적인 움직임과 카메라 동작을 설명합니다—이미지가 이미 내용을 제공하기 때문입니다. 이것이 가장 흔한 개념적 실수입니다: 사람들은 전체 장면 설명을 쓰고 나서 출력이 소스 프레임을 무시하는 이유를 의아해합니다.

소스 이미지 제공 방법

이미지는 참조로 전달되며 서비스가 이를 가져올 수 있어야 합니다. 실질적인 결과가 두 가지 있습니다:

  • 리소스는 서비스에서 공개적으로 접근 가능해야 합니다, localhost, VPN, 인증이 필요한 버킷 뒤에 있으면 안 됩니다. 요청 실행 시점에 여전히 유효하다면 짧은 만료 시간의 서명 URL도 괜찮습니다.
  • 형식과 크기가 지원되어야 합니다. 일반적인 웹 형식과 합리적인 크기를 고수하세요. 40 MB TIFF는 디버깅을 기다리는 것과 같습니다.

이미지가 비공개 스토리지에 있다면 버킷을 공개로 설정하려 하지 말고 요청 시점에 짧은 만료 시간의 서명 URL을 생성하세요.

텍스트 경로와의 실제 차이

  • 프롬프트의 역할이 장면 설명에서 움직임 설명으로 바뀝니다.
  • 검증에 리소스 가져오기 단계가 하나 더 추가되어 완전히 새로운 종류의 실패가 생깁니다(디버깅 장 참조).
  • 출력 구성이 소스 이미지의 가로세로 비율에 의해 제약되며, 이는 다운스트림 레이아웃 계획에 영향을 줍니다.

먼저 브라우저에서 이미지 URL을 테스트하세요. 당신에게도 깔끔하게 로드되지 않는다면 서비스에도 마찬가지입니다.

curl과 Python으로 API 호출하기

동일한 요청이 두 곳에서 모두 작동하게 하세요: 터미널(빠른 반복과 원시 응답 확인용)과 코드베이스(실제 사용용).

curl

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-flash/text-to-video",
    "prompt": "비에 젖은 네온 거리에서 천천히 다가가는 카메라, 시네마틱"
  }'

model 문자열을 gemini-omni-flash/image-to-video로 바꾸고 image 필드를 추가하면 다른 엔드포인트로 전송됩니다—나머지는 바꿀 필요가 없습니다.

-sS를 사용하면 오류가 조용히 삼켜지지 않습니다. 응답을 확인할 때는 JSON 포매터로 파이프하여 중첩 필드를 읽을 수 있게 하세요.

Python

import os
import requests

BASE_URL = "https://api.hiapi.ai/v1/chat/completions"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}

payload = {
    "model": "gemini-omni-flash/text-to-video",
    "prompt": "비에 젖은 네온 거리에서 천천히 다가가는 카메라, 시네마틱",
}

resp = requests.post(BASE_URL, headers=HEADERS, json=payload, timeout=300)
resp.raise_for_status()
print(resp.json())

그대로 따라 할 만한 두 가지 세부 사항: 키를 환경 변수에서 읽고, 충분히 넉넉한 타임아웃을 설정하세요. 동영상 생성은 즉시 요청이 아닙니다—10초 기본 타임아웃은 API 오류처럼 보이지만 실제로는 클라이언트가 먼저 포기한 가짜 실패를 낳습니다.

이미지-투-비디오의 경우 한 줄을 추가하세요:

payload["model"] = "gemini-omni-flash/image-to-video"
payload["image"] = "https://your-cdn.example.com/source-frame.jpg"

2xx가 아닌 상태 코드를 만나면 예외를 발생시키기 전에 반드시 원시 응답 본문을 출력하거나 기록하세요. 오류 텍스트는 보통 문제가 있는 필드를 직접 지목합니다.

통합 코드 구성하기

두 경로가 각각 작동하게 되면 코드베이스에 거의 동일한 함수를 두 개 남기고 싶어지기 쉽습니다. 조금 더 나은 구조는 비용이 거의 들지 않고, 두 번째 동영상 모델을 추가하는 순간 원가를 회수합니다.

공유 컴포넌트 두 개

하나의 요청 빌더. 의도 수준 매개변수를 받아 페이로드 딕셔너리를 반환하는 함수:

def build_video_payload(prompt, image_url=None, duration=None):
    if image_url:
        payload = {
            "model": "gemini-omni-flash/image-to-video",
            "prompt": prompt,
            "image": image_url,
        }
    else:
        payload = {
            "model": "gemini-omni-flash/text-to-video",
            "prompt": prompt,
        }
    if duration:
        payload["duration"] = duration
    return payload

엔드포인트 선택은 "이미지가 있는가?"의 결과가 되며, 이는 실제 제품 결정과 일치합니다. 호출자는 모델 ID를 직접 다루지 않습니다.

하나의 응답 처리기. 전송 오류, 페이로드 오류, 모델 수준 실패를 분리해서 처리하고 정규화된 결과 객체(상태, 동영상 참조, 로그용 원시 응답 본문)를 반환하는 함수. 모든 호출자가 이를 거치므로 두 엔드포인트의 오류 의미가 일관됩니다.

이렇게 하는 것이 가치 있는 이유

  • 모델 ID를 한 곳에서만 바꾸면 됩니다. 다른 동영상 모델로 마이그레이션할 때 열다섯 개 호출 지점이 아니라 빌더만 편집하면 됩니다.
  • 일관된 오류 처리. 이미지 가져오기 실패와 프롬프트 검증 실패가 동일한 방식으로 UI에 표시됩니다.
  • 네트워크 없이 테스트 가능. 빌더는 순수 함수입니다. 페이로드 구조를 저비용으로 단위 테스트할 수 있습니다.
  • 청구 가시성. 동영상은 생성된 출력 기준으로 청구되므로 단일 처리기는 비용 추적을 위해 길이와 출력 크기를 기록하기에 자연스러운 위치입니다.

빌더는 가볍게 유지하세요. 무엇을 생성할지에 대한 비즈니스 로직은 호출자에게 속합니다. 빌더는 그 의도를 API의 형태로 표현하는 방법만 알면 됩니다.

흔한 요청 실패 디버깅

거의 모든 초기 실패는 세 가지 범주 중 하나에 속합니다. 먼저 범주를 파악하고, 그다음 수정하세요.

범주 1: 요청 구조

증상: 즉시 4xx 반환, 누락되었거나 알 수 없는 필드를 언급하는 오류 메시지, 또는 JSON 형식 오류 불평.

순서대로 확인:

  1. JSON이 유효한가? 요청 본문을 린터에 붙여넣으세요. 페이로드를 수동으로 편집하면서 남긴 후행 쉼표는 전형적인 문제입니다.
  2. 모델 ID가 정확히 일치하는가? gemini-omni-flash/text-to-video와 gemini-omni-flash-text-to-video는 같은 문자열이 아닙니다. 여기의 오타는 인증 문제처럼 읽히는 "모델을 찾을 수 없음" 오류를 낳습니다.
  3. 요청 헤더가 완전한가? Authorization과 Content-Type: application/json이 모두 설정되어 있습니다.
  4. 모델과 엔드포인트가 일치하는가? image 필드를 텍스트 엔드포인트로 보내면 원하는 결과를 얻지 못합니다—해당 필드는 거부되거나 무시되며, 어느 쪽이든 잘못된 결과를 얻게 됩니다.

범주 2: 입력 리소스(이미지 경로 전용)

증상: 요청은 수락되지만 처리 중에 실패하거나, 오류가 이미지 가져오기나 디코딩을 언급합니다.

확인:

  1. 쿠키가 없는 시크릿 브라우저 창에서 이미지 URL을 여세요. 로드되지 않는다면 서비스도 로드할 수 없습니다.
  2. URL이 localhost 주소, 사설 네트워크 호스트, 만료된 서명 링크가 아닌지 확인하세요.
  3. 형식이 일반적인 웹 형식이고 파일 크기가 합리적인지 확인하세요.
  4. 응답이 실제로 이미지인지 확인하세요—200 상태 코드를 반환하지만 내용은 HTML 오류 페이지인 CDN은 의외로 흔한 함정입니다.

범주 3: 모델 호출 자체

증상: 요청이 유효하고 리소스에 접근 가능하지만 생성이 실패하거나 거부됩니다—보통 콘텐츠 정책이나 용량과 관련됩니다.

확인:

  1. 최소 프롬프트로 줄이고 다시 시도하세요. 성공하면 프롬프트가 변수입니다.
  2. 클라이언트 타임아웃이 충분히 긴지 확인하세요—로그에서 클라이언트 타임아웃은 응답을 받았는지 확인하지 않는 한 서버 실패와 똑같이 보입니다.
  3. 전체 요청/응답 로그를 활성화하세요(키는 마스킹). 그러면 세 가지 문제 범주를 한눈에 구분할 수 있습니다.

효과적인 디버깅 순서

최소 페이로드 → 검증 → 이미지 추가 → 검증 → 선택적 매개변수 하나씩 추가 → 검증. 문제가 생기면 마지막으로 한 변경이 원인입니다. 한 번에 변수 하나만 디버깅한다는 원칙을 지키면 대부분의 통합 고통이 사라집니다.

각 엔드포인트의 최소 사용 가능한 호출에서 시작하고, 공유 빌더와 처리기로 감싼 다음 점진적으로 확장하세요—이 경로가 통합이 성장할 때 텍스트-투-비디오와 이미지-투-비디오를 모두 예측 가능하게 유지해 줍니다.

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

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

API 문서 보기