Rihpig

Posted on Apr 22 • Originally published at apidog.com

gpt-image-2 API 사용법

gpt-image-2 API는 2026년 4월 21일 ChatGPT 이미지 2.0과 함께 출시된 OpenAI의 신규 이미지 생성 엔드포인트입니다. 기존에 OpenAI 채팅 또는 임베딩 API를 사용 중이라면, 이 가이드를 따라 바로 이미지 생성을 워크플로우에 통합할 수 있습니다. 핵심은 새로운 요청 형식, 적절한 범위의 API 키 준비, 그리고 약 10분의 환경 세팅입니다.

지금 Apidog을 사용해보세요

이 글은 API 자체에 집중합니다: 인증, 요청 매개변수, 3개 언어별 코드 샘플, 사고 모드, 배치 생성, 응답 처리, 오류 코드, 속도 제한, 프롬프트 검증용 워크플로우까지 모두 다룹니다. ChatGPT 이미지 2.0의 신기능 요약은 ChatGPT 이미지 2.0 분석을 참고하십시오. 이 가이드 완료 시, 바로 사용할 수 있는 호출, 반복 가능한 Apidog 컬렉션, 각 매개변수별 비용 구조를 정확히 이해하게 됩니다.

전제 조건

시작 전 아래 4가지를 준비하십시오:

API 접근 권한이 있는 OpenAI 계정 (ChatGPT Plus와 별도, 구독에 API 크레딧 미포함)
유료 Tier (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 헤더에 Bearer 토큰으로 전달합니다. 모든 요청은 JSON 본문에 모델 ID, 프롬프트, 출력 매개변수를 포함해야 합니다.

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, 실패 시 표준 OpenAI 오류 응답(code 및 message 포함)을 반환합니다. 주요 오류는 아래에서 다룹니다.

요청 매개변수

아래 표는 gpt-image-2의 전체 매개변수 맵입니다. 각 필드는 비용과 결과에 직접 영향을 줍니다.

매개변수	유형	값	참고
`model`	문자열	`gpt-image-2`	필수.
`prompt`	문자열	최대 32,000자	필수. 프롬프트가 길수록 입력 토큰 증가.
`size`	문자열	`1024x1024`, `1024x1536`, `1536x1024`, `2000x1000`, `1000x2000`, `2000x667`, `667x2000`	출력 토큰 수에 영향.
`quality`	문자열	`standard`, `high`	`high`는 2배 비용, 텍스트/디테일 우수.
`n`	정수	1–10	배치 요청, 스타일 공유.
`thinking`	문자열	`off`, `low`, `medium`, `high`	추론 예산 (아래 참고).
`response_format`	문자열	`url`, `b64_json`	URL은 1시간 후 만료.
`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)로 바로 호출할 수 있습니다:

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`);

공식 SDK를 사용하면 fetch 대비 재시도, 멱등성, 스트리밍, 스키마 변경 추적이 쉬워집니다.

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

thinking은 이미지 생성 전 레이아웃/계획 추론에 소모할 연산량을 제어합니다.

off: 추론 없음. 빠르고 저렴. 자유로운 창작 프롬프트에 적합.
low: 기본 계획. 제품 사진·히어로 이미지에 적합(기본값).
medium: 더 많은 계획. 다이어그램, 인포그래픽, "4개 패널" 등 개수·위치 제약에 적합.
high: 최대 추론. 복잡한 다국어 레이아웃, 엄격한 기술 다이어그램에만 사용. 속도·비용 증가.

실전 팁: 프롬프트에 숫자·레이블·위치 제약이 있다면 한 단계 올리고, 자유로운 묘사라면 내리십시오.

사고 모드는 이미지 토큰 외에 추가 추론 토큰 비용이 붙습니다. OpenAI 가격 기준, medium/high 사용 시 이미지당 1.2~2배 예산을 고려하십시오.

배치 생성

n>1로 호출하면 동일한 프롬프트, 스타일을 공유하는 여러 이미지를 한 응답에서 반환합니다. 단순 병렬 호출과 달리, 배치 생성은 일관된 결과를 제공합니다.

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면 4배). 일관성 확보 목적에 유용합니다.

