튜토리얼

HiAPI API를 통한 imagen-4.0 사용 방법: curl, Python 및 사용 가능한 요청 예시

Nov 3, 2026

HiAPI가 제공하는 imagen-4.0 기능

imagen-4.0은 텍스트-이미지 생성 모델입니다. 자연어 프롬프트를 보내면 생성된 이미지를 반환합니다. 통합 개발자에게 진짜 중요한 것은 모델의 아키텍처가 아니라 그 주변의 인터페이스 계약입니다. HiAPI를 통해 그 계약은 하나의 HTTP 엔드포인트입니다. JSON을 받고 bearer 키로 인증하며, 이는 chat completion과 embedding 호출에서 이미 익숙한 패턴과 정확히 같습니다.

모델에 직접 연결하는 대신 HiAPI를 사용할 때의 실질적인 이점:

통일된 인증 방식. 동일한 API 키가 플랫폼의 모든 모델에 적용되므로 여러 제공업체의 자격 증명 사이를 오갈 필요가 없습니다.
통일된 요청 형식. 모델 식별자와 프롬프트를 담은 하나의 JSON 요청 본문. 특정 SDK의 요청 구조를 배울 필요가 없습니다.
동기 반환. imagen-4.0은 결과를 동일한 HTTP 응답에서 반환하므로 기본 시나리오에서는 폴링 루프나 webhook을 구축할 필요가 없습니다.

이 가이드는 curl과 Python으로 각각 하나의 동작하는 요청을 처음부터 구축하고, 그다음 응답을 읽는 방법과 프로덕션 환경에 배포하기 전에 무엇을 준비해야 하는지 설명합니다.

API 키 발급 및 인증 설정

HiAPI의 모든 imagen-4.0 호출은 bearer token으로 인증합니다. HiAPI 계정에서 API 키를 생성하면 이후 그 키가 요청에 필요한 유일한 자격 증명입니다. 별도의 프로젝트 ID도, 서명 헤더도 필요하지 않습니다.

대부분의 사고를 예방하는 원칙: 키는 환경 변수에 두고, 절대 소스 코드에 커밋하지 마세요. 스크립트에 붙여넣고 코드 저장소에 푸시한 키는 결국 교체해야 하는 키입니다.

로컬 설정

shell 세션에서 키를 export합니다:

export HIAPI_API_KEY="your-key-here"

변수를 지속적으로 유지하려면 이 줄을 shell 구성 파일에 추가하거나, .env 파일을 사용해 .gitignore에 포함하고 애플리케이션 시작 시 로드하세요.

배포 환경

CI와 프로덕션에서는 플랫폼의 시크릿 관리자를 통해 HIAPI_API_KEY를 설정하세요. 파일을 이미지에 굽는 대신 런타임에 환경 변수를 주입합니다. 이렇게 하면 애플리케이션 코드는 로컬과 배포 환경에서 완전히 동일하고, 변수의 출처만 달라집니다.

요청 헤더

모든 요청에 다음을 포함합니다:

Authorization: Bearer $HIAPI_API_KEY

401이 보이면 가장 먼저 확인할 것은 헤더가 실제로 전송되었는지, 그리고 변수가 비어 있지 않은 값으로 해석되었는지입니다. 변수를 export한 적 없는 shell은 평소처럼 Bearer 를 보내고 뒤에는 아무것도 없습니다.

보내기 전에 요청 구조 이해하기

imagen-4.0 요청 본문은 외워둘 수 있을 만큼 작으며, 이것이 핵심입니다. 구조를 이해하면 복사-붙여넣기 코드 조각을 번역하지 않고도 어떤 언어로든 요청을 구성할 수 있습니다.

최소한 다음을 전송해야 합니다:

{
  "model": "imagen-4.0",
  "prompt": "A weathered lighthouse on a cliff at dusk, long exposure, muted colors"
}

두 필드가 주요 역할을 합니다:

