gpt-image-2 API 사용법

gpt-image-2 API는 2026년 4월 21일 ChatGPT 이미지 2.0과 함께 출시된 OpenAI의 새로운 이미지 생성 엔드포인트입니다. 이미 OpenAI 채팅 또는 임베딩 API를 호출하고 있다면, 이미지 생성을 추가하는 데는 새로운 요청 형식, 적절한 범위를 가진 API 키, 그리고 약 10분 정도가 소요됩니다.

이 가이드는 전적으로 API에 관한 것입니다: 인증, 요청 매개변수, 세 가지 언어로 된 코드 샘플, 사고 모드, 배치 생성, 응답 처리, 오류 코드, 속도 제한, 그리고 잘못된 프롬프트로 크레딧을 낭비하지 않도록 하는 테스트 워크플로우를 다룹니다. ChatGPT 이미지 2.0의 새로운 기능에 대한 제품 수준의 개요는 ChatGPT 이미지 2.0 분석을 참조하십시오.

이 가이드를 마치면 작동하는 호출, 반복을 위한 재사용 가능한 Apidog 컬렉션, 그리고 각 매개변수 비용에 대한 명확한 그림을 얻게 될 것입니다.

버튼

전제 조건

첫 요청을 보내기 전에 네 가지가 필요합니다:

API 접근 권한이 있는 OpenAI 계정. 개발자 계정은 ChatGPT Plus와 별개입니다; ChatGPT 구독에는 API 크레딧이 포함되지 않습니다.
유료 사용 등급. gpt-image-2는 Tier 1 이상에서 사용할 수 있습니다. 새 계정은 무료 등급으로 시작하며 이미지 엔드포인트가 잠금 해제되기 전에 결제 정보를 추가해야 합니다.
images:write 범위를 가진 API 키. 프로덕션 환경에서는 사용자 범위 키보다 프로젝트 범위 키를 권장합니다.
이미지 응답을 미리 볼 수 있는 테스트 도구. 터미널 curl은 첫 요청에 작동하지만, 그 이후에는 실제 API 클라이언트를 사용하십시오. 자세한 내용은 아래에서 설명합니다.

이 가이드의 모든 예제가 수정 없이 실행되도록 셸에 키를 한 번 설정하십시오:

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

엔드포인트 및 인증

gpt-image-2는 이전 모델과 동일한 이미지 생성 엔드포인트를 사용합니다:

POST https://api.openai.com/v1/images/generations

인증은 Authorization 헤더의 베어러 토큰입니다. 모든 요청에는 모델 ID, 프롬프트, 출력 매개변수가 포함된 JSON 본문도 함께 전달됩니다.

curl https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A sharp product hero image for an API testing platform, dark background",
    "size": "1024x1024",
    "n": 1,
    "quality": "high"
  }'

호출에 성공하면 이미지 data 배열이 포함된 JSON 객체를 받게 됩니다. 실패 시에는 code와 사람이 읽을 수 있는 message가 포함된 표준 OpenAI 오류 엔벨로프를 반환합니다; 이 가이드 뒷부분의 오류 표에서 일반적인 오류를 다룹니다.

요청 매개변수

요청 본문의 모든 필드는 지불할 금액과 얻게 될 결과에 영향을 미칩니다. 다음은 gpt-image-2의 전체 매개변수 맵입니다.

매개변수	유형	값	참고
`model`	문자열	`gpt-image-2`	필수.
`prompt`	문자열	최대 32,000자	필수. 프롬프트가 길수록 더 많은 입력 토큰을 소모합니다.
`size`	문자열	`1024x1024`, `1024x1536`, `1536x1024`, `2000x1000`, `1000x2000`, `2000x667`, `667x2000`	출력 토큰 수에 영향을 줍니다.
`quality`	문자열	`standard`, `high`	`high`는 약 2배의 비용이 들지만 미세한 텍스트 및 UI 요소를 처리합니다.
`n`	정수	1–10	배치 요청은 세트 전체에서 스타일을 공유합니다.
`thinking`	문자열	`off`, `low`, `medium`, `high`	렌더링 전 추론 예산.
`response_format`	문자열	`url`, `b64_json`	URL은 한 시간 후에 만료됩니다.
`user`	문자열	자유 형식	악용 감지에 사용됩니다; 해시된 사용자 ID를 전달하십시오.
`background`	문자열	`auto`, `transparent`, `opaque`	투명한 출력은 알파 채널이 있는 PNG로 제공됩니다.
`seed`	정수	모든 int32	느슨한 제어; 동일한 시드와 동일한 프롬프트는 유사하지만 동일하지는 않습니다.

