HiAPI
Ko
블로그

튜토리얼

GPT Image 2.5 Sunburst 텍스트-이미지 API: 바로 사용 가능한 curl 및 Python 가이드

Sep 12, 2026
GPT Image 2.5 Sunburst 텍스트-이미지 API: 바로 사용 가능한 curl 및 Python 가이드

hiapi API로 gpt-image-2.5-sunburst/text-to-image를 사용해 이미지를 생성하려는 경우, 이 가이드에서 curl과 Python을 각각 사용하여 작업 생성부터 최종 이미지 URL 다운로드까지 완전하고 실행 가능한 요청을 안내합니다. 여기에 표시된 모든 요청/응답은 게시 전에 실제 라이브 API에서 실행한 것입니다.

사전 요구 사항

  • hiapi 계정과 API key(sk-...)가 필요합니다. hiapi 콘솔에서 확인할 수 있습니다.
  • curl, 또는 Python 예제를 따라 하려면 Python 3.8+가 필요합니다.
  • 최소 한 장의 출력 이미지에 대한 예산이 필요합니다. gpt-image-2.5-sunburst/text-to-image는 출력 해상도 기준으로 과금되며——프로덕션 환경에서 실행하기 전에 현재 가격을 확인하세요. 요율이 변경될 수 있습니다.

모든 요청은 표준 요청 헤더를 사용합니다:

Authorization: Bearer sk-your-api-key-here
Content-Type: application/json

최소 동작 예제

hiapi의 이미지 모델은 모두 동일한 비동기 작업 API에서 실행됩니다. POST로 작업을 생성한 다음 종료 상태에 도달할 때까지 폴링하거나(또는 webhook 콜백을 받은 후) output[0].url에서 이미지 URL을 읽습니다.

1. 작업 생성(curl)

curl -s -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "input": {
      "prompt": "대리석 카운터 위에 놓인 세라믹 커피 드리퍼의 미니멀한 제품 사진, 부드러운 아침 빛, 35mm 렌즈 느낌",
      "resolution": "2K",
      "aspect_ratio": "4:3",
      "background": "auto"
    }
  }'

호출이 성공하면 작업 ID만 반환됩니다——생성은 비동기로 진행됩니다:

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

2. 결과 폴링

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

몇 초 간격으로 계속 폴링하여 data.status가 종료 상태 값이 될 때까지 기다립니다. 성공 시 응답은 다음과 같습니다(taskId/URL은 가독성을 위해 축약됨):

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01ABCDEF...",
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "status": "success",
    "storage": "temp",
    "created": 1789144334,
    "completed": 1789144407,
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/.../output-0.png",
        "artifactId": "146251",
        "expireAt": 1789749206
      }
    ]
  },
  "message": "success"
}

data.output[0].url에서 이미지를 가져옵니다. 해당 URL은 만료됩니다(expireAt, Unix 타임스탬프 참조)——작업이 성공하면 즉시 바이트를 다운로드하여 직접 저장하고, 영구 링크로 취급하지 마세요.

3. Python 엔드투엔드 예제

import time
import requests

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