model은 어느 모델이 요청을 처리할지 식별합니다. 문자열이며, 플랫폼이 imagen-4.0을 나열하는 모든 곳에서 사용하는 동일한 식별자입니다. 잘못 작성하면 조용한 폴백이 아니라 오류 응답을 받습니다.
prompt는 원하는 이미지에 대한 설명입니다. 사람에게 장면을 묘사하듯 작성하세요. 주제, 장면, 스타일, 조명. 구체적인 프롬프트가 한 단어 프롬프트보다 더 예측 가능한 결과를 냅니다.

요청은 POST 방식, Content-Type: application/json으로 플랫폼의 이미지 생성 엔드포인트로 전송됩니다. 모델에 추가 선택적 매개변수가 있을 수 있지만, 위의 두 필드 요청 본문은 완전하고 유효한 요청입니다. 여기서 시작하고 필요할 때만 옵션을 추가하세요.

요청 본문이 순수 JSON이므로 curl, Python, Node 및 HTTP 클라이언트가 있는 모든 도구는 동등한 일급 시민입니다. 다음 두 섹션에서는 동일한 요청을 작성하는 두 가지 방법을 보여줍니다.

사용 가능한 curl 요청

터미널에서 시작하면 모든 파싱 간섭 없이 원시 응답을 볼 수 있습니다.

curl -sS -X POST "$HIAPI_BASE_URL/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0",
    "prompt": "A weathered lighthouse on a cliff at dusk, long exposure, muted colors"
  }'

줄별 설명:

-sS는 진행 표시줄을 숨기되 오류는 표시하므로 출력이 읽기 쉬우면서도 실패를 숨기지 않습니다.
-X POST는 요청 메서드를 설정합니다. 이미지 생성은 콘텐츠를 만들므로 POST입니다.
URL은 기본 URL에 경로를 더한 플랫폼의 이미지 생성 엔드포인트입니다. 기본 URL을 변수에 저장하면 동일한 명령을 여러 환경에서 사용할 수 있습니다.
첫 번째 헤더는 앞서 export한 환경 변수에서 읽은 bearer 키를 전달합니다.
Content-Type: application/json은 서버에 요청 본문을 어떻게 파싱할지 알려줍니다.
-d는 JSON 본문을 제공합니다. 작은따옴표는 shell이 중괄호와 따옴표를 해석하지 않도록 하며, 그 안의 JSON은 그대로 전달됩니다.

출력을 검사하려면 JSON 포맷 도구로 처리하세요:

curl -sS -X POST "$HIAPI_BASE_URL/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"imagen-4.0","prompt":"A weathered lighthouse on a cliff at dusk"}' \
  | python -m json.tool

응답에 이미지 참조가 포함되어 있다면 요청이 성공한 것입니다. 다음 섹션에서는 이를 애플리케이션 코드로 전환합니다.

Python으로 동일한 요청 작성하기

curl 호출은 그대로 변환할 수 있습니다. 유일한 실질적 선택은 HTTP 클라이언트입니다. 표준 라이브러리 urllib은 어디서나 사용 가능하지만, requests는 코드가 더 짧고 대부분의 코드베이스가 이미 의존하는 라이브러리입니다.

재사용 가능한 헬퍼 함수

import os
import requests

HIAPI_BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai/v1")


def generate_image(prompt: str, model: str = "imagen-4.0") -> dict:
    api_key = os.environ["HIAPI_API_KEY"]
    response = requests.post(
        f"{HIAPI_BASE_URL}/images/generations",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json={"model": model, "prompt": prompt},
        timeout=120,
    )
    response.raise_for_status()
    return response.json()


result = generate_image("A weathered lighthouse on a cliff at dusk")
print(result)

주목할 점 세 가지:

os.environ["HIAPI_API_KEY"]는 변수가 없을 때 즉시 KeyError를 발생시켜 빈 token을 보내는 대신 빠르고 명확하게 실패합니다.
json=는 딕셔너리를 자동으로 직렬화하고 콘텐츠 유형을 설정하므로 요청 동작이 curl 버전과 완전히 일치합니다.
timeout=120은 호출 시간을 제한합니다. 이미지 생성은 텍스트 완성보다 오래 걸리므로 기본 무제한 대신 넉넉한 시간 제한을 사용합니다.

