HiAPI API로 gpt-image-2.5-sunburst/text-to-image를 호출하는 방법: curl과 Python

이 모델 엔드포인트가 제공하는 것

gpt-image-2.5-sunburst/text-to-image는 HiAPI의 통합 API를 통해 노출되는 이미지 생성 모델입니다. 모델 ID로 호출하며, 텍스트 모델과 동일한 chat-completions 형태의 요청 본문에 프롬프트를 담아 보내고, 응답에서 생성된 이미지 데이터를 받습니다.

실질적인 의미는 다음과 같습니다. 코드베이스가 이미 HiAPI를 통해 텍스트를 처리하고 있다면 두 번째 SDK도, 별도의 인증 방식도, 새로운 엔드포인트 계열을 배울 필요도 없습니다. 달라지는 것은 모델 ID 하나뿐입니다.

작업이 프롬프트에서 이미지로의 생성, 즉 텍스트 설명에 따라 새 이미지를 만들고 선택적으로 요청에 제공된 참조 이미지로 유도하는 것이라면 이 엔드포인트를 선택하세요. 기존 이미지를 생성이 아니라 분석하거나 설명해야 한다면 시각 능력을 갖춘 채팅 모델이 더 적합합니다. 이미지 생성은 이 엔드포인트에 맡기고, 이미지 이해는 다른 곳에 두세요.

미리 하나만 기대치를 정해 두세요. 이미지 호출은 텍스트 완성보다 느립니다. 응답 시간이 한 자릿수 초에 달하는 것은 정상이며, 클라이언트 타임아웃은 순수 텍스트 설정에서 물려받지 말고 이 현실에 맞게 조정해야 합니다.

첫 요청을 보내기 전에

세 가지를 준비해야 합니다.

API 키

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

export HIAPI_API_KEY="your-key-here"

정확한 모델 ID

문자열은 gpt-image-2.5-sunburst/text-to-image입니다. 불투명 식별자로 취급하세요. 복사하고 기억에 의존해 다시 입력하지 마세요. 슬래시는 ID의 일부입니다. 여기서의 오타는 첫 호출 실패의 가장 흔한 원인이며, 페이로드 문제가 아니라 모델을 찾을 수 없다는 식의 오류로 나타납니다.

HTTPS 요청을 보낼 수 있는 클라이언트

첫 검증에는 대부분의 시스템에 기본 설치된 curl만 있으면 됩니다. 애플리케이션 코드에는 requests 라이브러리가 있는 Python(또는 아무 HTTP 클라이언트)이면 충분합니다. 이 엔드포인트는 클라이언트에 별도의 이미지 라이브러리를 요구하지 않습니다. JSON을 보내고 JSON을 돌려받을 뿐입니다.

첫 순수 텍스트 호출 전에 이미지를 미리 업로드하거나 스토리지를 구성할 필요는 없습니다. 아래의 최소 요청으로 시작하고, 기본 왕복이 동작한 뒤에만 참조 이미지를 추가하세요.

curl을 사용한 최소 동작 요청

최소한의 올바른 호출은 다음과 같습니다:

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "messages": [
      {
        "role": "user",
        "content": "A sunlit coastal cliff at golden hour, wide angle, high detail"
      }
    ]
  }'

필드별 설명:

• URL — 표준 HiAPI chat-completions 경로입니다. 이미지 모델은 텍스트 모델과 같은 라우팅을 사용합니다.
• Authorization — API 키가 담긴 bearer 토큰입니다. 이 헤더 형식이 잘못되면 모델 호출 전에 401을 받습니다.
• Content-Type — 반드시 application/json이어야 합니다.
• model — 이전 섹션의 정확한 모델 ID입니다.
• messages — 표준 role/content 객체 배열입니다. 프롬프트는 user 메시지의 content입니다.

성공하면 생성된 이미지 데이터와 일반적인 완성 메타데이터가 담긴 JSON 응답을 받습니다. 먼저 원시 응답을 파일로 저장하고, 확인한 후 파싱 로직을 스크립트에 연결하세요:

curl -sS ... -o response.json

이것이 이미지를 반환하면 자격 증명과 페이로드 형태가 올바른 것이며, 이후의 모든 문제는 구성이 아니라 애플리케이션 로직의 문제입니다.

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