def create_task(prompt: str, resolution: str = "1K", aspect_ratio: str = "1:1") -> str:
    payload = {
        "model": "gpt-image-2.5-sunburst/text-to-image",
        "input": {
            "prompt": prompt,
            "resolution": resolution,
            "aspect_ratio": aspect_ratio,
        },
    }
    resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_task(task_id: str, timeout_s: int = 300, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {task.get('error')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} did not finish within {timeout_s}s")


if __name__ == "__main__":
    task_id = create_task("대리석 카운터 위에 놓인 세라믹 커피 드리퍼의 미니멀한 제품 사진")
    task = wait_for_task(task_id)
    image_url = task["output"][0]["url"]
    print(f"Done: {image_url}")

    img_bytes = requests.get(image_url, timeout=60).content
    with open("output.png", "wb") as f:
        f.write(img_bytes)

input이 실제로 허용하는 필드

gpt-image-2.5-sunburst/text-to-image의 schema는 작고 엄격합니다. 다음 필드만 허용하며——그 외 다른 필드(quality, size, n, output_format, style, seed)는 400으로 거부됩니다:

필드 필수 값
prompt 예 임의의 문자열
resolution 아니요(기본값 1K) 1K, 2K, 4K
aspect_ratio 아니요 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
background 아니요 transparent, opaque, auto

이는 기본 gpt-image-2.5-sunburst 모델과 schema가 다릅니다. 후자는 quality 등급(low/medium/high/xhigh/max/auto)을 허용하고 image_urls를 통한 이미지-이미지 편집을 지원합니다. 가격도 다르므로——구체적인 숫자에 의존하기 전에 /en/pricing에서 확인하세요. 요율이 변경될 수 있습니다.

프로덕션 환경 패턴

폴링 대신 Webhook 콜백 사용

빠른 스크립트를 넘어서는 모든 상황에서는 폴링을 건너뛰고 hiapi가 작업 완료 시 콜백하도록 하세요. 동일한 POST /v1/tasks 요청에 최상위 callback 객체를 추가합니다:

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

when: "final"은 현재 유일하게 지원되는 값입니다——작업이 종료 상태(success 또는 fail)에 도달하면 엔드포인트가 한 번 호출되며, 페이로드 구조는 폴링으로 얻는 결과와 동일합니다.

폴링 vs. 콜백: 폴링은 스크립트나 notebook에서 더 쉽게 올바르게 구현할 수 있고 공인 엔드포인트가 필요 없지만, 요청을 낭비하고 완료를 알게 되기까지 지연(평균적으로 폴링 간격)이 추가됩니다. 서버 측 통합이나 동시성이 높은 모든 시나리오에서는 콜백이 더 적합합니다——폴링 루프를 완전히 피하고 작업이 완료되는 즉시 알림을 받습니다.

재시도 시 멱등성

작업 API는 model/input/callback과 나란히 최상위 idempotency_key 문자열을 허용합니다. 클라이언트가 타임아웃 후 POST를 재시도할 수 있는 경우(요청을 보냈지만 응답을 받지 못함), 안정적인 키를 첨부하면 원래 요청이 실제로 도달했는지 추측하는 대신 확인할 수 있는 명확한 신호를 얻게 됩니다.

오류 처리

유효하지 않거나 만료된 API key는 HTTP 401과 구조화된 오류 본문을 반환합니다:

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

잘못된 input 값(잘못된 열거형 멤버, prompt 누락, 지원되지 않는 필드)은 작업 생성 전에 HTTP 400을 반환하므로——과금되지 않습니다:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: prompt: missing required field \"prompt\""}

이 두 가지 경우를 명시적으로 확인하세요. 일시적인 네트워크/5xx 오류는 재시도하되, 400은 요청 본문을 수정하라는 신호로 간주하고 맹목적으로 재시도하지 마세요.

관련 리소스

자주 묻는 질문

resolution을 지정해야 하나요? 아니요——생략하면 기본값은 1K입니다. 2K 또는 4K 출력이 필요하면 명시적으로 설정하세요. 가격이 해상도에 따라 올라가기 때문입니다.

다른 GPT Image 모델 문서처럼 quality를 전달할 수 있나요? 이 라우트에서는 불가능합니다. gpt-image-2.5-sunburst/text-to-image는 quality를 완전히 거부합니다——해당 파라미터는 schema와 가격이 다른 기본 gpt-image-2.5-sunburst 모델 ID에만 존재합니다.

왜 내 요청은 이미지를 직접 반환하지 않고 작업 ID를 반환하나요? hiapi의 모든 이미지 모델은 동일한 비동기 작업 API(POST /v1/tasks → 폴링 또는 콜백 → output[0].url)를 통해 실행되며, 기반 모델이 실제로 얼마나 빠른지와 무관합니다. 이 패턴에 맞춰 통합을 한 번 구축하면 이후 교체하는 모든 모델이 동일한 방식으로 작동합니다.

출력 URL을 제때 다운로드하지 않으면 어떻게 되나요? 만료됩니다——작업 응답의 expireAt 필드는 임시 URL이 작동을 멈추는 Unix 타임스탬프입니다. status가 success가 되면 즉시 직접 다운로드하여 바이트를 저장하세요.

이 모델로 이미지-이미지 편집을 할 수 있나요? /text-to-image 라우트에서는 불가능합니다. 이미지 편집에는 기본 gpt-image-2.5-sunburst 모델 ID를 사용하고 image_urls 입력 필드를 전달하세요——정확한 schema는 모델 페이지를 참조하세요.

직접 시도할 준비가 되셨나요? hiapi 콘솔에서 API key를 발급받고 위 Python 예제의 prompt를 교체하면 됩니다.

태그API 튜토리얼텍스트를 이미지로 변환

관련 글

모든 아티클 보기 →

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

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

API 문서 보기