hiapi API로 gpt-image-2.5-sunburst@pro 사용하는 방법: curl, Python 및 실행 가능한 요청 예제

gpt-image-2.5-sunburst@pro는 hiapi의 gpt-image-2.5-sunburst 모델의 Pro 라우트입니다. 이 가이드는 모델 id가 정확히 무엇인지, 어떤 input 필드를 정확히 받는지, 바로 실행 가능한 curl/Python 예제, 그리고 무인 운영 전에 필요한 프로덕션 패턴(멱등성, 콜백, 오류 처리)까지 처음부터 실행 가능한 요청 하나로 안내합니다.

먼저 준비해야 할 것

• hiapi 계정과 콘솔에서 발급한 API key. 아래 모든 요청은 Authorization: Bearer sk-<your key>로 인증합니다.
• 그게 전부입니다 — 별도 SDK 설치가 필요 없습니다. hiapi의 모든 모델은 동일한 비동기 작업 엔드포인트로 호출되므로, 다른 hiapi 모델을 호출해 본 적이 있다면 이 요청 구조도 익숙할 것입니다.

이 모델의 특유한 점 하나: @pro는 라우트 접미사이지 별칭이 아닙니다. hiapi는 일부 모델에 둘 이상의 호출 모드를 노출하며, gpt-image-2.5-sunburst도 그중 하나입니다 — 일반 모델 id와 @pro 접미사가 붙은 id는 서로 다른 input 필드를 받고 서로 다른 가격 등급으로 청구됩니다. 이 가이드는 gpt-image-2.5-sunburst@pro만 다룹니다; 맨 gpt-image-2.5-sunburst id를 사용하면 다른 모드, 다른 스키마를 얻게 됩니다(FAQ 참조).

최소 실행 예제

hiapi의 모든 생성 모델 — 이미지, 비디오, 오디오 — 은 동일한 통합 엔드포인트로 호출됩니다: POST /v1/tasks. model과 input을 제출하면 즉시 taskId를 받고 생성은 비동기로 실행됩니다.

gpt-image-2.5-sunburst@pro의 input은 다음을 받습니다:

필드	타입	필수 여부	설명
prompt	string	예	1–32,000자
image_urls	string[]	아니오	공개 JPEG/PNG/WebP URL 1–16개; 포함하면 텍스트-이미지 대신 이미지-이미지로 동작(SVG 미지원)
aspect_ratio	enum	아니오	예: 1:1, 16:9, 9:16, 또는 1536x1024 같은 명시적 크기; 기본값 1:1
quality	enum	아니오	low / medium / high / xhigh / max / auto; 기본값 medium — 올리기 전에 아래 프로덕션 주의사항을 먼저 보세요
background	enum	아니오	transparent, opaque 또는 auto; 기본값 auto
output_format	enum	아니오	png, jpeg 또는 webp; 기본값 webp

curl

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sunburst-pro-demo-001" \
  -d '{
    "model": "gpt-image-2.5-sunburst@pro",
    "input": {
      "prompt": "밝은 나무 테이블 위 세라믹 핸드드립 커피 드리퍼의 미니멀 제품 사진, 부드러운 스튜디오 조명",
      "aspect_ratio": "1:1",
      "quality": "medium",
      "output_format": "webp"
    }
  }'

이렇게 하면 즉시 taskId가 반환됩니다:

{ "code": 0, "message": "ok", "data": { "taskId": "task_xxxxxxxx" } }

그런 다음 결과를 폴링합니다:

curl -s "https://api.hiapi.ai/v1/tasks/task_xxxxxxxx" \
  -H "Authorization: Bearer sk-YOUR_API_KEY"

data.status가 success가 되면 이미지는 data.output[0].url에 있습니다. 즉시 다운로드하세요 — 이 URL에는 expireAt이 있어 영구 외부 링크로 사용할 수 없습니다.

Python

import time
import requests

API_KEY = "sk-YOUR_API_KEY"
BASE = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def submit_task():
    payload = {
        "model": "gpt-image-2.5-sunburst@pro",
        "input": {
            "prompt": "밝은 나무 테이블 위 세라믹 핸드드립 커피 드리퍼의 미니멀 제품 사진, "
                      "부드러운 스튜디오 조명",
            "aspect_ratio": "1:1",
            "quality": "medium",
            "output_format": "webp",
        },
    }
    r = requests.post(
        f"{BASE}/tasks",
        headers={**HEADERS, "Idempotency-Key": "sunburst-pro-demo-001"},
        json=payload,
        timeout=30,
    )
    r.raise_for_status()
    return r.json()["data"]["taskId"]

