HiAPI
블로그

튜토리얼

HiAPI API로 gemini-omni-1.1-flash 호출하는 방법: curl 및 Python 가이드

Nov 17, 2026
추상 건축 스타일 커버 이미지: 따뜻한 회색 콘크리트 평면이 비스듬히 비치는 햇빛 아래 교차하고, 슬레이트 블루 그림자와 가느다란 세이지색 이음새가 있습니다.
이 페이지에서

첫 요청 전에 준비해야 할 것

코드를 작성하기 전에 네 가지를 확인하세요. 각 항목이 디버깅 왕복 한 번씩을 줄여줍니다.

API 키

HiAPI에 대한 모든 요청은 API 키로 인증해야 합니다. 계정 콘솔에서 생성하고 소스 코드 관리에 들어가지 않도록 하세요. 아래 예제는 환경 변수에서 읽으므로 키가 셸 기록이나 커밋된 파일에 나타나지 않습니다:

export HIAPI_API_KEY="your_key_here"

기본 URL과 엔드포인트 경로

기본 URL은 모든 HiAPI 모델에서 동일하며, 모델 식별자만 바뀝니다. 엔드포인트 경로와 요청 메서드는 블로그 글에서 베끼지 말고 API 참고 문서에서 가져오세요. 경로에 버전이 붙어 있어 변경될 수 있기 때문입니다. 기본 URL은 클라이언트의 상수로 두어 나중에 변경 시 한 줄만 고치면 되도록 하세요.

모델 식별자

gemini-omni-1.1-flash는 문자열로 요청 페이로드에 전달됩니다. 정확히 복사하세요. 하이픈과 버전 접미사가 중요합니다. 철자를 틀리면 오류가 보통 라우팅 실패가 아니라 검증 실패로 나타나 혼란스러울 수 있습니다. 뒤의 디버깅 섹션을 참고하세요.

모델 페이지 즐겨찾기

gemini-omni-1.1-flash 모델 페이지는 어떤 매개변수가 있고, 어떤 값을 받으며, 응답 구조가 어떤지에 대한 권위 있는 출처입니다. 한 번 읽고 끝낼 것이 아니라 변경 전마다 확인하는 참고 자료로 삼으세요.

이 네 가지가 준비되면 호출할 수 있습니다.

curl로 최소 요청 보내기

가능한 한 작은 요청으로 시작하세요. 목적은 좋은 결과를 얻는 것이 아니라 키, 엔드포인트, 페이로드 구조가 서로 맞는다는 것을 증명하는 것입니다. 한 번 동작하면 이후 모든 변경은 점진적입니다.

curl -X POST "$HIAPI_BASE_URL/<endpoint-path>" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-1.1-flash",
    "input": {
      "prompt": "나무 탁자 위의 도자기 컵을 향해 카메라가 천천히 다가가며, 부드러운 아침 햇살"
    }
  }'

각 부분의 의미는 다음과 같습니다:

  • 메서드와 URL —— 호출은 API 참고 문서에서 가져온 엔드포인트 경로에 기본 URL을 앞에 붙인 곳으로 보내는 POST입니다.
  • Authorization 헤더 —— bearer 토큰을 담습니다. 여기서 변수가 누락되거나 비어 있는 것이 401의 가장 흔한 원인입니다.
  • Content-Type 헤더 —— application/json이어야 합니다. 없으면 서버가 요청 본문을 아예 파싱하지 않을 수 있습니다.
  • model —— 정확한 모델 식별자 문자열입니다.
  • input —— 생성 매개변수를 담는 객체입니다. 프롬프트가 여기에 들어가며, 해상도와 길이도 아래에서 설명하듯 여기에 추가합니다.

호출이 최종 출력이 아니라 작업 식별자나 수락 상태 응답을 반환한다면 정상입니다. 생성은 비동기입니다. 해당 식별자를 저장하세요. 폴링 단계에서 사용합니다.

같은 호출을 Python으로 옮기기

Python 버전은 완전히 동일한 JSON 요청 본문을 보내야 합니다. 페이로드를 일관되게 유지해야 이식이 신뢰할 만합니다. curl은 성공했는데 Python은 실패한다면 문제는 API에 대한 이해가 아니라 Python 코드에 있습니다.

import json
import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
ENDPOINT = f"{BASE_URL}/<endpoint-path>"

payload = {
    "model": "gemini-omni-1.1-flash",
    "input": {
        "prompt": "나무 탁자 위의 도자기 컵을 향해 카메라가 천천히 다가가며, 부드러운 아침 햇살"
    },
}

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

response = requests.post(ENDPOINT, headers=headers, data=json.dumps(payload), timeout=30)
response.raise_for_status()
print(response.json())

즉시 들일 만한 몇 가지 습관이 있습니다:

  • 상수로 URL을 구성하세요. 코드 곳곳에 문자열 연결을 흩뿌리지 마세요.
  • 명시적 타임아웃을 설정하세요. 설정하지 않으면 멈춘 요청이 워커 프로세스를 무한정 매달리게 할 수 있습니다.
  • raise_for_status()를 호출하세요. 그래야 오류 응답이 조용히 성공 응답 본문으로 파싱되지 않고 예외로 드러납니다.
  • json.dumps로 직렬화하세요. 폼 인코딩에 의존하지 마세요. 폼 인코딩은 중첩된 input 객체를 올바르게 생성하지 못합니다.

