GPT-Image-2.6 API 사용법

GPT-Image-2.6 API는 gpt-image-2.6-flare와 gpt-image-2.6-sunburst라는 두 가지 OpenAI 모델을 통해 이미지를 생성하고 편집합니다. API 키와 함께 프롬프트를 POST /v1/images/generations로 보낸 다음, 응답의 b64_json을 디코딩하면 됩니다. 버전 2.6에서는 이미지 마크업, SVG 및 GIF 출력, 그리고 complexity 파라미터가 추가되었습니다.

이 가이드에서는 인증, 첫 생성, 마크업 편집, SVG 내보내기, quality 및 complexity 설정을 다룹니다. 새로운 내용에만 집중했으므로, 스트리밍과 Responses API 도구에 대해서는 gpt-image-2.5 API 가이드를, 전체 릴리스 내용은 ChatGPT Images 2.6 해설을 참고하세요. 아래의 모든 요청은 2026년 11월 5일자 OpenAI 문서를 기반으로 작성했습니다. 실제 키로 실행해 본 적은 없으니, 배포 전에 반드시 테스트해 보세요.

GPT-Image-2.6 API 한눈에 보기

항목	세부 정보
모델 ID	`gpt-image-2.6-flare`, `gpt-image-2.6-sunburst`
생성	`POST /v1/images/generations`
편집	`POST /v1/images/edits`
인증	`Authorization: Bearer $OPENAI_API_KEY`
출력	`b64_json`; 기본은 PNG이며, JPEG, WebP, GIF, SVG도 지원
`quality`	`low`, `medium`, `high`, `xhigh`, `max`, `auto`(기본값)
`complexity`	`low`, `medium`, `high`(생략 시 `high`)
이미지 토큰 요금	1M당 입력 $8, 캐시된 입력 $2, 출력 $30
텍스트 토큰 요금	1M당 입력 $5, 캐시된 입력 $1.25

요금은 OpenAI 가격 페이지에서 가져왔습니다. 두 모델 모두 토큰당 비용이 동일하므로, 속도와 편집 정밀도를 기준으로 선택하세요.

Flare와 Sunburst: 어떤 모델을 호출해야 할까?

빠른 반복 작업과 일상적인 생성에는 Flare를 호출하세요. OpenAI에 따르면 Flare는 low 품질에서 최소 6초 만에 이미지를 반환할 수 있으며, 포스터와 제품 이미지의 레이아웃을 개선한다고 합니다. 세밀한 작업과 반복적인 편집에는 Sunburst를 호출하세요. OpenAI는 medium 또는 high 품질에서 더 나은 일관성을 제공한다고 주장합니다.

이는 독립적인 벤치마크가 아닌 OpenAI의 주장입니다. 2.5 버전의 Flare vs Sunburst 비교에서 두 모델의 차이를 설명하고 있습니다.

인증 및 설정

첫 호출을 하기 전에 세 가지가 필요합니다:

OpenAI 대시보드에서 API 키를 생성하고 OPENAI_API_KEY로 내보내세요.
조직에서 필요로 한다면 API Organization Verification을 완료하세요. OpenAI에 따르면 GPT Image 모델을 사용하기 전에 이 과정이 필요할 수 있습니다.
curl 예제를 위해 jq를, Python을 위해 openai 패키지를 설치하세요.

앱이 개별 사용자에게 서비스를 제공한다면, 최대 128자 길이의 해시된 safety_identifier도 함께 전송하세요. 이는 더 이상 사용되지 않는 user 파라미터를 대체합니다.

첫 이미지 생성하기

이 요청은 low 품질의 Flare를 사용하며, 초안 작업에 적합합니다.

curl --fail-with-body --silent --show-error \
  https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-flare",
    "prompt": "A minimal poster for a developer meetup, with the words SHIP IT in bold type",
    "size": "1024x1536",
    "quality": "low",
    "complexity": "low"
  }' | jq -er '.data[0].b64_json' | base64 --decode > poster.png

동일한 호출을 Python으로 작성하면 다음과 같습니다:

import base64
from pathlib import Path
from openai import OpenAI

client = OpenAI()