응답 형식 및 저장

b64_json: 응답에 이미지 인라인 포함. 스크립트/자동화에 편리. 대용량 응답(최대 3MB 이상) 유의.
url: OpenAI CDN에 1시간 저장, 직접 다운로드 방식. 서버리스, 자체 스토리지 파이프라인에 적합.

실 서비스는 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 서버 일시 문제	지수적 백오프 2회 재시도
503	`overloaded`	지역 급증	대기 후 재시도

속도 제한은 등급별로 다릅니다. Tier 1은 분당 약 50회, 상위 등급은 그 이상 가능합니다. x-ratelimit-remaining-requests, x-ratelimit-remaining-tokens 헤더를 읽고, 한도 도달 전 스로틀링 로직을 구현하십시오.

재시도 로직 예시(Python):

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 및 https://api.openai.com/v1/images/generations 설정
Authorization: Bearer {{OPENAI_API_KEY}} 헤더 추가, 키는 환경 변수로 관리
JSON 본문 입력(프롬프트 포함), Apidog가 OpenAPI 스펙으로 타입 유효성 검사
전송 클릭, 인라인 이미지 미리보기. 좋은 이미지는 저장, 나쁜 이미지는 태그 후 변형 요청으로 포크
thinking: off, medium, high별 환경 저장, 동일 프롬프트를 추론 레벨별로 쉽게 비교

Apidog의 요청 diff/비교 기능으로, 매개변수 조정 전후 이미지를 나란히 보고, 팀 프롬프트 라이브러리에 최적화된 결과를 바로 커밋할 수 있습니다.

Postman 등 일반 HTTP 클라이언트에서 전환하려면 Apidog 다운로드 후 OpenAI 키만 지정하면 5분 내로 바로 테스트 환경이 완성됩니다. 대안 검토 중인 경우 Postman 없이 API 테스트 가이드, VS Code 확장 개요도 참고하십시오.

흔한 실수

텍스트/레이블 많은 프롬프트에 quality: "standard" 사용: 표준 품질은 작은 텍스트 품질이 낮으니, 텍스트 중요시 high 사용.
과도한 프롬프트: 32k자는 한계치일 뿐, 500단어 미만 유지·복잡 제약은 thinking으로.
seed로 완전 재현 기대: 시드는 분산만 줄임, 완전 동일 이미지는 캐싱 필요.
OpenAI URL 제공: 1시간 후 만료. 반드시 자체 스토리지로 복사 후 제공.
반복문에서 직렬 호출: 이미지 생성은 느림. 작업자 병렬화, 속도 제한 헤더 준수 필요.

자주 묻는 질문

API 수준에서 gpt-image-2와 gpt-image-1 차이점은? 동일 엔드포인트·인증, 새로운 thinking 파라미터, 최대 2000px size, n=10까지 지원. 기존 SDK도 모델 ID만 바꿔 계속 사용 가능. 전체 차이는 ChatGPT 이미지 2.0 개요 참고.

가장 빠른 프로토타이핑 방법은? Apidog에서 요청 생성, 사고 모드별 환경 저장, 코드 없이 프롬프트 반복 후 최종 요청만 curl/SDK로 내보내기.

이미지 편집/인페인팅 지원? 편집·변형 엔드포인트는 기존과 동일. 최신 스키마는 gpt-image-2 모델 참조에서 확인.

상업적 출력 사용 가능? 예, OpenAI 표준 정책 내에서 가능. 생성 이미지는 사용자 소유. 단, 상표/유명인 등은 여전히 보호장치 적용.

프로덕션 워크로드 비용? 1024x1024 고품질 이미지당 약 $0.21, 1만 장 = $2,100(사고 모드 미포함). 사고 모드 사용 시 20~80% 추가. 예산 우선이면 GLM 5V Turbo, Qwen 3.5 Omni 대안도 비교.

동일 품질의 더 저렴한 대안? 아직 다국어 텍스트 품질까지 대체 가능한 오픈모델은 없음. 구성력은 따라잡았으나, CJK/인도어 스크립트는 미흡.

DEV Community