gpt-image-2.5 API (Flare 및 Sunburst)를 curl, Python, Node로 사용하는 방법

OpenAI는 2026년 9월 8일 ChatGPT Images 2.5를 출시했으며, 두 가지 새로운 API 모델인 gpt-image-2.5-flare와 gpt-image-2.5-sunburst를 함께 선보였습니다. 두 모델 모두 gpt-image-2와 동일한 엔드포인트 뒤에 있으므로, 저희의 gpt-image-2 API 가이드를 따랐다면 대부분의 코드가 모델 ID 교체 후에도 작동할 것입니다. 변경된 점은 품질 단계와 Responses API가 도구 호출당 모델을 선택할 수 있도록 하는 방식입니다.

이 가이드는 개발자 경로만을 다룹니다: 생성, 참조 이미지 및 마스크를 사용한 멀티파트 편집, Responses API 도구, 스트리밍, 그리고 실제 비용을 위한 usage 읽기입니다. 이번 릴리스가 ChatGPT 사용자에게 어떤 의미인지 알아보려면 저희의 ChatGPT Images 2.5 개요를 읽어보세요; OpenAI 출시 게시물에는 제품 프레이밍이 설명되어 있습니다. 아래의 모든 수치는 2026년 9월 9일에 확인된 OpenAI 문서, 가격 페이지 또는 계산기에서 가져온 것입니다.

gpt-image-2.5 API 한눈에 보기

항목	값 (OpenAI 문서)
모델 ID	`gpt-image-2.5-flare`, `gpt-image-2.5-sunburst` (스냅샷 `-2026-09-08`)
엔드포인트	`POST /v1/images/generations`, `POST /v1/images/edits`, Responses API `image_generation` 도구
입력 / 출력	텍스트와 이미지 입력, 이미지 단독 출력
품질	`low`, `medium`, `high`, `xhigh`, `max`, `auto` (기본값). `xhigh`와 `max`는 새로 추가됨
크기	`1024x1024`, `1536x1024`, `1024x1536` 권장; 16의 배수로 사용자 지정 크기, 가로세로 비율 1:3 ~ 3:1, 최대 4K 총 픽셀
출력	`data[].b64_json`; `output_format` `png`, `jpeg`, `webp`; `background: "transparent"`는 png 또는 webp 필요
스트리밍	`partial_images` 0-3, 각 부분은 100개의 추가 출력 토큰 비용 발생
가격 (두 모델 모두)	이미지 출력 토큰 1백만 개당 $30, 이미지 입력 토큰 1백만 개당 $8, 텍스트 입력 토큰 1백만 개당 $5

토큰당 요율은 gpt-image-2와 동일합니다; 품질 수준별 토큰 수가 변경되었기 때문에 이미지당 비용은 여전히 변동됩니다.

사전 요구 사항

유료 사용 등급의 OpenAI 개발자 계정. 이미지 엔드포인트는 Tier 1 이상이 필요하며, 이는 결제 수단을 추가해야 함을 의미합니다; ChatGPT 구독은 포함되지 않습니다. 저희의 OpenAI API 키 가이드는 프로젝트 범위 키를 다룹니다.
Python 또는 Node용 공식 openai SDK.
이미지 응답을 미리 볼 수 있는 방법. curl은 base64를 출력하여 반복 작업에 불편합니다; Apidog는 디코딩된 이미지를 인라인으로 렌더링하며, 마지막 섹션에서는 워크플로우를 Apidog로 이동합니다.

키를 한 번 내보냅니다:

export OPENAI_API_KEY="sk-proj-..."

curl로 이미지 생성하기

먼저 Flare를 사용하세요; OpenAI의 모델 페이지에서는 이를 "대부분의 애플리케이션을 위한 기본 선택"이라고 부릅니다.

curl https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "Product photo of a matte black mechanical keyboard, studio lighting, no text",
    "size": "1536x1024",
    "quality": "medium",
    "output_format": "webp",
    "background": "transparent"
  }'

응답에는 이미지당 하나의 b64_json을 포함하는 data 배열과 input_tokens 및 output_tokens를 포함하는 usage 객체가 있습니다. usage를 잘 보관하세요; 이는 얻을 수 있는 유일한 정확한 비용 신호입니다. 이미지 생성 가이드의 매개변수 참고 사항: output_format은 기본적으로 png이며 OpenAI는 "jpeg를 사용하는 것이 png보다 빠르다"고 말합니다; output_compression (0-100)은 jpeg 및 webp에만 적용됩니다; background: "transparent"는 jpeg에서 실패합니다.

