hiapi API로 gpt-image-2-beta 사용하는 방법: 파라미터, 코드 및 실행 가능한 예제

gpt-image-2-beta는 hiapi에서 GPT Image 2에 접근하는 초간단 고정 가격 경로입니다. 입력 필드 두 개, 가격 하나, 가로세로 비율이나 품질 조정 항목은 없습니다. 이 가이드에서는 최소 실행 예제, 정확한 파라미터 구조(실제 엔드포인트를 프로브하여 확인) 및 기본 gpt-image-2/text-to-image 경로와 비교했을 때의 차이를 보여주어, 언제 어떤 것을 사용해야 할지 판단할 수 있게 합니다.

사전 준비

hiapi 대시보드의 API Keys 페이지에서 API 키를 발급받아야 합니다. 키는 sk-로 시작합니다. 현재 단일 이미지 가격은 gpt-image-2-beta 모델 페이지와 가격 페이지에서 확인하세요.

hiapi의 모든 이미지 모델과 마찬가지로, 이 모델은 통합 비동기 작업 엔드포인트에서 실행됩니다:

• POST https://api.hiapi.ai/v1/tasks — 생성 작업 생성
• GET https://api.hiapi.ai/v1/tasks/{taskId} — 작업 상태 폴링

beta 경로의 차이점

gpt-image-2/text-to-image(기본 경로)는 aspect_ratio + resolution을 받고 해상도 등급에 따라 가격이 책정됩니다(1K는 $0.03, 최대 4K는 $0.06). gpt-image-2-beta는 이 모든 것을 이미지당 고정 가격 $0.02와 선택적 size 필드 하나로 축소했습니다. size는 "1024x1024" 또는 "1600x900"과 같은 리터럴 픽셀 크기 문자열이며, 비율이 아닙니다. size를 완전히 생략하면 모델은 자체 기본 출력 크기로 폴백합니다.

대가는 세밀한 비율/해상도 제어를 포기하고 더 낮고 단순한 가격을 얻는 것입니다. 정확한 구도가 중요하지 않고 "저렴하게 이미지 한 장 생성"만 필요할 때 적합합니다.

최소 실행 예제(curl)

# 1. Create the task
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-beta",
    "input": {
      "prompt": "a paper airplane launching off a stack of documents, flat vector illustration",
      "size": "1024x1024"
    }
  }'
# => {"code":200,"data":{"taskId":"tk-hiapi-01..."},"message":"success"}

# 2. Poll until status == "success"
TASK_ID="tk-hiapi-01..."
curl -s "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-YOUR_KEY"
# => {"code":200,"data":{"status":"success","output":[{"url":"https://..."}], ...}}

완성된 이미지는 data.output[0].url에 있습니다. 이 URL은 expireAt 유효 기간이 짧으므로 즉시 다운로드하여 자체 스토리지에 다시 호스팅하세요. 프로덕션 콘텐츠에 직접 링크하지 마세요.

위 curl 호출(다른 프롬프트 사용)로 생성된 예시 이미지, size: "1024x1024" 사용.

Python: 생성 + 폴링 + 디스크에 저장

import os
import time
import requests  # pip install requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]  # sk-...

def create_task(prompt: str, size: str | None = None) -> str:
    input_fields = {"prompt": prompt}
    if size:
        input_fields["size"] = size  # e.g. "1024x1024", "1600x900"
    r = requests.post(
        API_BASE,
        json={"model": "gpt-image-2-beta", "input": input_fields},
        headers={"Authorization": f"Bearer {TOKEN}"},
        timeout=60,
    )
    r.raise_for_status()
    body = r.json()
    if body.get("code") != 200:
        raise RuntimeError(f"create failed: {body}")
    return body["data"]["taskId"]

def wait_task(task_id: str, timeout_s: int = 300, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API_BASE}/{task_id}",
                          headers={"Authorization": f"Bearer {TOKEN}"}, timeout=30)
        r.raise_for_status()
        task = r.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