이 함수는 프롬프트를 인수로 받아 파싱된 JSON을 반환하므로, 코드의 나머지 부분은 HTTP 세부 사항을 다룰 필요가 없습니다. 무언가에 연결하기 전에 REPL에서 테스트하세요.

동기 응답 읽기 및 오류 처리

imagen-4.0은 동기적으로 응답합니다. 생성된 이미지는 동일한 HTTP 응답 본문에서 반환됩니다. 기본 시나리오에서는 폴링할 작업 ID도, 작성할 폴링 루프도 없습니다. 이 호출을 다른 요청-응답 상호작용과 동일하게 취급하세요.

반환되는 내용

성공 응답은 JSON 객체입니다. Python에서는 response.json()으로 파싱하거나 curl 출력을 JSON 포맷 도구로 처리한 뒤, 반환 구조에서 이미지 데이터를 찾으세요. 일반적으로 URL 또는 인코딩된 이미지 페이로드, 그리고 생성에 관한 메타데이터입니다. 실제 응답에서 정확한 필드명을 한 번 읽고 그에 맞춰 코드를 작성하세요.

대비해야 할 문제

호출을 래핑하고 파싱 전에 상태를 확인하세요:

try:
    result = generate_image("A weathered lighthouse on a cliff at dusk")
except requests.HTTPError as e:
    print("HTTP error:", e.response.status_code, e.response.text)
except requests.Timeout:
    print("Request timed out")

명시적으로 처리할 가치가 있는 실패 모드:

401 — 키가 없거나 유효하지 않음. 코드가 아니라 환경 변수를 수정하세요.
일반적인 4xx — 요청 본문 형식 오류, 모델 식별자 오류 또는 프롬프트 거부. 응답 본문이 보통 어느 것인지 설명합니다. 로그에 기록하세요.
5xx — 서버 측 장애. 백오프를 통해 재시도할 가치가 있습니다.
시간 초과 — 성공이 아니라 결과 미확인으로 취급하세요. 이미지가 생성되었다고 가정하지 마세요.

실패 시 항상 상태 코드와 잘린 응답 본문을 기록하세요. 이 정보 없이 디버깅하는 것은 추측입니다.

첫 요청에서 프로덕션 환경으로

요청이 동작합니다. 규모를 확장하기 전에 다음 항목을 하나씩 점검하세요:

구성. 기본 URL과 API 키는 모두 환경에서 가져옵니다. 소스 코드에 리터럴이 없고 이미지에 키가 없습니다.
시간 초과. 모든 이미지 호출에 시간 제한이 있습니다. 시간 제한이 없으면 정체된 요청이 작업자를 무기한 점유할 수 있습니다.
재시도. 5xx와 시간 초과에만 재시도하고, 지수 백오프에 상한을 두세요. 401이나 요청 본문 형식 오류 4xx는 절대 재시도하지 마세요. 동일한 방식으로 실패합니다.
로깅. 각 호출의 모델, 프롬프트 길이, 상태 코드, 지연 시간을 기록하세요. 키를 기록하지 말고, 프롬프트에 사용자 데이터가 포함될 수 있다면 전체 프롬프트도 기록하지 마세요.
비용 인식. 이미지 생성은 생성된 출력으로 과금되므로 사용자당 또는 작업당 얼마나 많은 이미지가 요청되었는지 추적하고 애플리케이션 계층에서 상한을 설정하세요. 현재 요율은 이 가이드가 아니라 플랫폼의 가격 패널을 참조하세요.
동시성. 이미지 호출은 텍스트 호출보다 느립니다. chat-completion 지연 시간을 가정하지 말고 이를 기준으로 작업자 풀 크기를 설정하세요.

이것들이 준비되면 동일한 generate_image 헬퍼 함수가 수정 없이 배치 작업, 사용자 대상 기능, 내부 도구에 사용될 수 있습니다. 더 많은 통합 세부 사항은 플랫폼 문서를 참조하세요.

모든 아티클 보기 →