요청 규약은 그대로입니다. 달라지는 것은 클라이언트 설정, 타임아웃, 응답 처리뿐입니다.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/chat/completions"

payload = {
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "messages": [
        {
            "role": "user",
            "content": "A sunlit coastal cliff at golden hour, wide angle, high detail",
        }
    ],
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=(10, 180),  # connect, read
)

response.raise_for_status()
data = response.json()
print(data)

주목할 세 가지 세부 사항:

타임아웃은 명시적이고 비대칭적

튜플 (10, 180)은 짧은 연결 타임아웃과 넉넉한 읽기 타임아웃을 설정합니다. 이미지 생성은 원래 시간이 걸립니다. 텍스트 클라이언트에서 복사한 단일 평면 타임아웃은 거짓 실패를 만들어냅니다. 연결 타임아웃은 네트워크 문제가 빠르게 실패하도록 짧게 유지하세요.

data=가 아닌 json=payload 사용

딕셔너리를 json=으로 전달하면 직렬화를 처리하고 콘텐츠 타입을 설정합니다. 미리 직렬화한 문자열을 data=로 전달한다면 헤더를 직접 설정하세요.

방어적 파싱

응답은 JSON입니다. 인덱싱 전에 예상치 못한 형태라면 전체 응답 본문을 기록하세요. 실제 응답을 보기 전에 고정된 중첩 깊이를 가정하지 말고, 2xx가 아닌 상태에서 성공 형태를 절대 가정하지 마세요.

HiAPI용으로 구성된 클라이언트 라이브러리를 선호한다면 전송되는 페이로드는 완전히 동일합니다. 호출 위치만 바뀝니다.

참조 이미지를 올바르게 전달하기

참조 이미지는 최상위 임시 필드가 아니라 메시지 콘텐츠 내부에 제공해야 합니다. 이는 통합에서 가장 미묘하게 틀리기 쉬운 부분입니다. 형식이 잘못된 참조는 보통 오류를 내지 않기 때문입니다. 요청은 그냥 성공하고 출력은 이미지를 무시합니다.

언어 간 페이로드 구조를 일관되게 유지하세요. user 메시지가 콘텐츠 배열을 가지며, 그중 텍스트 부분이 프롬프트를 담고 이미지 부분이 참조 데이터를 담습니다. Python에서 구성한 동일한 JSON 요청 본문이 curl에서 바이트 단위로 표현될 수 있어야 합니다. Python 페이로드의 curl 등가물을 작성할 수 없다면 구조가 이미 어긋난 것입니다.

결과가 참조 이미지를 무시하는 것처럼 보일 때 다음 순서로 확인하세요:

1. 위치. 이미지 부분이 messages[].content 내부에 있는가, 아니면 요청 본문 최상위로 새어 나갔는가? 모델은 메시지 안에 있는 것만 볼 수 있습니다.
2. 인코딩. 참조 이미지는 인코딩된 데이터 형태로 요청에서 전송됩니다. 데이터가 수동 연결이나 잘못된 복사 붙여넣기로 잘리지 않고 완전하고 올바른 형식인지 확인하세요.
3. 프롬프트 결합. 참조 이미지는 생성을 유도할 뿐 지시를 대체하지 않습니다. 모델이 추론할 것이라 가정하지 말고 이미지가 맡는 역할(스타일, 구도, 피사체)을 명확히 설명하세요.
4. 크기. 매우 큰 참조는 요청을 부풀리고 왕복을 느리게 합니다. 인코딩 전에 작업에 실제로 필요한 크기로 줄이세요.

실용적인 디버깅 습관

참조 이미지 페이로드를 한 번 구성하고, 동작하는 정확한 JSON 요청 본문을 저장해 고정 샘플로 재사용하세요. 이후 호출이 이상하면 현재 요청 본문을 고정 샘플과 비교(diff)하세요. 대부분의 참조 이미지 회귀는 구조적이므로 diff로 몇 초 만에 찾을 수 있습니다.

오류, 타임아웃, 재시도 처리