Python: 이미지 생성 후 참조 이미지로 편집하기

SDK 호출은 curl 본문을 반영합니다. b64_json을 디코딩하고 바이트를 씁니다.

import base64
from openai import OpenAI

client = OpenAI()

gen = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="Clean API analytics dashboard mockup, dark theme, latency chart top right",
    size="1536x1024",
    quality="high",
    output_format="png",
)
open("dashboard.png", "wb").write(base64.b64decode(gen.data[0].b64_json))
print(gen.usage.output_tokens, "output tokens")

편집 기능은 2.5 모델이 제 역할을 하는 부분입니다; 출시 게시물에서는 "요청한 부분만 더 잘 편집하면서 나머지 세부 사항은 동일하게 유지한다"고 말하며, OpenAI는 Sunburst를 "편집 전반에 걸쳐 더 정밀한 제어"를 위해 포지셔닝하고 있습니다. 편집 엔드포인트는 멀티파트입니다: 참조 이미지, 선택적 마스크, 그리고 프롬프트입니다. 마스크가 투명한 부분에서는 모델이 다시 그리며, 다른 모든 부분에서는 원본을 유지합니다.

edit = client.images.edit(
    model="gpt-image-2.5-sunburst",
    image=open("dashboard.png", "rb"),
    mask=open("chart-area-mask.png", "rb"),
    prompt="Replace the latency chart with a bar chart of error rates per endpoint; keep everything else",
    size="1536x1024",
    quality="high",
)
open("dashboard-v2.png", "wb").write(base64.b64decode(edit.data[0].b64_json))
print(edit.usage.input_tokens, "input tokens (includes the reference image)")

mask를 생략하면 모델은 프롬프트만으로 무엇을 변경할지 결정합니다. 참조 이미지는 1백만 개당 $8의 이미지 입력 토큰으로 청구됩니다; OpenAI는 이미지당 입력 토큰 수를 게시하지 않으므로 usage.input_tokens를 확인하십시오.

Node 및 TypeScript: b64_json을 디스크에 쓰기

import fs from "node:fs/promises";
import OpenAI from "openai";

const client = new OpenAI();

const res = await client.images.generate({
  model: "gpt-image-2.5-flare",
  prompt: "Hero image for API docs: floating JSON cards over a teal gradient, no text",
  size: "1536x1024",
  quality: "medium",
  output_format: "jpeg",
  output_compression: 80,
});

const b64 = res.data?.[0]?.b64_json;
if (!b64) throw new Error("no image returned");
await fs.writeFile("hero.jpg", Buffer.from(b64, "base64"));

별칭이 변경되는 동안 안정적인 출력을 유지하려면 프로덕션에서 gpt-image-2.5-flare-2026-09-08을 고정하세요.

Responses API: 도구로서의 이미지 생성

여기서 메인라인 모델이 사용자의 프롬프트를 읽고, 수정하여 image_generation 도구를 호출합니다. 도구 정의 내에서 model을 설정하여 이미지 모델을 선택합니다; 최상위 model은 메인라인 모델이어야 하며, OpenAI의 도구 문서에서는 gpt-6-astra를 사용합니다. 저희의 Responses API 가이드는 요청 형태를 다룹니다. action 필드는 auto (기본값), generate, 또는 edit을 사용합니다; 참조 이미지를 전달하고 재해석이 아닌 수정을 원할 때 edit으로 설정합니다.

import base64

with open("product.png", "rb") as f:
    ref = base64.b64encode(f.read()).decode()

first = client.responses.create(
    model="gpt-6-astra",
    input=[{"role": "user", "content": [
        {"type": "input_text", "text": "Put this bottle on a white marble surface with soft daylight"},
        {"type": "input_image", "image_url": f"data:image/png;base64,{ref}"},
    ]}],
    tools=[{"type": "image_generation", "model": "gpt-image-2.5-sunburst", "action": "edit"}],
)
calls = [o for o in first.output if o.type == "image_generation_call"]
open("bottle-marble.png", "wb").write(base64.b64decode(calls[0].result))

second = client.responses.create(
    model="gpt-6-astra",
    previous_response_id=first.id,
    input="Same scene, but add a second bottle behind it, slightly out of focus",
    tools=[{"type": "image_generation", "model": "gpt-image-2.5-sunburst", "action": "edit"}],
)

