GPT Image 2.5 API 연동: 생성, 편집 및 Image 2 마이그레이션

HiAPI에서 GPT Image 2.5를 연동하려면 먼저 gpt-image-2.5-flare 또는 gpt-image-2.5-sunburst를 선택한 다음 POST /v1/tasks로 작업을 제출하세요. 두 모델 모두 생성과 편집을 지원하며, image_urls 전달 여부에 따라 요청에 참조 이미지가 포함되는지가 결정됩니다.

Image 2에서 마이그레이션할 때는 모델 이름과 입력 파라미터를 함께 수정해야 합니다. 이전 버전의 resolution, size, 참조 이미지 필드 및 라우트 설정은 규약이 다르므로, 모델 문자열만 교체하면 적용되지 않는 파라미터가 남기 쉽습니다.

다음 코드는 2026년 9월 9일 기준 HiAPI 온라인 문서에 따라 작성되었으며, 요청과 비동기 처리 흐름을 설명하기 위한 것입니다. 실제 출력과 비용은 작업 기록을 기준으로 합니다. 파라미터 업데이트는 Flare 문서와 Sunburst 문서를 기준으로 하세요.

하나의 모델 ID로 생성과 편집을 모두 지원

Flare와 Sunburst는 HiAPI에서 요청 필드가 동일합니다. 모델을 하나 선택한 후 순수 텍스트 생성 시에는 image_urls를 생략합니다. 편집 시에는 1–16장의 참조 이미지를 추가하고, 프롬프트에 수정할 내용과 유지할 내용을 명시하세요. 순수 텍스트 생성에 빈 배열을 보내지 말고, /edit 또는 /text-to-image 접미사를 직접 붙일 필요도 없습니다. 각 작업은 이미지 한 장을 출력합니다.

안정적인 이미지 워크플로가 이미 있다면 먼저 한 가지 작업 유형을 마이그레이션하고 기존 입력과 검수 기준을 유지하세요. 두 모델의 포지셔닝에 대해서는 먼저 Image 2와 2.5의 차이를 참고하세요. 이 글은 요청을 실제로 어떻게 적용하는지에 초점을 맞춥니다.

생성 요청 제출하기

아래 예시는 정사각형 컵 상품 이미지를 생성합니다. JSON을 request.json으로 저장하세요. quality는 이후 파라미터 재현을 위해 medium으로 명시하고, aspect_ratio는 문서에 나열된 픽셀 크기 1024x1024로 설정합니다.

{
  "model": "gpt-image-2.5-flare/text-to-image",
  "input": {
    "prompt": "A studio product photograph of a matte cobalt blue ceramic mug on a warm gray seamless background. Front three-quarter view, soft light from the left, subtle contact shadow, no text, no logo.",
    "aspect_ratio": "1024x1024",
    "quality": "medium",
    "background": "opaque",
    "output_format": "webp"
  }
}

API Key는 서버 환경 변수 HIAPI_API_KEY에 저장합니다. 다음 명령은 파일을 읽어 제출하고, 작업 생성 응답을 저장합니다. HIAPI_REQUEST_ID는 여러분의 애플리케이션이 이 논리적 요청에 대해 생성하는 값입니다. 동일한 요청을 네트워크 문제로 재시도할 때는 재사용하고, 입력을 수정하거나 다른 이미지를 생성할 때는 새 값을 사용하세요.