def poll_task(task_id, timeout_s=180, interval_s=3):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{BASE}/tasks/{task_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task failed: {data.get('error')}")
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

if __name__ == "__main__":
    task_id = submit_task()
    image_url = poll_task(task_id)
    print("image ready:", image_url)

프로덕션 패턴

폴링과 콜백. 위의 루프는 스크립트와 저트래픽 사용에는 문제없습니다. 서버 측 시나리오라면 폴링보다 콜백을 선호하세요: 같은 요청에 callback 객체를 추가합니다 —

{
  "model": "gpt-image-2.5-sunburst@pro",
  "input": { "...": "..." },
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" }
}

callback.url은 HTTPS여야 하며, when: "final"(현재 유일하게 지원되는 값)은 성공과 실패 시 각각 한 번 알려줍니다 — 폴링 루프도, 낭비되는 요청도 없습니다. hiapi는 콜백을 여러 번 전송할 수 있으므로 수신 측에서 taskId로 중복 제거하세요.

멱등성. POST /v1/tasks에 Idempotency-Key 헤더(최대 255바이트의 임의 문자열, 예: 주문 id)를 추가하세요. 네트워크 타임아웃으로 클라이언트가 같은 제출을 재시도하면 플랫폼은 두 번째 작업을 생성 — 및 과금 — 하는 대신 원래 taskId를 반환합니다(응답 헤더에 Idempotent-Replay: true). 이 key는 계정 범위이며 24시간 후 만료됩니다; 다른 요청 본문으로 재사용하면 조용히 새 작업을 만드는 대신 422 IDEMPOTENCY_KEY_MISMATCH를 반환하므로, 불일치는 맹목적으로 재시도하지 말고 재시도 로직을 점검하라는 신호입니다.

인증 오류. 형식이 잘못되었거나 잘못된 API key는 작업 생성 이전에 401과 permission_denied 오류 코드로 빠르게 실패합니다:

{
  "error": {
    "code": "permission_denied",
    "message": "This API key is invalid. Check that it is correct or use another API key and try again.",
    "type": "hiapi_error"
  }
}

이것이 보인다면 원인은 거의 항상 key 자체(환경 변수 오타, key 만료, sk- 접두사 누락)이지 요청 본문이 아닙니다. key를 고치기 전까지는 재시도 불가로 취급하세요.

quality에 관하여. quality 기본값은 medium이며 이는 합리적인 기본 출시 값입니다 — 올리면 비용과 생성 시간이 함께 늘어나므로, 주어진 prompt가 해당 등급에서도 안정적으로 성공함을 자체 테스트에서 확인한 뒤에만 high/xhigh/max로 올리세요.

관련 페이지

• gpt-image-2.5-sunburst 모델 페이지 — 이 모델 계열의 기능, 예시 출력 및 모든 사용 가능한 모드.
• 통합 비동기 API 문서 — 모든 hiapi 생성 모델이 공유하는 전체 /v1/tasks 계약(멱등성, 콜백, 상태 코드).
• 인증 문서 — API key 생성 및 관리 방법.
• gpt-image-2.5-sunburst API 가이드 — 기본(@pro 아님) 모드를 원한다면 이 글에서 독립적인 resolution 기반 스키마를 자세히 설명합니다.
• 가격 — 현재 quality 등급별 이미지당 비용.

FAQ

gpt-image-2.5-sunburst@pro와 gpt-image-2.5-sunburst는 다른 모델인가요? 같은 모델 계열의 다른 라우트입니다. 맨 gpt-image-2.5-sunburst id(및 그 /text-to-image 모드)는 resolution 필드(1K/2K/4K)를 받고 quality나 image_urls 필드는 없습니다. @pro는 이를 quality 등급으로 바꾸고 선택적 image_urls를 추가하므로, 같은 호출에서 품질 등급을 제어하거나 이미지-이미지를 하려면 이 라우트를 사용하세요.

참조 이미지가 필요한가요? 아니요. 텍스트-이미지일 때는 image_urls를 완전히 생략하세요. 공개 이미지 URL을 1–16개 포함하면 참조 이미지로 출력을 조건화합니다.

API key 없이 이 모델을 사용할 수 있나요? 아니요 — 모든 요청에는 계정의 실제 hiapi API key와 함께 유효한 Authorization: Bearer 헤더가 필요합니다. 미인증 또는 key 없는 등급은 없습니다.

비용은 얼마인가요? 가격은 quality 등급에 따라 달라지며 여기 반복하지 않고 가격 페이지에 최신 상태로 유지됩니다 — 규모별 비용을 추정하기 전에 확인하세요.

콜백이 계속 오지 않으면 어떻게 하나요? 콜백 전송은 즉시성을 보장하지 않으며 hiapi가 전송을 재시도할 수 있습니다(따라서 taskId로 중복 제거하세요). 하드 상한이 필요하면 콜백을 무한히 기다리지 말고 타임아웃 후 GET /v1/tasks/:id에 대한 폴백 폴링을 유지하세요.

제출 시 오류 대신 fail 상태가 나오는 이유는 무엇인가요? 제출(200/taskId 반환)은 요청이 수락되었다는 것만 의미합니다 — 생성 자체는 여전히 비동기로 실패할 수 있습니다. 폴링 후 또는 콜백으로 data.status를 확인하고, 재제출 전에 data.error에서 원인을 확인하세요.