튜토리얼

hiapi API로 gpt-image-2.5-sunburst 사용하기: curl, Python 및 사용 가능한 요청 예시

최소 요청, 전체 파라미터 레퍼런스, 그리고 프로덕션 배포 전에 반드시 갖춰야 할 callback/멱등성 패턴.

Sep 10, 2026

gpt-image-2.5-sunburst로 이미지를 생성하거나 편집하려면 프롬프트가 담긴 작업을 POST /v1/tasks에 제출한 다음, 작업이 완료될 때까지 GET /v1/tasks/<id>를 폴링(또는 콜백 수신)하고 data.output[0].url에서 이미지 URL을 읽으세요. 이 가이드는 최소 요청, 전체 파라미터 세트, 그리고 배포 전에 필요한 프로덕션 패턴(콜백, 멱등성, 오류 처리)을 다룹니다.

사전 요구사항

hiapi API 키가 필요합니다. 콘솔에서 생성하세요——모든 요청은 Authorization: Bearer sk-<your-key>로 인증합니다. 브라우저에서 무료로 호출할 수 있는 방법도, 키 없이 호출하는 방법도 없습니다. 아래의 모든 예시는 이미 키를 보유하고 있다고 가정합니다.

최소 동작 예시

gpt-image-2.5-sunburst/text-to-image는 input에 prompt만 있으면 됩니다. 종횡비 기본값은 auto, 해상도 기본값은 1K입니다.

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "input": {
      "prompt": "A minimalist product photo of a ceramic espresso cup on a marble counter, soft morning light"
    }
  }'

즉시 작업 id를 반환합니다:

{"code":200,"data":{"taskId":"tk-hiapi-01M23BC5FM0G4N3DN5Y31JF0NZ"},"message":"success"}

결과 폴링:

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01M23BC5FM0G4N3DN5Y31JF0NZ \
  -H "Authorization: Bearer sk-<your-key>"

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M23BC5FM0G4N3DN5Y31JF0NZ",
    "status": "success",
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "output": [
      {"type": "image", "url": "https://temp.hiapi.ai/.../output-0.webp", "expireAt": 1789571298}
    ]
  }
}

동일한 왕복 흐름의 Python 버전:

import time
import requests

API_KEY = "sk-<your-key>"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers=HEADERS,
    json={
        "model": "gpt-image-2.5-sunburst/text-to-image",
        "input": {"prompt": "A minimalist product photo of a ceramic espresso cup on a marble counter"},
    },
    timeout=30,
)
task_id = resp.json()["data"]["taskId"]

while True:
    poll = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()
    status = poll["data"]["status"]
    if status in ("success", "fail"):
        break
    time.sleep(2)

if status == "success":
    image_url = poll["data"]["output"][0]["url"]
    print(image_url)
else:
    print("task failed:", poll["data"])

data.output[0].url은 임시 저장소를 가리킵니다——응답에 expireAt(Unix 초)이 포함되어 있습니다. 해당 기한 전에 바이트를 다운로드하여 영구 보관하세요(자체 스토리지, S3, R2 등). 영구 링크로 취급하지 마세요.

전체 파라미터 레퍼런스

gpt-image-2.5-sunburst에는 두 가지 모델 id가 있습니다: 프롬프트 기반 생성용 gpt-image-2.5-sunburst/text-to-image와 참조 이미지 편집 또는 합성용 gpt-image-2.5-sunburst/image-to-image. 둘 다 동일한 필드를 받지만, image_urls는 image-to-image에서 필수이고 text-to-image에서는 사용하지 않습니다:

필드	타입	기본값	설명
`prompt`	string, 1–8000자	—	필수. 편집의 경우 무엇을 변경해야 하는지, 그리고 무엇이 반드시 그대로 유지되어야 하는지 설명하세요.
`image_urls`	URL 배열	—	image-to-image 전용, 필수, JPEG, PNG 또는 WebP 이미지 1–16장, 각 최대 20 메가픽셀 및 30 MB 이하. 공개적으로 다운로드 가능한 URL 또는 data URI여야 합니다.
`aspect_ratio`	열거형	`"auto"`	`auto`, `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `16:9`, `9:16`, `21:9`, `27:16`, `16:27`, `9:8`, `8:9`.
`resolution`	열거형	`"1K"`	`1K`, `2K`, `4K`. 가격이 이 값에 따라 결정됩니다.
`background`	열거형	없음	`transparent`, `opaque`, `auto`. `transparent`는 `1K`에서만 적용되며, 이때 알파 채널이 포함된 PNG를 반환합니다.

편집 예시——하나 이상의 참조 이미지를 전달하고 원하는 변경 사항만 설명하세요:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/image-to-image",
    "input": {
      "prompt": "Change only the ceramic cup color to matte black. Keep the marble counter, lighting, and camera angle exactly as-is.",
      "image_urls": ["https://your-storage.example.com/cup-original.webp"],
      "resolution": "2K"
    }
  }'

이 스키마는 엄격합니다(additionalProperties: false)——알 수 없는 필드는 거부되므로 다른 이미지 모델의 파라미터(예: size, strength, n)를 그대로 가져오지 마세요.

프로덕션 패턴

실제 백엔드에서는 폴링 대신 콜백을 사용하세요. callback 블록을 추가하면 폴링 루프를 건너뛸 수 있습니다:

{
  "model": "gpt-image-2.5-sunburst/text-to-image",
  "input": {"prompt": "..."},
  "callback": {"url": "https://your-server.example.com/hooks/hiapi", "when": "final"}
}

when: "final"은 작업이 종료 상태(success 또는 fail)에 도달할 때 정확히 한 번 트리거됩니다. 엔드포인트는 빠르게 2xx를 반환하고 실제 작업(출력 다운로드, 자체 데이터베이스 업데이트)은 비동기로 수행하세요——hiapi는 빠른 확인을 받지 못한 콜백을 재시도합니다.

재시도를 멱등하게 만드세요. 클라이언트 요청이 타임아웃되면 작업이 생성되었는지 확신할 수 없습니다. 생성 요청에 Idempotency-Key 헤더(최대 255바이트)를 보내고 재시도 시 동일한 키를 재사용하세요. 동일한 계정과 키에서는 작업이 하나만 생성되며, 재시도는 원래 taskId를 반환합니다. 이것이 없으면 동일한 프롬프트를 중복 처리할 때 두 번 과금됩니다.

실제로 마주하게 될 종료 상태를 처리하세요:

success — data.output[0].url을 읽고 제때 다운로드하세요(expireAt 준수).
fail — 재시도 전에 data.error를 확인하여 실패 원인을 파악하세요. 모든 실패를 무작정 재시도하지 마세요. 일부는 프롬프트 수준의 문제(예: 정책 위반)로, 그대로 재시도하면 여전히 실패합니다.
존재하지 않는 작업 id(오타, 만료)를 폴링하면 HTTP 404와 함께 {"code":404,"message":"task not found"}가 반환됩니다.

인증 실패는 작업 수준 오류가 아니라 HTTP 401입니다:

{"error":{"code":"permission_denied","message":"This API key is invalid...","request_id":"...","type":"hiapi_error"}}

작업이 실패했다고 단정하기 전에 오류 처리에서이 부분을 확인하세요——유효하지 않거나 폐기된 키는 작업 생성 단계에 아예 도달하지 못합니다.

자주 묻는 질문

gpt-image-2.5-sunburst는 이미지 편집을 지원하나요, 아니면 텍스트-투-이미지만 지원하나요? 둘 다 지원하며, 두 가지 모델 id로 구현됩니다. 편집 또는 합성에는 image_urls(1–16장의 참조 이미지)와 함께 gpt-image-2.5-sunburst/image-to-image를 사용하고, 텍스트만으로 생성하려면 gpt-image-2.5-sunburst/text-to-image를 사용하세요.

생략하는 대신 빈 image_urls 배열을 보내면 어떻게 되나요? 그렇게 하지 마세요. image-to-image에서 image_urls는 필수이며 최소 하나의 URL이 필요합니다. 순수 텍스트 생성에는 text-to-image 모델 id를 사용하세요.

이미지 한 장에 얼마인가요? resolution에 따라 다릅니다: 1K는 $0.05, 2K는 $0.08, 4K는 $0.12이며 text-to-image와 image-to-image가 동일합니다. 프로그래머의 날 프로모션 기간(2026년 11월 9일 00:00 UTC+8까지)에는 모든 등급에서 50% 할인이 적용되어 $0.025, $0.04, $0.06입니다. 규모를 확장하기 전에 모델 페이지에서 실시간 가격을 확인하세요.

종횡비 대신 고정 픽셀 크기를 얻을 수 있나요? 가능합니다——aspect_ratio는 16:9 같은 비율 문자열 외에도 1024x1024, 1536x1024, 3840x2160 같은 리터럴 크기를 받습니다.

작업을 폴링할 때 왜 404가 반환되나요? taskId에 오타가 있거나, 폴링하는 엔드포인트/리전에 해당 작업이 없는 경우입니다. 생성 응답에서 저장한 id를 다시 확인하세요——hiapi는 정상적인 폴링 시간 범위 내에서 작업 레코드를 조용히 만료시키지 않습니다.

API 키 없이 테스트용으로 호출할 수 있나요? 불가능합니다. 모든 /v1/tasks 요청에는 Authorization: Bearer sk-<key>가 필요하며, 익명 또는 브라우저 전용 모드는 없습니다.