: "${HIAPI_API_KEY:?Set HIAPI_API_KEY on your server}"
: "${HIAPI_REQUEST_ID:?Set a unique ID for this logical request}"
curl --fail-with-body --silent --show-error \
  https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer ${HIAPI_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${HIAPI_REQUEST_ID}" \
  --data-binary @request.json \
  --output created.json

생성에 성공하면 created.json의 data.taskId에서 작업 ID를 읽습니다. 이 시점에 이미지는 여전히 비동기로 생성 중입니다. Idempotency-Key는 동일한 논리적 요청이 중복 제출로 여러 작업을 생성하는 것을 방지합니다. 전체 규약은 작업 생성 문서를 참고하세요. 제출 성공을 이미지 완료로 오해하지 마세요.

같은 인터페이스로 이미지 편집하기

아래는 독립적인 Sunburst 편집 요청입니다. image_urls의 자리 표시자 주소를 서비스에서 읽을 수 있는 실제 참조 이미지 URL로 교체한 후 request.json으로 저장하고, 새 요청 ID로 제출하세요. example.com 주소는 필드 구조를 설명하기 위한 것일 뿐이며, 직접 생성에 사용할 수 없습니다.

{
  "model": "gpt-image-2.5-sunburst/image-to-image",
  "input": {
    "prompt": "Change only the background behind the mug to pale peach. Preserve the mug shape, cobalt blue color, handle, camera angle, lighting direction, and contact shadow. Do not add text or objects.",
    "image_urls": ["https://example.com/your-mug-reference.webp"],
    "aspect_ratio": "1024x1024",
    "quality": "medium",
    "background": "opaque",
    "output_format": "webp"
  }
}

여러 참조 이미지는 배열 순서대로 용도를 설명합니다. 예를 들어 첫 번째는 상품을, 두 번째는 배경을 제공합니다. 연속 수정 시에는 이전 단계에서 저장한 출력을 다음 요청의 참조 이미지로 사용하세요. 매번 새로운 작업이므로 새로운 수정 요구 사항을 명확히 해야 합니다. 인터페이스가 이전 대화나 이미지를 자동으로 유지한다고 가정하지 마세요.

투명 배경은 background를 transparent로 설정하고 PNG 또는 WebP를 선택해야 합니다. JPEG는 투명 채널을 지원하지 않습니다. 모델 출력 후에도 가장자리와 피사체를 반드시 확인해야 하며, 필드 설정이 이미지 검수를 대체할 수 없습니다.

상태 조회 후 파일 저장하기

GET /v1/tasks/:id는 작업 상세 정보를 반환합니다. queued, handling, archiving은 모두 비종료 상태이며, success만 출력물 사용 가능을 의미합니다. fail은 data.error를 통해 실패 정보를 제공합니다. 외부 code: 200은 조회 성공만 의미하므로, 반드시 data.status를 계속 판단해야 합니다. 작업 상세 문서

다음 Python 예제는 requests를 사용하여 방금 생성된 created.json을 읽고, 처음 3초 대기 후 4초마다 조회합니다. 상세 JSON과 첫 번째 이미지를 저장합니다. 10분은 예제의 로컬 대기 한도이며, 서비스 SLA를 의미하지도 않고 서버 작업을 취소하지도 않습니다. 타임아웃 후에는 taskId를 유지하고 나중에 같은 작업을 계속 조회하세요.

import json
import os
import time
from pathlib import Path

import requests

created = json.loads(Path("created.json").read_text())
if created.get("code") != 200:
    raise RuntimeError(created)
task_id = created["data"]["taskId"]
headers = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}
deadline = time.monotonic() + 600
delay = 3

while time.monotonic() < deadline:
    time.sleep(delay)
    response = requests.get(
        f"https://api.hiapi.ai/v1/tasks/{task_id}",
        headers=headers, timeout=30,
    )
    if response.status_code == 503:
        delay = min(delay * 2, 30)
        continue
    response.raise_for_status()
    envelope = response.json()
    if envelope.get("code") != 200:
        raise RuntimeError(envelope)
    task = envelope["data"]
    Path("task-detail.json").write_text(json.dumps(envelope, indent=2))
    status = task["status"]
    if status == "fail":
        raise RuntimeError(task.get("error"))
    if status == "success":
        image = next(x for x in task["output"] if x["type"] == "image")
        # This example requested WebP. Do not forward the API key to the CDN.
        with requests.get(image["url"], stream=True, timeout=60) as result:
            result.raise_for_status()
            with Path("result.webp").open("wb") as output:
                for chunk in result.iter_content(1024 * 1024):
                    output.write(chunk)
        print("Saved result.webp", task_id)
        break
    if status not in {"queued", "handling", "archiving"}:
        raise RuntimeError(f"Unexpected status: {status}")
    delay = 4
else:
    raise TimeoutError(f"Resume polling this task later: {task_id}")

임시 출력물은 output[].expireAt 전에 다운로드하거나 전송해야 합니다. 프로덕션 서비스에서는 요청 최상위 레벨에 callback을 설정하여 최종 상태 알림을 받고, 폴링을 백업으로 유지할 수 있습니다. 콜백 필드는 input에 넣지 마세요. 콜백 서명 검증과 중복 알림 처리는 통합 비동기 API에 따라 구현하세요. 예제에는 비즈니스 큐, 콜백 서비스 또는 전체 네트워크 재시도 전략이 포함되어 있지 않습니다.