동작하면 재사용 가능한 요청 구조가 생긴 것입니다. 다음 두 섹션에서는 출력을 실제로 제어하는 매개변수를 추가합니다.

요청에서 해상도와 길이 구성하기

해상도와 길이는 프롬프트와 나란히 input 객체 안의 일반 필드입니다. 개념상 페이로드는 다음과 같습니다:

{
  "model": "gemini-omni-1.1-flash",
  "input": {
    "prompt": "...",
    "resolution": "<supported-value>",
    "duration": "<supported-value>"
  }
}

핵심 규칙: 기억이나 몇 달 전 읽은 튜토리얼에 의존해 이 값들을 하드코딩하지 마세요. 지원 값은 모델 업데이트에 따라 바뀌며, 지원되지 않는 값을 전달하면 페이로드 오류처럼 보이는 검증 오류가 발생합니다. 설정 전에 항상 모델 페이지에서 현재 허용되는 값을 확인하세요.

실용적인 패턴

값을 코드가 아니라 설정에 두세요:

payload = {
    "model": "gemini-omni-1.1-flash",
    "input": {
        "prompt": prompt,
        "resolution": settings.resolution,
        "duration": settings.duration,
    },
}

이것은 세 가지 이점을 줍니다. 로직을 바꾸지 않고 출력 품질을 조정할 수 있습니다. 개발 중에는 저렴한 저해상도 테스트를 돌리고 최종 렌더링에서만 품질을 높일 수 있습니다. 플랫폼이 지원 값을 추가하면 코드베이스를 뒤지지 않고 설정 필드 하나만 고치면 됩니다.

더 미묘한 함정 두 가지도 짚을 만합니다. 첫째, 해상도와 길이는 보통 비용과 연관됩니다. 과금은 보통 산출물에 연동되므로 더 길고 고해상도인 클립은 무료가 아닙니다. 둘째, 어떤 필드가 선택 사항이라면 빈 문자열이나 null을 보내지 말고 생략하세요. 일부 검증기는 필드 자체가 선택 사항이어도 명시적 null을 거부합니다.

비동기 생성 처리: 먼저 제출, 그다음 폴링

생성에는 시간이 걸리므로 API는 제출 후 폴링 패턴을 사용합니다. 클라이언트는 이 둘을 재시도 의미가 다른 두 개의 독립 작업으로 다뤄야 합니다.

1단계: 제출

제출 호출은 이미 구성한 요청입니다. 작업 식별자를 반환하며, 엔드포인트에 따라 작업 ID, task ID 또는 유사한 필드일 수 있습니다. 방어적으로 파싱하세요:

created = response.json()
job_id = created.get("id") or created.get("job_id")
if not job_id:
    raise RuntimeError(f"No job identifier in response: {created}")

2단계: 폴링

그다음 해당 식별자로 상태 엔드포인트를 폴링하여 작업이 종료 상태에 도달할 때까지 기다립니다. 견고한 루프에는 네 가지 특성이 있습니다: 최대 대기 시간, 백오프, 종료 상태 확인, 실패 확인.

import time

def wait_for_job(job_id, timeout=600, initial_delay=2, max_delay=30):
    deadline = time.time() + timeout
    delay = initial_delay
    while time.time() < deadline:
        status = fetch_status(job_id)          # GET on the status endpoint
        state = status.get("status")
        if state in ("succeeded", "completed"):
            return status
        if state in ("failed", "error", "cancelled"):
            raise RuntimeError(f"Job {job_id} ended in state {state}: {status}")
        time.sleep(delay)
        delay = min(delay * 2, max_delay)
    raise TimeoutError(f"Job {job_id} did not finish within {timeout}s")

이 세부 사항이 중요한 이유

  • 지수 백오프는 렌더링에 1분이 걸리고 여전히 대기 중인 작업에 상태 엔드포인트를 계속 두드리는 것을 막아줍니다.
  • 하드 데드라인은 멈춘 작업이 워커를 영원히 차단하지 않게 합니다. 타임아웃 시 작업 ID를 기록하여 수동으로 확인할 수 있게 하세요.
  • 명시적 종료 상태는 예상치 못한 상태에서 무한 루프에 빠지지 않게 해줍니다. 알 수 없는 상태는 “계속 대기”로 취급하되 로그를 한 번 남기세요.
  • 분리된 재시도 정책: 제출 호출 재시도는 중복 작업을 만들 수 있어 상태 호출 재시도보다 위험합니다. 폴링은 안심하고 재시도해도 됩니다. 제출은 명확한 전송 오류에만 재시도하세요.

일반적인 장애 패턴 진단하기

대부분의 장애는 몇 가지 유형으로 분류됩니다. 뒤의 증상이 앞의 문제에서 비롯되는 경우가 많으므로 이 순서로 확인하세요.

인증 오류