previous_response_id 후속 작업은 첫 번째 이미지를 컨텍스트에 유지하므로 파일을 다시 업로드할 필요 없이 "동일한 장면"이 해결됩니다. 메인라인 모델 토큰은 이미지 토큰 외에 추가로 청구되며, 프롬프트 재작성은 프롬프트 텍스트만으로는 출력을 재현할 수 없음을 의미합니다.

부분 이미지 스트리밍

두 API 모두 partial_images (0에서 3까지)를 허용합니다. 각 부분은 100개의 추가 출력 토큰 비용이 들며, 따라서 세 부분은 300개의 토큰 또는 이미지당 $0.009의 비용이 추가됩니다. 진행 상황을 보여주는 UI에는 가치가 있지만, 배치 작업에서는 낭비될 수 있습니다.

stream = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="Isometric illustration of an API gateway routing requests to three services",
    size="1024x1024",
    quality="medium",
    stream=True,
    partial_images=2,
)
for event in stream:
    if event.type.endswith("partial_image"):
        open(f"gateway-partial-{event.partial_image_index}.png", "wb").write(
            base64.b64decode(event.b64_json))
    elif event.type.endswith("completed"):
        open("gateway.png", "wb").write(base64.b64decode(event.b64_json))

정확한 이벤트 타입 문자열은 이미지 생성 가이드에 있습니다; 접미사 확인은 두 API 변형에서 루프가 작동하도록 유지합니다. 코드 외부에서 스트리밍 이벤트를 검사하려면 AI API의 SSE 응답 테스트에 대한 저희 가이드를 참조하세요.

사용량을 읽고 토큰을 달러로 환산하기

OpenAI의 경고: "동일한 토큰 요율이 이미지당 동일한 비용을 의미하지는 않습니다: 토큰 소비량은 모델 및 품질 설정에 따라 다를 수 있습니다." 이미지 생성 가이드의 계산기는 가격 책정 페이지의 1백만 개당 $30 요율을 기준으로 이미지 출력 토큰 단독에 대한 다음 추정치를 제공합니다:

품질	1024x1024	1536x1024
`low`	196 토큰, $0.0059	158 토큰, $0.0047
`medium`	439 토큰, $0.0132	343 토큰, $0.0103
`high`	1,756 토큰, $0.0527	1,372 토큰, $0.0412
`xhigh`	3,122 토큰, $0.0937	2,459 토큰, $0.0738
`max`	7,024 토큰, $0.2107	5,488 토큰, $0.1646

재분류에 유의하세요. 2.5의 high는 gpt-image-2의 이전 medium 예산인 1,756 토큰을 사용하고; max는 이전 high 예산인 7,024 토큰을 사용합니다. 마이그레이션 중 quality: "high"를 유지하면 각 이미지가 이전 medium 예산에서 약 4배 저렴해집니다; 이전 high 예산의 경우 max로 이동하세요. 저희의 Flare vs Sunburst vs gpt-image-2 비교에서는 전체 월별 계산을 실행합니다.

계산기 수치는 추정치입니다. 실제 비용은 응답에서 나옵니다:

OUTPUT_RATE = 30 / 1_000_000  # dollars per image output token
usd = gen.usage.output_tokens * OUTPUT_RATE
print(f"{gen.usage.output_tokens} tokens = ${usd:.4f}")

요청별로 기록하세요; OpenAI에 따르면, 더 큰 비정방형 크기가 더 작은 정방형 크기보다 적은 토큰을 생성할 수 있습니다. 한 가지 미해결 질문: 가격 페이지의 배치 탭에는 gpt-image-2만 나열되어 있으므로, 2.5에 대한 배치 API 지원은 확인되지 않은 것으로 간주하세요.

오류, 속도 제한 및 시간 초과

429 속도 제한. 지터를 사용하여 후퇴하고 Retry-After를 따르십시오. 2.5 모델 페이지는 티어별 제한을 게시하지 않습니다. 참고로, gpt-image-2는 Tier 1에서 분당 5개 이미지 및 10만 TPM으로 작동하며, Tier 5에서는 250 IPM 및 8백만 TPM으로 확장됩니다.
insufficient_quota. 크레딧이 없거나 여전히 무료 티어에 있습니다. 결제 정보를 추가하세요; 재시도하지 마세요.
콘텐츠 조정 거부. 프롬프트 또는 참조 이미지가 필터에 걸렸습니다. 재시도 대신 내용을 다시 작성하세요; moderation: "low"는 임계값을 완화합니다.
시간 초과. OpenAI는 "복잡한 프롬프트는 처리하는 데 최대 2분까지 걸릴 수 있다"고 문서화하고 있습니다. 클라이언트 시간 초과를 그 이상으로 설정하세요; Sunburst는 Flare보다 의도적으로 더 오래 실행됩니다.

