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

gpt-image-2.5-flare@pro는 hiapi 통합 작업 API를 통해 제공되는 이미지 모델 중 하나입니다. 이 가이드에서는 먼저 curl과 Python으로 최소 실행 가능한 요청을 시연한 다음, 프로덕션 환경에 필요한 매개변수와 모드(콜백, 멱등성, 오류 처리)를 소개합니다.

준비물

• hiapi API 키. hiapi 콘솔에서 발급받을 수 있으며, 모든 키는 sk-로 시작합니다.
• 기본 URL로 https://api.hiapi.ai를 사용합니다. 모든 요청에는 Authorization: Bearer sk-<your-key> 헤더가 필요합니다.

hiapi에서의 이미지 생성(및 비디오, TTS, 음악 등 모든 비동기 모델)은 동일한 엔드포인트로 실행됩니다: POST /v1/tasks. 먼저 작업을 생성한 다음 GET /v1/tasks/:id를 폴링하거나, 작업 완료 시 콜백을 받을 수 있습니다. 전체 참고 자료: 통합 비동기 API.

최소 실행 예제

curl

작업 생성:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare@pro",
    "input": {
      "prompt": "a cyan glass data center entrance, cinematic lighting",
      "aspect_ratio": "16:9",
      "quality": "high",
      "output_format": "png"
    }
  }'

여기서 반환되는 것은 이미지가 아니라 작업 ID입니다. 이미지 생성은 비동기로 이루어집니다:

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

결과 폴링:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR \
  -H "Authorization: Bearer $HIAPI_API_KEY"

data.status는 queued → handling → archiving → success(또는 fail) 순서로 변합니다. 상태가 success이면 이미지는 data.output[0].url에 있습니다:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "gpt-image-2.5-flare@pro",
    "status": "success",
    "output": [
      { "url": "https://cdn.hiapi.ai/tasks/.../output.png", "type": "image", "expireAt": 1777886899 }
    ]
  }
}

expireAt은 Unix 타임스탬프입니다. 만료되기 전에 파일을 다운로드하거나 재호스팅하세요. 만료 후에는 해당 URL이 작동을 멈춥니다.

Python

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def create_image_task(prompt: str, aspect_ratio: str = "16:9", quality: str = "high") -> str:
    resp = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={
            "model": "gpt-image-2.5-flare@pro",
            "input": {
                "prompt": prompt,
                "aspect_ratio": aspect_ratio,
                "quality": quality,
                "output_format": "png",
            },
        },
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_task(task_id: str, timeout_s: int = 120, interval_s: int = 3) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        data = resp.json()["data"]
        if data["status"] in ("success", "fail"):
            return data
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} did not finish within {timeout_s}s")


if __name__ == "__main__":
    task_id = create_image_task("a cyan glass data center entrance, cinematic lighting")
    result = wait_for_task(task_id)
    if result["status"] == "success":
        image_url = result["output"][0]["url"]
        image_bytes = requests.get(image_url, timeout=30).content
        with open("output.png", "wb") as f:
            f.write(image_bytes)
        print(f"saved output.png from {image_url}")
    else:
        print("task failed:", result.get("error"))

유일한 의존성은 pip install requests로 설치하고, HIAPI_API_KEY를 내보낸 뒤 실행하면 됩니다.

주요 매개변수

gpt-image-2.5-flare는 두 가지 라우트를 제공합니다: 기본 라우트(모델 ID gpt-image-2.5-flare를 직접 사용)와 pro 라우트(@pro를 추가, 위의 모든 예제에서처럼). 명시적인 @default 접미사는 존재하지 않으며, 전달하면 MODEL_UNAVAILABLE이 반환됩니다.

input은 다음 필드를 받습니다:

• prompt(문자열, 필수) — 유일한 필수 필드입니다.
• aspect_ratio — 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, auto, 또는 1536x1024, 2048x2048, 3840x2160과 같은 명시적 픽셀 크기.
• quality — low, medium, high, xhigh, max 또는 auto.
• output_format — png, jpeg 또는 webp.
• background — auto, transparent 또는 opaque. output_format: png 또는 webp와 함께 transparent를 사용하면 누끼 소재를 얻을 수 있습니다.