result = client.images.generate(
    model="gpt-image-2.6-sunburst",
    prompt="A product shot of a ceramic mug on a walnut desk, soft morning light",
    size="1536x1024",
    quality="medium",
    extra_body={"complexity": "low"},
)

Path("mug.png").write_bytes(base64.b64decode(result.data[0].b64_json))

complexity는 extra_body를 통해 전달하여, SDK 버전이 이를 명명된 인수로 노출하는지 여부에 관계없이 호출이 작동하도록 했습니다. GPT Image 모델은 항상 base64를 반환하므로 response_format을 보내지 말고, url 필드를 찾지도 마세요.

OpenAI 가이드에서는 토큰 사용량을 측정하기 위해 응답의 usage 객체를 읽으라고 안내합니다. 하지만 API 레퍼런스는 이 필드가 gpt-image-1에만 해당한다고 설명하고 있으며, 샘플 응답에는 포함되어 있습니다. 따라서 비용 추적을 구축하기 전에 2.6 응답에서 이 필드가 나타나는지 먼저 확인하세요.

마크업으로 이미지 편집하기

마크업은 모델에게 어디를 변경해야 하는지 알려줍니다. 원본 이미지, 원이나 스케치를 그린 투명 PNG, 그리고 편집 내용을 설명하는 프롬프트를 함께 전송합니다.

curl --fail-with-body --silent --show-error \
  https://api.openai.com/v1/images/edits \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-flare",
    "images": [{"image_url": "https://your-bucket.example/kitchen.png"}],
    "markup": {"image_url": "https://your-bucket.example/vase-overlay.png"},
    "prompt": "Recolor the vase inside the red circle to solid cobalt blue. Keep everything else unchanged. Remove the red circle.",
    "quality": "medium",
    "complexity": "low"
  }' | jq -er '.data[0].b64_json' | base64 --decode > vase.png

JSON 요청은 images 배열과 image_url 또는 file_id 중 정확히 하나만 담는 markup 객체를 사용합니다. image_url은 HTTPS URL 또는 base64 데이터 URL이 될 수 있습니다. 멀티파트 요청은 대신 파일 업로드를 받으며, 해당 버전의 Python 예제는 이미지 생성 가이드에서 확인할 수 있습니다.

Diagram of a GPT-Image-2.6 markup edit: the original photo, a transparent PNG overlay and a text prompt go to POST /v1/images/edits, which returns the edited image with the annotation removed

오버레이에는 엄격한 규칙이 적용됩니다:

방향을 조정한 후 첫 번째 이미지의 너비와 높이와 일치해야 합니다.
투명 픽셀을 포함해야 하므로, 사진 위에 평탄화하지 마세요.
첫 번째 입력 이미지에 적용됩니다. 나머지 이미지는 참조로 사용됩니다.
두 이미지 각각은 최대 16,777,216 픽셀을 담을 수 있으며, 오버레이 파일은 50MB를 초과할 수 없습니다.
markup은 mask 또는 prompt_rewriter와 함께 사용할 수 없습니다.

OpenAI의 예제에서처럼, 모델에게 주석을 제거하라고 지시하세요. 마크업은 다른 편집과 동일한 비용이 듭니다. Responses API는 마크업을 지원하지 않으므로, 그곳에서는 마스크를 사용하세요.

SVG 내보내기

편집 가능한 경로가 필요한 아이콘, 로고, 일러스트레이션에는 생성 엔드포인트에서 output_format을 svg로 설정하세요.

curl --fail-with-body --silent --show-error \
  https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-sunburst",
    "prompt": "A flat two-color wheat logo for a bakery called Field and Flour",
    "output_format": "svg",
    "quality": "medium",
    "n": 1
  }' | jq -er '.data[0].b64_json' | base64 --decode > logo.svg

API는 먼저 quality로 제어되는 참조 이미지를 렌더링한 다음, 이를 기반으로 SVG를 작성합니다. 디코딩된 바이트는 스크립트, 외부 리소스, 임베디드 래스터가 없는 UTF-8 XML입니다.

네 가지 제한 사항이 있습니다:

n은 1이어야 합니다.
스트리밍, 부분 이미지, output_compression, prompt_rewriter는 작동하지 않습니다.
편집 엔드포인트는 SVG를 출력할 수 없으며, SVG를 래스터 입력으로 받지도 않습니다.
선택적 svg 객체는 작성 모델을 선택하지만, 계정에 SVG 모델 선택 기능이 있는 경우에만 가능합니다. 그렇지 않으면 생략하세요.

비용은 두 번 발생합니다: 참조 이미지에 대한 이미지 요금과 작성 모델의 토큰 요금입니다. API 레퍼런스에는 두 번째 부분을 위한 별도의 svg_usage 객체가 나열되어 있으니, 이를 로깅하세요.

GIF 생성하기

API는 스프라이트 시트가 아닌 완성된 GIF를 반환합니다. 생성 요청에 세 가지 필드를 추가하세요:

{
  "model": "gpt-image-2.6-flare",
  "prompt": "A small orange robot waves, blinks and returns to its starting pose. Make it loop.",
  "output_format": "gif",
  "frame_count": 9,
  "frame_duration_ms": 200,
  "size": "auto"
}

동일한 방식으로 b64_json을 디코딩하고 .gif로 저장하세요. 먼저 두 가지를 확인하세요:

프레임 제한. 가이드에서는 frame_count가 2에서 64까지라고 설명합니다. 반면 API 레퍼런스는 2에서 16이라고 합니다. 더 높은 값을 테스트해 보기 전까지는 16 이하로 유지하세요.
접근 권한. 레퍼런스에 따르면 GIF 출력은 선택한 모델의 GIF 프리뷰에 대한 접근 권한이 필요하지만, 가이드에서는 이에 대해 언급하지 않습니다. GIF 요청이 거부되었다면 잘못된 페이로드가 아니라 접근 권한 문제일 수 있습니다.

GIF 출력은 스트리밍, 부분 이미지, 사용자 정의 output_compression을 지원하지 않으며, 편집 엔드포인트에서는 반환할 수 없습니다. OpenAI는 GIF 전용 청구 공식을 공개하지 않았으므로, 규모를 확장하기 전에 소규모 테스트를 실행하고 청구서를 확인하세요.

품질과 복잡도 설정하기

quality는 렌더링 세부 수준을 제어하고 토큰 비용에 영향을 미칩니다. complexity는 모델이 렌더링 전에 얼마나 계획하는지를 제어하며, 이를 변경해도 별도의 요금은 발생하지 않습니다.

모든 요청에서 complexity를 설정하세요. 기본값은 high이지만, OpenAI는 대부분의 편집에 low를 권장합니다. 가이드에서는 높은 설정이 지연 시간을 늘리고 원치 않는 변경을 유발할 수 있다고 경고합니다.

Grid of suggested GPT-Image-2.6 starting settings: quick drafts use Flare at low quality and low complexity, focused edits use low complexity, final detailed images use Sunburst at medium or high quality, and dense layouts use medium or high complexity

품질은 출력 청구 금액도 결정합니다. 다음 표는 11월 5일 기준 OpenAI 계산기를 사용한 1024x1024 이미지의 결과이며, 입력 토큰은 제외한 값입니다:

`quality`	출력 토큰	출력 비용
`low`	823	$0.02469
`medium`	1,449	$0.04347
`high`	1,756	$0.05268
`xhigh`	3,122	$0.09366
`max`	7,024	$0.21072

medium과 high의 차이는 약 1센트이므로, 두 가지를 모두 비교해 보세요. 가격 페이지의 Batch 탭에는 아직 2.6이 나열되지 않았으므로, 2.5의 배치 할인이 적용된다고 가정하지 마세요.

오류 및 타임아웃 처리하기

재시도가 도움이 될 수 있는지에 따라 실패를 분류하세요:

실패 유형	대응 방법
속도 제한 또는 서버 오류	백오프를 사용하여 재시도
할당량 오류	재시도하지 말고 청구 문제 해결
`error.type`이 `image_generation_user_error`인 경우	먼저 프롬프트나 입력을 변경
`error.code`가 `moderation_blocked`인 경우	`moderation_details`를 읽고 수정