비용에 가장 큰 영향을 미치는 세 가지 매개변수는 size, quality, thinking입니다. thinking: "high"를 사용한 2000픽셀 너비의 high 품질 이미지는 기준 1024x1024 standard 렌더링 비용의 4~5배에 달할 수 있습니다.

Python 예시

공식 SDK (openai>=1.50.0)는 gpt-image-2에 대한 네이티브 지원을 추가합니다:

import base64
from pathlib import Path
from openai import OpenAI

client = OpenAI()

response = client.images.generate(
    model="gpt-image-2",
    prompt=(
        "A minimalist diagram of an OAuth 2.1 authorization code flow with PKCE. "
        "Five boxes labeled in English: User, Client, Auth Server, Resource Server, Token. "
        "Sharp sans-serif text, off-white background, teal accent arrows."
    ),
    size="1536x1024",
    quality="high",
    n=2,
    thinking="medium",
    response_format="b64_json",
)

out_dir = Path("out")
out_dir.mkdir(exist_ok=True)

for i, image in enumerate(response.data):
    png_bytes = base64.b64decode(image.b64_json)
    (out_dir / f"oauth_{i}.png").write_bytes(png_bytes)

print(f"Generated {len(response.data)} images into {out_dir.resolve()}")

두 가지 주목할 점:

n=1일 때도 response.data는 목록입니다. 항상 반복하십시오.
로컬 스크립트에는 b64_json이 더 쉽습니다; 이미지를 CDN이나 S3 업로드로 전달하는 경우에는 디코딩-재인코딩 주기를 건너뛸 수 있으므로 url이 더 좋습니다.

Node.js / TypeScript 예시

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

const client = new OpenAI();

const response = await client.images.generate({
  model: "gpt-image-2",
  prompt:
    "Dashboard UI mockup for a REST client, sentence-case labels, latency sparkline in the top-right, cool grey palette.",
  size: "1536x1024",
  quality: "high",
  n: 4,
  thinking: "medium",
  response_format: "b64_json",
});

await Promise.all(
  response.data.map(async (image, i) => {
    if (!image.b64_json) return;
    await fs.writeFile(`dash_${i}.png`, Buffer.from(image.b64_json, "base64"));
  }),
);

console.log(`Saved ${response.data.length} images`);

특별한 이유가 없다면 일반 fetch 대신 공식 SDK를 사용하십시오. SDK는 재시도, 멱등성 헤더, 스트리밍을 처리하며, 모델 개정 간의 스키마 변경 사항을 추적합니다.

사고 모드: 언제 사용해야 하는가

thinking은 모델이 렌더링하기 전에 레이아웃을 계획하는 데 얼마나 많은 컴퓨팅 자원을 할애할지 제어합니다. 대략 네 가지 값:

off: 추론 없음. 가장 빠르고 저렴하며, 구성이 정확할 필요가 없는 자유로운 창의적 프롬프트에 가장 적합합니다.
low: 가벼운 계획. 제품 사진 및 히어로 이미지에 적합한 기본값입니다.
medium: 더 무거운 계획. 다이어그램, 인포그래픽, 슬라이드, 그리고 개수가 정해진 요소("패널 4개", "화살표 3개")가 있는 모든 것에 적합합니다.
high: 최대 추론. 복잡한 다국어 레이아웃이나 엄격한 기술 다이어그램에서만 효과가 있으며, 눈에 띄게 높은 지연 시간과 비용을 예상해야 합니다.

실용적인 규칙: 프롬프트에 숫자, 레이블 또는 위치 제약이 포함되어 있으면 한 단계 올리십시오. 단순히 "아늑한 장면"이라고만 되어 있으면 한 단계 내리십시오.

사고 모드는 이미지 출력 토큰 외에 추론 토큰에 대한 비용을 추가합니다. OpenAI 가격 페이지에는 현재 토큰당 요금이 나와 있습니다; medium 또는 high를 켜면 기본 이미지 비용의 1.2~2배를 예산으로 잡으십시오.

배치 생성

n > 1로 설정하면 단일 응답에서 구성과 스타일을 공유하는 여러 이미지가 반환됩니다. 이는 엔드포인트를 n번 병렬로 호출하는 것과는 다릅니다; 병렬 호출은 관련 없는 네 개의 이미지를 제공합니다. 배치 출력은 일관성이 있으며, 이는 디자인 팀이 반복하는 방식과 일치합니다.

response = client.images.generate(
    model="gpt-image-2",
    prompt="Four different hero illustrations for an API documentation landing page, shared color palette, shared line weight.",
    size="1536x1024",
    quality="high",
    n=4,
    thinking="low",
)

이미지당 비용을 지불하므로, n=4는 n=1의 대략 4배의 비용이 듭니다. 이점은 처리량이 아니라 일관성입니다.