증상: 401 또는 403. 먼저 확인: 키가 실제로 프로세스가 실행되는 환경에 존재하는가? len(API_KEY)를 출력하면 변수 미설정으로 bearer 토큰이 비는 전형적인 경우를 잡을 수 있습니다. 그다음 요청 헤더 형식이 Bearer <key>이며 사이에 공백이 하나뿐인지, 키가 취소되었거나 다른 프로젝트로 한정되지 않았는지 확인하세요.

페이로드 형식 오류

증상: 400과 함께 요청 본문이나 누락된 필드에 대한 불만. 먼저 확인: 요청 본문을 동작하는 curl 요청과 비교하세요. 흔한 원인은 Content-Type: application/json 헤더 누락, JSON 대신 폼 인코딩 데이터 전송, API가 기대하는 중첩 대신 input 객체를 평평하게 보내기(또는 반대), 의도치 않은 타입 변환입니다. 숫자형 duration을 따옴표 붙은 문자열로 보내면 검증에 실패할 수 있습니다.

지원되지 않는 매개변수 값

증상: 400 또는 422와 함께 resolution이나 duration 같은 특정 필드를 지목. 먼저 확인: 현재 지원 값을 나열한 모델 페이지. 거의 항상 코드 결함이 아니라 오래된 하드코딩 값입니다. 예전에 동작하던 값이 이제 실패한다면 서비스 장애를 의심하기 전에 모델이 업데이트되었다고 가정하고 문서를 다시 읽으세요.

모델 식별자 철자 오류

증상: 프롬프트를 언급하지 않는 검증 오류 또는 not found 오류. 먼저 확인: model 문자열을 출력하고 문서와 문자 단위로 비교하세요. 끝에 붙은 공백 하나나 뒤집힌 버전 번호는 놓치기 쉽습니다.

타임아웃과 일시적 장애

증상: 연결 타임아웃, 429 또는 5xx 응답. 먼저 확인: 타임아웃을 설정했는가? 타임아웃을 추가한 뒤 429와 5xx에만 백오프가 있는 유한 재시도를 추가하세요. 429 이외의 4xx 오류는 재시도하지 마세요. 요청이 매번 같은 방식으로 실패하기 때문입니다. 긴 작업의 경우 최종 결과는 폴링으로 가져온다는 점을 기억하세요. 제출 호출 타임아웃이 생성 실패를 의미하지는 않습니다.

기술적으로 유효하지만 결과가 틀림

요청은 성공했지만 출력이 기대에 못 미칩니다. 이는 API 문제가 아니라 프롬프트 문제입니다. 피사체, 카메라 움직임, 조명, 리듬을 구체적으로 명시하고, 차이를 귀속시킬 수 있도록 한 번에 변수 하나만 바꾸세요.

재사용 가능한 클라이언트 함수로 캡슐화하기

캡슐화의 목표는 간단합니다. 비즈니스 로직에 모델 식별자, 매개변수 이름, 폴링 루프가 들어가지 않게 하는 것입니다. 모델 관련 세부 사항은 한곳에 모읍니다.

def generate_video(prompt, *, resolution=None, duration=None, timeout=600):
    payload = {
        "model": "gemini-omni-1.1-flash",
        "input": {"prompt": prompt},
    }
    if resolution is not None:
        payload["input"]["resolution"] = resolution
    if duration is not None:
        payload["input"]["duration"] = duration

    created = post_json(ENDPOINT, payload)
    job_id = created.get("id") or created.get("job_id")
    if not job_id:
        raise RuntimeError(f"No job identifier: {created}")

    return wait_for_job(job_id, timeout=timeout)

이것이 주는 것

  1. 모델 교체가 한 줄. 더 새로운 모델이 나오면 상수와 기본 매개변수를 바꾸면 됩니다. 호출 지점은 영향을 받지 않습니다.
  2. 선택 매개변수가 올바르게 처리됩니다. 생략된 값은 전송되지 않아 앞서 설명한 null 거부 문제를 피합니다.
  3. 폴링이 호출자에게 보이지 않습니다. 호출자는 결과를 받거나 예외를 받으며, 직접 관리해야 할 작업 ID를 받는 일은 없습니다.
  4. 테스트가 쉬워집니다. post_json과 wait_for_job을 각각 스텁 처리하여 페이로드 구성과 폴링 로직을 격리해 테스트할 수 있습니다.

계층으로 나누기

구조를 평평하고 명확하게 유지하세요: 전송 계층(HTTP, 헤더, 타임아웃, 재시도), 모델 계층(gemini-omni-1.1-flash의 페이로드 구성), 작업 계층(제출과 폴링). 단일 generate_video 함수가 이들을 조합하며, 각 계층은 문제 발생 시 추론하기 쉽도록 충분히 작습니다.

먼저 curl로 연결 구성을 확인하고, 실제 작업은 Python으로 옮기며, 매개변수가 바뀔 때마다 모델 페이지를 읽고, 폴링 루프를 인터페이스 뒤에 두어 애플리케이션 코드로 절대 새어 나가지 않게 하세요.

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

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

API 문서 보기