error.code를 안정적인 확인 기준으로 사용하고, 요청 ID를 로깅하세요. moderation_details에는 moderation_stage와 대략적인 categories가 포함되는데, 이는 사용자에게 보이는 메시지가 아니라 로그에 기록해야 합니다. OpenAI에 따르면 복잡한 프롬프트는 2분 이상 걸릴 수 있으므로, 클라이언트 타임아웃을 2분 이상으로 설정하세요.

Apidog CLI로 코딩 에이전트가 테스트하도록 하기

Apidog CLI를 사용하면 코딩 에이전트가 이러한 요청과 제한 사항을 테스트 스위트로 전환할 수 있습니다. 한 번만 설정하면 됩니다:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install

그런 다음 Claude Code, Codex 또는 Cursor에 다음 프롬프트를 전달하세요:

In Apidog project <id>, add POST /v1/images/generations and POST /v1/images/edits
on https://api.openai.com. Read the bearer token from OPENAI_API_KEY.
Create test cases for gpt-image-2.6-flare at low quality and low complexity:
1. PNG generation: assert status 200 and data[0].b64_json exists.
2. SVG generation: assert status 200 and output_format equals svg.
3. GIF with frame_count 6: assert status 200 and output_format equals gif.
4. SVG with n set to 2: assert a 4xx status and that error.message exists.
5. GIF with frame_count 17: record the status, because OpenAI's docs disagree.
Put them in a test suite named "GPT-Image-2.6", run it against environment
<envId>, and summarize every failure.

에이전트는 각 스키마를 읽고, 페이로드를 검증한 다음, 스위트를 작성하고 실행합니다:

apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file endpoint.json
apidog endpoint create --project <id> --file endpoint.json
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <id> --file case.json
apidog cli-schema validate test-suite-create --file suite.json
apidog test-suite create --project <id> --file suite.json
apidog test-suite run <suiteId> --project <id> -e <envId> \
  --env-var "OPENAI_API_KEY=$OPENAI_API_KEY" --on-error continue -r cli,json

케이스 5는 계정의 프레임 제한을 확인해 주고, 케이스 3은 GIF 접근 권한이 있는지 보여줍니다. 성공한 케이스는 실제로 청구되는 생성 작업을 수행하므로, 품질을 낮게 유지하세요. CI 파이프라인에서 스위트를 실행하려면 -r junit으로 교체하고, 에이전트 관련 세부 사항은 Claude Code 설정 가이드를 참고하세요.

FAQ

GPT-Image-2.6 API의 모델 이름은 무엇인가요? gpt-image-2.6-flare와 gpt-image-2.6-sunburst입니다. 2.5 모델과 달리, API 레퍼런스에는 아직 이들에 대한 날짜별 스냅샷이 나열되어 있지 않습니다.

GPT-Image-2.6 API 비용은 얼마인가요? 이미지 토큰은 1M 입력당 $8, 1M 출력당 $30입니다. 1024x1024 이미지는 입력 토큰을 제외하고 low에서 출력 비용이 약 $0.025, high에서 약 $0.053입니다.

gpt-image-2.5에서 마이그레이션해야 하나요? SVG, GIF 또는 complexity가 필요하다면 마이그레이션하세요. 다만 먼저 비용을 테스트해 보세요: low 이미지는 2.5에서 사용한 토큰의 약 4.2배를 사용하며, 2.6 모델에는 아직 Batch 가격이 나열되어 있지 않습니다.

편집 엔드포인트에서 complexity를 사용할 수 있나요? 네. OpenAI는 대부분의 편집에 low를 권장합니다.

업로드한 이미지를 API를 통해 GIF로 변환할 수 있나요? 아니요. 편집 엔드포인트는 GIF나 SVG를 반환하지 않으므로, 두 형식 모두 생성 엔드포인트에서 텍스트 프롬프트로 시작해야 합니다.

API가 URL을 반환하나요? 아니요. GPT Image 모델은 항상 b64_json에 base64로 반환하므로, 직접 디코딩하여 파일을 저장해야 합니다.