이미지 엔드포인트는 텍스트 엔드포인트와 다르게 실패합니다. 더 느리기 때문에 더 많은 호출이 타임아웃이 발생하는 구간에 들어가고, 작업이 더 무거워서 무작정 재시도하는 비용이 더 큽니다.

클라이언트 오류와 일시적 실패 구분

• 4xx(429 제외) — 페이로드 형식 오류, 잘못된 모델 ID, 인증 누락. 같은 요청을 재시도하면 똑같이 실패합니다. 요청을 고치세요.
• 401/403 — 자격 증명 문제. 키와 Authorization 헤더 형식을 확인하세요.
• 429 — 속도 제한에 걸림. 재시도하되 즉시 재시도하지 말고 백오프와 지터를 사용하세요.
• 5xx 및 연결 오류 — 일시적입니다. 재시도하세요.
• 읽기 타임아웃 — 모호합니다. 생성이 서버 측에서 이미 완료되었을 수 있습니다. 워크플로가 중복 가능성을 감수할 수 있을 때만 타임아웃을 재시도 가능으로 취급하세요.

안전한 경우에만 재시도

지터가 있는 지수 백오프를 사용하고 시도 횟수에 작은 상한을 두세요. 보통 세 번이면 충분합니다. 간단한 패턴:

import time, random

def post_with_retry(session, url, payload, attempts=3):
    for i in range(attempts):
        try:
            r = session.post(url, json=payload, timeout=(10, 180))
            if r.status_code == 429 or r.status_code >= 500:
                raise RuntimeError(f"retryable: {r.status_code}")
            r.raise_for_status()
            return r.json()
        except (RuntimeError, requests.ConnectionError, requests.Timeout):
            if i == attempts - 1:
                raise
            time.sleep((2 ** i) + random.random())

이 루프 안에서 4xx 페이로드 오류를 재시도하지 마세요. 즉시 드러내어 잘못된 요청이 조용히 시도 횟수를 낭비하지 않고 크게 실패하게 하세요.

모델에 맞게 타임아웃 크기 조정

이미지 호출에 설정하는 읽기 타임아웃은 텍스트 기본값의 몇 배여야 하며, 전역이 아니라 호출별로 설정해 텍스트 트래픽이 불이익을 받지 않게 하세요. 플랫폼에 하드 요청 상한이 있다면 생성 프롬프트와 참조 이미지를 실제로 감당할 수 있는 예산 안으로 유지하세요.

배포 전 프로덕션 체크리스트

대부분의 사고를 예방하는 간단한 체크리스트:

• 모델 ID는 한 곳에. gpt-image-2.5-sunburst/text-to-image를 흩어진 문자열 리터럴이 아니라 상수나 구성 값으로 정의하세요.
• 키는 환경 변수에서 가져오고 절대 커밋하지 마세요. 다른 비밀 정보처럼 교체(rotate)하세요.
• 명시적 타임아웃과 넉넉한 읽기 창을 세션 기본값이 아니라 요청에 설정하세요.
• 429/5xx/타임아웃에서만 재시도하고, 백오프와 지터를 사용하며 시도 횟수를 제한하세요.
• 실패 시 전체 응답 기록 — 파싱 전에 상태, 응답 본문, 요청 ID를 기록해 지원 대화가 증거에서 시작되게 하세요.
• 동작하는 페이로드 고정 샘플 저장 — 일반적인 경우와 참조 이미지 경우를 모두 포함하고, 동작이 바뀔 때 diff에 사용하세요.
• 참조 이미지는 메시지 콘텐츠 내부에, 작업에 맞게 축소하고, 프롬프트에 그 역할을 명시하세요.
• CI의 스모크 테스트 — 모델 ID로 실제 호출을 한 번 수행해, 이름이 바뀌거나 폐기된 모델이 사용자 발견 전에 드러나게 하세요.

이 습관들은 이미지 생성에만 국한된 것이 아니지만, 각각은 이미지 호출이 텍스트 호출보다 더 자주 만나는 실패 모드를 겨냥합니다. 한 번 제대로 갖춰 두면 엔드포인트는 기술 스택의 다른 부분처럼 동작합니다. 모델의 현재 파라미터와 제한에 대해서는 구성을 확정하기 전에 HiAPI의 모델 페이지를 확인하세요.