응답 형식 및 저장

두 가지 형식, 두 가지 사용 사례:

b64_json: 이미지가 응답에 인라인으로 포함됩니다. 스크립트에 용이합니다. 응답 페이로드가 빠르게 커질 수 있습니다; 2000픽셀 너비의 고품질 PNG는 응답 크기를 3MB 이상으로 만들 수 있습니다.
url: 이미지는 OpenAI의 CDN에 한 시간 동안 저장되며, 사용자가 직접 다운로드합니다. 응답 크기 제한이 있는 서버리스 함수나 이미지를 자체 스토리지로 전달하는 파이프라인에 더 적합합니다.

프로덕션 환경에서는 URL을 다운로드하여 즉시 자체 S3, R2 또는 Cloudflare Images 버킷에 푸시하십시오. 최종 사용자에게 OpenAI URL을 제공하지 마십시오. 만료됩니다.

오류 처리 및 속도 제한

gpt-image-2는 표준 OpenAI 오류 형식을 반환합니다. 발생할 수 있는 오류는 다음과 같습니다:

HTTP	`코드`	원인	해결
400	`invalid_request_error`	잘못된 크기, 지원되지 않는 비율, 프롬프트 32k자 초과	크기 목록을 확인하고 프롬프트를 줄이십시오.
401	`invalid_api_key`	키 누락 또는 잘못된 키	`OPENAI_API_KEY`를 다시 내보내십시오.
403	`insufficient_quota`	크레딧 부족 또는 무료 등급	결제를 추가하고 등급을 확인하십시오.
429	`rate_limit_exceeded`	분당 너무 많은 요청	지터와 함께 대기 후 `Retry-After`로 재시도하십시오.
429	`image_generation_user_error`	콘텐츠 정책 거부	프롬프트를 다시 작성하십시오.
500	`server_error`	일시적인 OpenAI 문제	지수 백오프를 사용하여 두 번 재시도하십시오.
503	`overloaded`	지역 전반의 급증	기다렸다가 재시도하십시오.

gpt-image-2의 속도 제한은 등급별로 다릅니다. Tier 1에서는 분당 약 50개 요청으로 시작하며, 상위 등급에서는 증가합니다. 모든 응답에서 x-ratelimit-remaining-requests 및 x-ratelimit-remaining-tokens 헤더를 항상 읽고 한도에 도달하기 전에 스로틀링하십시오.

프로덕션 환경에서 재시도 가능한 오류:

import time
from openai import OpenAI, RateLimitError, APIStatusError

client = OpenAI()

def generate_with_retry(prompt: str, tries: int = 3):
    delay = 1.0
    for attempt in range(tries):
        try:
            return client.images.generate(
                model="gpt-image-2",
                prompt=prompt,
                size="1024x1024",
                quality="high",
                n=1,
            )
        except RateLimitError:
            time.sleep(delay)
            delay *= 2
        except APIStatusError as e:
            if 500 <= e.status_code < 600 and attempt < tries - 1:
                time.sleep(delay)
                delay *= 2
                continue
            raise
    raise RuntimeError("gpt-image-2 retries exhausted")

400, 401 또는 콘텐츠 정책 관련 429 오류는 재시도하지 마십시오. 이러한 오류는 이유가 있어 실패하며 재시도는 크레딧을 낭비합니다.

Apidog로 API 테스트하기

터미널에서 이미지 생성 프롬프트를 반복하는 것은 느립니다: 결과를 볼 수 없고, 매개변수 변경 사항을 비교할 수 없으며, 좋은 프롬프트를 버전 관리할 수 없습니다. 목적에 맞게 구축된 API 클라이언트는 이 세 가지 문제를 모두 해결합니다.

Apidog는 gpt-image-2 엔드포인트를 일류 요청으로 취급합니다. 일반적인 워크플로우:

OpenAI 컬렉션에서 새 요청을 생성하고, 메서드는 POST, URL은 https://api.openai.com/v1/images/generations로 설정합니다.
Authorization: Bearer {{OPENAI_API_KEY}}를 헤더로 추가하고, OPENAI_API_KEY는 환경 변수에 설정하여 소스에 절대 노출되지 않도록 합니다.
프롬프트가 포함된 JSON 본문을 붙여넣습니다; Apidog는 OpenAPI 사양에 대해 유효성을 검사하고 전송하기 전에 유형 불일치를 알려줍니다.
전송을 클릭합니다. 이미지 응답은 인라인으로 렌더링됩니다; 좋은 이미지는 저장하고, 나쁜 이미지는 태그를 지정하고, 변형을 위해 요청을 포크합니다.
thinking: off, thinking: medium, thinking: high에 대한 환경을 저장하여 동일한 프롬프트를 추론 수준별로 비교합니다.