Apidog에서 Flare와 Sunburst를 나란히 테스트하기

이미지 프롬프트에 대한 터미널 반복은 출력을 볼 수 없고, 잘못된 quality 값은 매 전송마다 실제 비용을 발생시키기 때문에 느립니다. Apidog는 API 클라이언트 및 테스트 플랫폼입니다: 호출을 전송하고 응답을 확인합니다; OpenAI 서버가 렌더링을 수행합니다.

키를 한 번 저장합니다. OPENAI_API_KEY를 환경 변수로 추가하고 Authorization 헤더에서 Bearer {{OPENAI_API_KEY}}로 참조합니다; 키는 저장된 요청에 절대 들어가지 않습니다.
두 개의 환경, 하나의 요청. flare와 sunburst라는 이름의 환경을 만들고, 각 환경에 MODEL 변수를 추가한 다음, 본문에 "model": "{{MODEL}}"을 설정합니다. 전환하고, 다시 전송하여 이미지와 usage를 나란히 비교합니다. 편집의 경우, image와 mask를 파일 필드로 사용하여 form-data 본문을 사용합니다.
후처리 단계에서 b64_json 디코딩. 짧은 스크립트가 data[0].b64_json을 가져와 디코딩하고 파일을 저장하므로, 모든 전송마다 원시 JSON 옆에 볼 수 있는 이미지가 생성됩니다.
비용에 대한 단언(assert) 후, 일정을 잡습니다. usage.output_tokens가 예산(예를 들어 high 1536x1024 렌더링의 경우 2,000 토큰)을 초과하지 않는지 단언하고, 요청을 정기 회귀 테스트로 실행합니다. 만약 누군가 품질을 max로 올리거나 스냅샷이 토큰 수를 변경하면, 청구서가 나오기 전에 테스트가 실패합니다.

Apidog를 다운로드하고 OpenAI 키를 연결하면, 비용 제한이 있는 공유 프롬프트 라이브러리를 사용할 수 있습니다.

자주 묻는 질문

2.5를 사용하기 위해 gpt-image-2 코드를 변경해야 하나요? 모델 ID를 교체하고 quality를 다시 확인하세요. 엔드포인트, 인증 및 응답 형태는 변경되지 않았지만, 이제 high는 더 작은 토큰 예산에 매핑됩니다. gpt-image-2 API 가이드는 여전히 이전 모델을 다룹니다.
API에 Flare 또는 Sunburst? Flare로 시작하세요. OpenAI는 이를 gpt-image-2와 동일한 토큰당 가격으로 "50% 더 낮은 지연 시간"을 가진 기본 모델로 포지셔닝합니다. 참조 사진으로 구축된 제품 이미지와 같이 속도보다 편집 정밀도가 더 중요할 때 Sunburst로 전환하세요. 두 모델 모두 동일한 계산기 토큰 수를 공유하므로, 비용이 아닌 시간이 선택의 기준이 됩니다.
이 모델들을 Chat Completions에서 사용할 수 있나요? 아니요. 이미지 생성은 이미지 API와 Responses API의 image_generation 도구에서만 가능합니다. Chat Completions는 이를 노출하지 않습니다.
API를 통해 2.5를 무료로 사용해 볼 방법이 있나요? 영구적인 무료 API 티어는 없으며, 이미지 엔드포인트는 Tier 1이 필요합니다. 가장 저렴한 실제 경로는 quality: "low"로 196 토큰이며, 1024x1024 이미지당 약 $0.006입니다. 소비자 앱은 별개의 문제입니다; ChatGPT Images 2.5를 무료로 사용하는 방법을 참조하세요.

다음 단계

curl 호출로 시작하여 계산기 표와 usage.output_tokens를 확인한 다음, 이미지를 볼 수 있는 클라이언트로 요청을 옮기세요. Simon Willison의 글에서는 Sunburst가 차트를 그대로 유지하면서 피사체를 추가하는 것을 보여줍니다; 커밋하기 전에 자신의 참조 이미지로 해당 편집 동작을 테스트해 보세요.

다운로드 버튼