Image 2에서 마이그레이션: 입력 항목별 확인

이전 버전 Image 2는 라우트가 다르므로, 마이그레이션 시 현재 어떤 라우트를 사용 중인지 먼저 확인하세요. 아래는 HiAPI 문서 간의 파라미터 차이이며, 다른 제공업체의 SDK 요청을 그대로 변환하는 데는 적용되지 않습니다.

이전 워크플로	Image 2.5의 조정 사항
생성과 편집에 서로 다른 Image 2 모델 ID 사용	전체 Flare 또는 Sunburst ID로 변경하고, image_urls 유무로 구분
Standard 편집에서 input_urls 사용	image_urls로 변경. 이전 ext 편집은 이미 이 필드를 사용
Standard / ext에서 resolution 사용	목표 크기에 따라 aspect_ratio의 비율 또는 픽셀 열거형을 다시 선택하고, resolution은 유지하지 않음
Beta 생성에서 size 사용	문서에서 지원하는 aspect_ratio 픽셀 열거형으로 변경하고, 임의 크기를 그대로 복사하지 않음
명시적 route: "beta" / "ext" 또는 모델 이름에 라우트 접미사 포함	2.5 모델 문서에 따라 요청을 재구성하고, 이전 라우트를 답습하지 않음
이전 버전에서 지원하는 4:5 등의 비율	항목별 확인. 2.5 현재 열거형에는 4:5가 없으므로 조용히 다른 비율로 변경하지 말 것
기본 품질, 크기 또는 출력 형식에 의존	명시적으로 지정하고, 출력, 비용 및 다운스트림 파일 처리를 다시 확인

2.5의 현재 비율 옵션은 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16 및 auto입니다. 또한 aspect_ratio는 문서에 나열된 10개의 픽셀 크기를 허용합니다. 고정 크기가 필요하면 열거형 값을 선택하세요. 문자열 형식만 보고 임의의 widthxheight가 모두 사용 가능하다고 추론해서는 안 됩니다. 특히 auto는 새 문서에서 모델이 적합한 구도를 선택한다고 설명하므로, 이전 편집 라우트의 "입력 이미지 따르기" 가정을 그대로 상속해서는 안 됩니다.

품질 옵션은 low, medium, high, xhigh, max, auto이며, 기본값은 medium입니다. 동일한 이름의 품질 등급이 이전 모델과 동일한 비용이나 시각적 성능을 보장하지는 않습니다. 전체 이전 프로토콜은 Image 2 생성 및 Image 2 편집 문서를 참고하세요.

오류와 예산을 하나의 검수 체인에 통합하기

제출 시 400은 모델 이름, 필드 및 열거형을 확인하고, 402는 잔액을 확인하며, 415는 Content-Type을 확인하세요. 작업이 생성된 후 fail이 발생하면 data.error를 저장하여 조사하고, 동일한 잘못된 입력을 반복 제출하지 마세요. 503은 잠시 후 백오프 재시도할 수 있습니다. POST가 네트워크 중단으로 생성 여부를 확정할 수 없을 때는 원래의 멱등 키를 사용하여 중복 작업을 방지하세요. 작업 생성 오류 설명

비용 확인은 HiAPI 현재 가격 페이지와 각 모델 페이지에서 시작하세요. 마이그레이션 검수 시 전체 모델명, 크기, 품질, 참조 이미지 수, 요청, 출력 및 실제 청구서를 기록해야 하며, 이전 Image 2의 단가를 답습하거나 다른 플랫폼의 시작 가격을 HiAPI 견적으로 오해해서는 안 됩니다. 웹 페이지의 샘플 이미지는 효과 평가에 도움이 되지만, API 소요 시간과 청구서는 각각의 실제 기록이 필요합니다.

생성 작업 하나와 편집 작업 하나를 연동, 저장 및 검수한 후 배치 프로세스로 확장하세요. Flare 모델 페이지 또는 Sunburst 모델 페이지에서 현재 진입점을 확인한 후, 해당 Docs에 따라 파라미터를 유지 관리하세요.