Apidog의 요청 차이 비교 기능이 여기에서 가장 중요합니다. 하나의 매개변수를 조정하고, 변경 전후 이미지를 나란히 보고, 승자를 팀 전체가 공유하는 프롬프트 라이브러리에 커밋합니다. 이것은 터미널이 제공할 수 없는 워크플로우입니다.

일반 HTTP 클라이언트나 손상된 Postman 워크스페이스에서 전환하는 경우, Apidog를 다운로드하여 OpenAI 키를 가리키십시오; 설정은 5분 이내에 완료됩니다. 대안을 평가하는 팀은 Postman 없이 API 테스트 가이드 및 Apidog VS Code 확장 개요도 읽을 수 있습니다.

흔한 실수

gpt-image-2를 처음 사용하는 한 주 동안 크레딧과 시간을 소모하는 몇 가지 실수가 있습니다.

텍스트가 많은 프롬프트에 quality: "standard" 사용. 표준 품질은 작은 텍스트를 망가뜨립니다. 레이블, 아이콘 또는 UI 텍스트가 중요할 때는 high로 전환하십시오.
과도한 프롬프트. 32k자는 상한선이지 목표가 아닙니다. 수백 토큰을 넘어가면 모델은 이전 지침을 무시하기 시작합니다. 프롬프트를 500단어 미만으로 유지하고 thinking을 사용하여 복잡한 제약 조건을 적용하십시오.
seed에서 재현 가능성을 기대. 시드는 분산을 줄이지만 출력을 고정하지는 않습니다. 정확히 동일한 이미지가 필요하다면 바이트를 캐시하십시오; 다시 렌더링하지 마십시오.
OpenAI URL 제공. 한 시간 후에 만료됩니다. 다운스트림에 제공하기 전에 항상 자체 스토리지에 복사하십시오.
반복문에서 엔드포인트 호출. 이미지 생성은 느립니다. 작업자 간에 병렬화하고 속도 제한 헤더를 준수하십시오; 순차적인 반복문은 대기열에 쌓여 시간 초과될 뿐입니다.

자주 묻는 질문

API 수준에서 gpt-image-2와 gpt-image-1의 차이점은 무엇입니까?동일한 엔드포인트, 동일한 인증. 새로운 매개변수: thinking (off/low/medium/high), 최대 2000px까지 확장된 size 값, 공유 스타일을 가진 최대 10개의 n 값. 기존 SDK 통합은 모델 ID 변경 후에도 계속 작동합니다; 필요한 경우에만 새로운 매개변수를 추가하면 됩니다. 전체 차이점은 ChatGPT 이미지 2.0 개요를 참조하십시오.

gpt-image-2 통합을 프로토타이핑하는 가장 빠른 방법은 무엇입니까?Apidog에서 요청을 생성하고, 두 개의 환경(표준 대 사고 모드)을 저장하고, 코드를 건드리지 않고 프롬프트를 반복하십시오. 커밋할 준비가 되면 최종 요청을 curl 또는 SDK 코드로 내보내십시오.

API는 이미지 편집 또는 인페인팅을 지원합니까?편집 및 변형 엔드포인트는 새 모델 ID 아래에서 이전 세대와 동일한 패턴을 따릅니다. 최신 스키마는 gpt-image-2 모델 참조를 확인하십시오; 마스크 및 입력 이미지에 대한 매개변수가 문서화되어 있습니다.

gpt-image-2를 상업적 출력에 사용할 수 있습니까?예, OpenAI의 표준 사용 정책에 따라 가능합니다. 생성된 이미지는 사용자 소유입니다; OpenAI는 악용 모니터링을 위해 입력 및 출력을 사용할 권리를 보유합니다. 상표 등록된 캐릭터 및 이름이 지정된 공인은 여전히 보호 장치를 트리거합니다.

프로덕션 워크로드 비용은 얼마입니까?표준 모드에서 1024x1024 고품질 이미지당 약 $0.21이므로, 한 달에 10,000개의 이미지는 사고 모드 없이 약 $2,100가 듭니다. 사고 모드를 추가하면 20~80%가 추가됩니다. 예산이 최고 품질보다 더 중요하다면, GLM 5V Turbo API 가이드 및 Qwen 3.5 Omni 통합과 같은 자체 호스팅 대안과 비교해보십시오.

유사한 텍스트 렌더링을 제공하는 더 저렴한 대안이 있습니까?아직 다국어 텍스트에 대해 동일한 품질을 제공하는 대안은 없습니다. 오픈 소스 모델은 구성 면에서 격차를 좁혔지만, CJK 및 인도어 스크립트에서는 여전히 뒤처져 있습니다.

버튼