스키마는 엄격합니다. 알 수 없는 필드(size, n 또는 나열되지 않은 모든 필드)는 조용히 무시되지 않고 400 INVALID_REQUEST와 additional properties '<field>' not allowed를 반환합니다. 빈 프롬프트에서 생성하는 대신 기존 이미지를 편집해야 한다면 hiapi는 이를 별도의 모델 ID로 제공합니다. 이미지 투 이미지 변형은 모델 페이지를 참고하세요.

프로덕션 환경 패턴

폴링 대신 콜백을 사용하세요. 생성 요청에 callback 객체를 추가합니다:

{
  "model": "gpt-image-2.5-flare@pro",
  "input": { "prompt": "..." },
  "callback": { "url": "https://yourapp.com/hooks/hiapi", "when": "final" }
}

when: "final"은 현재 유일하게 지원되는 값입니다. 작업이 success 또는 fail에 도달하면 hiapi가 귀하의 URL로 POST 요청을 한 번 전송합니다. 콜백 본문은 GET /v1/tasks/:id가 반환하는 data 필드와 완전히 동일합니다.

Idempotency-Key 헤더를 전송하세요. 귀하 측에서 요청이 타임아웃되어 재시도하는 경우, 멱등 키는 hiapi가 동일한 요청에 대해 두 번째 작업을 생성(및 과금)하는 것을 방지합니다.

오류를 명시적으로 처리하세요. 유효하지 않거나 취소된 키는 HTTP 401을 반환합니다:

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

형식이 잘못된 input은 HTTP 400과 함께 error_code: "INVALID_REQUEST" 및 문제 필드를 명시하는 message를 반환합니다. 재시도 전에 이를 확인하세요. 동일한 요청 본문으로 400을 재시도하면 다시 실패할 뿐입니다.

gpt-image-2.5-flare@pro의 가격(성공적으로 생성된 이미지 기준 과금, 해상도 및 품질 등급에 따라)은 가격 페이지를 참고하세요.

관련 문서

• 통합 비동기 API 참고 — 전체 작업 라이프사이클, 모든 모델 유형
• 작업 생성 — POST /v1/tasks의 요청/응답 구조
• 작업 세부 정보 조회 — GET /v1/tasks/:id 폴링
• 인증 — API 키 형식 및 헤더
• gpt-image-2.5-flare@pro 모델 페이지

자주 묻는 질문

기본 라우트와 @pro의 차이는 무엇인가요? 동일한 모델 제품군의 두 가지 독립적인 라우트로, 전송하는 모델 ID(gpt-image-2.5-flare 대 gpt-image-2.5-flare@pro)로 선택됩니다. 선택하기 전에 모델 페이지와 가격을 확인하여 현재의 비용 및 성능 차이를 파악하세요.

투명 PNG를 생성할 수 있나요? 네 — "background": "transparent"를 "output_format": "png"(또는 "webp")와 함께 설정하세요.

왜 additional properties 'size' not allowed가 반환되나요? 스키마가 엄격합니다. size 필드 대신 aspect_ratio를 사용하세요(aspect_ratio는 1024x1024와 같은 명시적 픽셀 크기도 받습니다).

출력 URL의 유효 기간은 얼마나 되나요? output[0] 객체의 expireAt Unix 타임스탬프까지입니다. 그 전에 다운로드하거나 자체 스토리지로 복사하세요. hiapi는 이후 해당 파일을 계속 제공하지 않습니다.

콜백을 설정했는데도 폴링이 필요한가요? 아니요, 하지만 여전히 폴링할 수 있습니다. 콜백 구성 여부와 관계없이 GET /v1/tasks/:id는 정상적으로 사용할 수 있으며, 콜백 엔드포인트가 전송을 놓친 경우 수동으로 재확인하는 데 유용합니다.

요청에 input_urls와 잘못된 prompt가 모두 포함되면 어떻게 되나요? 검증은 작업 생성 전에 전체 요청 본문에 대해 실행됩니다. 모든 유효하지 않은 필드(형식이 잘못된 미디어 배열 포함)는 400을 반환하며, 작업이 생성되지 않고(과금도 되지 않음) 않습니다.