def save_image(url: str, path: str) -> None:
    resp = requests.get(url, timeout=60)
    resp.raise_for_status()
    with open(path, "wb") as f:
        f.write(resp.content)

if __name__ == "__main__":
    tid = create_task("a red panda mascot reading a book, flat pastel illustration", size="1024x1024")
    task = wait_task(tid)
    save_image(task["output"][0]["url"], "output.jpg")
    print("saved output.jpg")

파라미터 참고

gpt-image-2-beta의 input 객체는 두 필드만 받습니다. 이 구조는 additionalProperties: false이므로 다른 어떤 내용이든 조용히 무시되는 대신 즉시 거부됩니다.

필드	타입	필수 여부	설명
prompt	string	예	생성할 이미지의 텍스트 설명.
size	string	아니오	리터럴 픽셀 크기, 예: "1024x1024", "1600x900". 가로세로 비율 키워드가 아닙니다. 생략하면 모델의 기본 출력 크기를 사용합니다.

지원하지 않는 항목(및 받게 되는 오류)

beta 구조는 기본 gpt-image-2/text-to-image 경로나 OpenAI Images API에서 사용하는 어떤 필드도 받지 않습니다. 즉 aspect_ratio, resolution, quality, background, moderation, output_format, output_compression, n, user 또는 style입니다. 이 중 하나라도 보내면 즉시 HTTP 400이 반환됩니다. 예:

{
  "code": 400,
  "data": null,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: <root>: additional properties 'quality', 'aspect_ratio' not allowed"
}

기본 경로나 OpenAI의 Images API에서 코드를 마이그레이션하는 경우, 먼저 prompt + size로 축소한 다음 gpt-image-2-beta를 가리키세요.

가격: beta vs 기본 vs @ext

경로	가격	제어 항목
gpt-image-2-beta	$0.02/이미지 고정	size(픽셀 크기)만
gpt-image-2/text-to-image(기본)	$0.03(1K) / $0.04(2K) / $0.06(4K)	aspect_ratio + resolution
gpt-image-2/text-to-image@ext	$0.007–$0.76, 품질 × 해상도 기준	16가지 가로세로 비율, 품질 등급

프로덕션에서 경로를 결정하기 전에 가격 페이지를 확인하세요. 특정 모델의 가격은 언제든지 변경될 수 있습니다.

beta 경로에서 구축하기 위한 팁

• 위 필드 목록을 영구 계약이 아닌 현재 계약으로 취급하세요. beta 경로의 구조나 가격은 기본 경로보다 조정될 가능성이 높으므로, 프로덕션에서 의존한다면 정기적으로 모델 페이지를 다시 확인하세요.
• size는 선택 사항이므로, 레이아웃이 특정 크기에 의존한다면 항상 명시적으로 전달하세요. 현재 기본값이 그대로 유지된다고 가정하지 마세요.
• status: "fail"은 다른 hiapi 이미지 모델과 동일하게 처리하세요. task.error.code / task.error.message를 읽고, 모든 실패가 일시적이라고 가정하는 대신 백오프 재시도하세요.

자주 묻는 질문

gpt-image-2-beta와 gpt-image-2/text-to-image는 같은 모델인가요? 기반은 동일한 GPT Image 2 모델이지만 API 경로가 다릅니다. beta 경로는 파라미터 제어를 고정된 더 낮은 가격과 교환합니다.

특정 가로세로 비율을 요청할 수 있나요? 직접 요청할 수 없습니다. aspect_ratio 열거형 대신 원하는 가로:세로 비율에 맞는 size 문자열을 선택하세요(예: 16:9는 "1600x900").

size를 전혀 전달하지 않으면 어떻게 되나요? 작업은 여전히 성공합니다. 모델은 자체 기본 출력 크기를 사용합니다.

관련 문서

가로세로 비율과 해상도를 명시적으로 제어하는 전체 기능 경로는 hiapi API로 gpt-image-2/text-to-image 사용하는 방법을 참조하세요. 직접 시도해 볼 준비가 되셨나요? API Keys 페이지에서 키를 발급받고 위 curl 예제를 실행하세요.