GPT Image 2 API와 Codex: 먼저 경로를 정해야 한다

GPT Image 2를 도입할 때 첫 질문은 “어떤 예제 코드를 붙여 넣을까”가 아니라 “이번 이미지 작업을 어떤 경로가 책임지는가”입니다. 한 장을 직접 생성하거나 기존 이미지를 편집하는 일이라면 Images API가 출발점입니다. 사용자가 assistant와 대화하고, 모델이 필요할 때 이미지를 만드는 구조라면 Responses의 image_generation 도구가 맞습니다. 문서용 커버, 설명 보드, UI 스케치처럼 저장소 안에서 검토할 시각 자료를 만들 때는 Codex 작업 흐름이 유용합니다. 통합 과금, 대체 접속, 여러 모델 라우팅이 목적이라면 외부 게이트웨이는 별도 계약의 선택지입니다.

같은 GPT Image 2라는 이름이 여러 곳에 보이기 때문에 이 구분이 흐려집니다. 하지만 구현면은 다릅니다. 흔한 실수는 gpt-image-2를 Responses의 최상위 model로 넣거나, Codex 사용량을 OpenAI API key 과금과 같은 것으로 설명하거나, 외부 게이트웨이 가격을 OpenAI 공식 가격처럼 쓰는 것입니다. 먼저 경로를 정하고, 그 다음 요청 형식과 로그 항목, 비용 설명을 맞추는 편이 안전합니다.

코드보다 먼저 경로 표를 확인한다

백엔드가 이미지 한 장을 바로 만들어야 한다면 Images API가 가장 간단합니다. API key, project, 모델 접근 권한, size, quality, 출력 저장, 오류 처리를 좁은 범위에서 확인할 수 있습니다. 반대로 사용자가 대화 속에서 요구사항을 말하고, 모델이 문맥을 판단한 뒤 이미지를 만들고, 이후 텍스트나 파일 작업을 이어가야 한다면 Responses가 더 자연스럽습니다. Codex는 또 다른 경우입니다. 공개 API endpoint라기보다 저장소 안에서 prompt, 생성 파일, 검토, publish path를 함께 다루는 작업 흐름에 가깝습니다.

이 표는 제품 이름을 외우기 위한 것이 아닙니다. 이미지 작업의 소유권을 분리하기 위한 것입니다. Images API는 직접 이미지 생성과 편집을 소유합니다. Responses는 도구 호출을 포함한 대화형 흐름을 소유합니다. Codex는 저장소 안의 파일 제작과 리뷰를 소유합니다. 외부 게이트웨이는 접속과 과금의 별도 계약을 소유합니다. 이 소유권을 먼저 정하면 구현과 문서가 동시에 정리됩니다.

직접 생성과 편집은 Images API부터 시작한다

GPT Image 2의 공식 모델 ID는 gpt-image-2입니다. 요구사항이 “이미지 한 장을 만들어 달라” 또는 “이 이미지를 바꿔 달라”에 가깝다면, 가장 깨끗한 첫 구현은 Images API입니다. endpoint와 모델 필드가 분명하고, 출력 저장과 오류 원인도 비교적 좁은 범위에서 볼 수 있습니다. 첫 통합 단계에서는 이 좁은 범위가 매우 중요합니다.

첫 요청은 일부러 단순해야 합니다. 투명 배경, 여러 참고 이미지, streaming, Responses tool call, 게이트웨이 fallback을 한 번에 넣지 마세요. 하나의 prompt, 하나의 size, 하나의 quality로 접근 권한과 출력 저장을 검증합니다. 조직 인증이 필요한지, project 설정이 맞는지, 모델 접근 권한이 열려 있는지, payload가 공식 형식에 맞는지를 먼저 확인합니다.

ts
import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const image = await client.images.generate({
  model: "gpt-image-2",
  prompt: "Create a clean route map for a developer documentation page.",
  size: "1024x1024",
  quality: "medium"
});

편집도 같은 원칙입니다. 입력 이미지를 기반으로 새 이미지를 만드는 것이 핵심이라면 Images API edits를 먼저 봅니다. Responses는 이미지 생성이 대화, 추론, 다른 도구, 후속 처리의 일부일 때 선택합니다. “새 API처럼 보인다”는 이유만으로 Responses를 먼저 선택하면, 오류가 tool 설정 문제인지, 모델 접근 문제인지, 출력 추출 문제인지 구분하기 어려워집니다.

한국어 독자에게는 접근 권한 설명도 중요합니다. GPT Image 계열 모델은 조직 인증이 필요할 수 있습니다. 어떤 커뮤니티 글에서 즉시 사용 가능하다고 보여도 내 project에서 곧바로 된다는 뜻은 아닙니다. 문서에는 API key, organization, project, billing, model access를 함께 확인하라고 적는 편이 더 안전합니다.

Responses는 assistant 흐름을 위한 경로다

Responses의 image_generation 도구는 이미지가 더 큰 작업 흐름의 일부일 때 적합합니다. 예를 들어 사용자가 제품 카드 콘셉트를 요청하고, 모델이 문구를 정리하고, 필요한 순간 이미지 도구를 호출한 뒤, 저장이나 배포 안내까지 이어가는 구조입니다. 이때 최상위 모델은 요청을 이해하고 도구 사용을 결정하며, 이미지 도구가 실제 이미지를 생성합니다.

따라서 핵심 규칙은 분명합니다. gpt-image-2를 Responses의 최상위 model로 넣지 않습니다. 최상위에는 텍스트와 추론을 담당하는 모델을 두고, 이미지 모델 지정은 image_generation 도구 쪽에 둡니다. 이 구분이 없으면 코드가 짧아 보여도 실제 장애 분석은 더 복잡해집니다.

ts
const response = await client.responses.create({
  model: "gpt-5.4",
  input: "Plan a product launch card and generate one square image for it.",
  tools: [{ type: "image_generation", model: "gpt-image-2" }]
});

Responses를 쓰면 이미지 생성 앞뒤의 문맥을 하나의 response flow로 묶을 수 있습니다. 하지만 단순한 “이미지 생성” 버튼에는 과할 수 있습니다. tool result 추출, 출력 파일 저장, 중간 상태 표시, 재시도, 과금 설명을 모두 설계해야 하기 때문입니다. 첫 번째 안정적인 이미지 호출이 목표라면 Images API가 더 빠르고 검증하기 쉽습니다.

Codex는 저장소 안의 시각 자료 제작에 강하다

한국어 자료에서도 Codex와 GPT Image 2를 함께 다루는 영상이나 글이 눈에 띕니다. 이것은 자연스러운 흐름입니다. Codex는 개발 중인 저장소 맥락을 알고, 커버 이미지, README 그림, UI 설명 보드, 문서용 이미지 같은 파일을 만들고 검토하기 좋습니다. prompt와 생성 파일, 게시 파일, 본문 참조를 같은 작업 단위에 남길 수 있다는 점이 장점입니다.

하지만 이것은 제품 백엔드의 공개 API 호출과 다릅니다. 사용자가 앱에서 버튼을 누르고, 서버가 이미지를 생성하고, 결과를 저장하고, 비용을 기록하고, 실패를 재시도하는 시스템이라면 Images API나 Responses 중 하나를 선택해야 합니다. Codex는 그런 시스템을 설명하는 이름이 아니라, 저장소 안에서 asset을 만드는 작업 환경입니다.

이 차이는 단순한 표현 문제가 아닙니다. 책임의 차이입니다. Codex로 만든 문서 이미지는 사람이 확인하고 반영하는 경우가 많습니다. 본番 API는 사용자 요청에 자동 응답하고, 로그, 저장, 삭제, 재시도, 비용 정산을 처리해야 합니다. 같은 모델 이름을 보더라도 운영 책임이 다릅니다.

비용은 세 개의 계정으로 나눠야 한다

GPT Image 2의 비용 설명은 세 층으로 나누는 것이 안전합니다. 첫 번째는 OpenAI API 공식 가격입니다. Images API나 Responses를 API key로 호출할 때의 비용입니다. 두 번째는 Codex 또는 ChatGPT plan의 credit과 제한입니다. Codex 작업 흐름에서 이미지나 파일을 만들 때의 한도입니다. 세 번째는 외부 게이트웨이 가격입니다. 이 가격은 그 게이트웨이의 routing, 결제, 제한, 지원 조건에 속합니다.

이 세 층을 섞으면 예산과 문서가 틀어집니다. 게이트웨이 단가가 OpenAI 공식 가격이 되는 것은 아닙니다. Codex credit이 제품 백엔드의 API 무료 호출량이 되는 것도 아닙니다. 공식 API의 품질별 가격 예시는 외부 게이트웨이 계약에 자동 적용되지 않습니다. 비용 표를 만들 때는 가장 먼저 “이 가격의 주인은 누구인가”를 적어야 합니다.

외부 게이트웨이는 통합 key, 로컬 결제, 예비 경로, 다중 모델 routing, 팀 단위 청구를 줄이고 싶을 때 의미가 있습니다. 그런 문맥에서는 laozhang.ai를 별도 API gateway 경로로 언급하고 docs.laozhang.ai나 api.laozhang.ai를 더 확인할 문서로 연결할 수 있습니다. 다만 현재 확인하지 않은 속도 보장, 무제한, 계정 정지 없음, 환불 보장, 실패 시 무료 같은 주장은 쓰지 않아야 합니다.

운영 전에 반드시 남겨야 할 로그

어떤 경로를 선택하든 production에서는 나중에 설명 가능한 로그가 필요합니다. 최소한 route, model ID, quality, size, 입력 이미지 수, 출력 형식, request ID, output ID, 저장 경로, 비용, user/project, retry count, error code, account readiness를 남겨야 합니다. 이미지는 텍스트보다 재현성이 낮기 때문에 결과 파일만 저장해서는 부족합니다. 어떤 조건에서 만들어졌는지 함께 남겨야 합니다.

기능 경계도 UI에 반영해야 합니다. GPT Image 2는 현재 transparent background를 지원하지 않습니다. 투명 배경이 꼭 필요한 제품이라면 GPT Image 2 경로의 일반 옵션으로 보여주지 말고, 다른 경로로 분리하거나 사용할 수 없다고 안내해야 합니다. 실패할 요청을 UI에 남겨두는 것은 사용자 경험과 비용 모두에 좋지 않습니다.

streaming 또는 partial output을 사용할 때도 정책이 필요합니다. 중간 상태를 보여줄지, 실패한 결과물을 저장할지, 재시도 비용을 누구에게 귀속할지, 실패한 요청의 output ID를 어떻게 처리할지 결정해야 합니다. 이 부분이 있어야 문서가 단순한 출시 소개가 아니라 실제 구현 가이드가 됩니다.

GPT Image 1.5에서 옮길 때도 경로를 다시 봐야 한다

이미 GPT Image 1.5 또는 이전 이미지 모델 통합이 있다면, 모델 문자열만 바꾸고 끝내면 안 됩니다. 기존 시스템이 direct Images API였는지, Responses tool flow였는지, Codex asset workflow였는지, 외부 gateway였는지 먼저 확인해야 합니다. 경로가 바뀌면 요청 필드, 저장 구조, 비용 설명, 실패 재시도, 지원하지 않는 기능의 처리도 달라집니다.

기존의 OpenAI 이미지 생성 API endpoint, OpenAI 이미지 편집 API, OpenAI 이미지 생성 API cURL은 일반적인 endpoint 이해에 유용합니다. GPT Image 2에서는 더 좁은 문제가 남습니다. API, Responses, Codex, provider 문맥에 동시에 등장할 때 어느 경로가 내 작업을 책임지는지 정하는 문제입니다.

마이그레이션 리뷰에서는 세 가지를 확인합니다. 사용자 경험이 단발성 이미지 생성인지 assistant 작업인지. 결과가 production storage와 billing으로 들어가는지. 가격, 제한, 기능 지원에 대한 문장이 현재 확인 가능한 출처와 맞는지. 이 세 가지가 맞으면 최소한 경로 선택으로 인한 큰 사고는 줄일 수 있습니다.

자주 묻는 질문

GPT Image 2는 Codex에서만 쓸 수 있나요?

아닙니다. Codex는 저장소 안의 시각 자료 제작에 좋은 작업 흐름입니다. 제품 백엔드에서 직접 생성하거나 편집하려면 Images API를 봐야 합니다. Codex라는 이름으로 public API route를 대신 설명하면 안 됩니다.

Responses의 최상위 model에 gpt-image-2를 넣어도 되나요?

일반적으로 피해야 합니다. Responses에서는 최상위 모델이 대화와 판단을 맡고, 이미지 생성은 image_generation 도구가 맡습니다. gpt-image-2는 이미지 도구나 Images API의 model field에 두는 편이 자연스럽습니다.

OpenAI API 가격과 Codex credit은 어떻게 다르나요?

OpenAI API 가격은 API key로 Images API나 Responses를 호출할 때의 가격입니다. Codex credit이나 plan limit은 Codex 작업 흐름에서 파일과 이미지를 만들 때의 한도입니다. 외부 게이트웨이 가격은 또 다른 계약입니다.

GPT Image 2는 transparent background를 지원하나요?

현재는 지원하지 않습니다. 투명 배경이 필요한 제품이면 GPT Image 2 경로에서 일반 옵션으로 제공하지 말고, 별도 경로나 지원 불가 안내로 분리해야 합니다.

외부 게이트웨이는 언제 필요하나요?

통합 접속, 로컬 결제, 예비 경로, 다중 모델 routing, 팀 결제 같은 현실적인 이유가 있을 때입니다. 공식 OpenAI API가 접근, 비용, 준수 요건을 만족한다면 공식 경로가 더 단순합니다.

일반 endpoint 가이드와 무엇이 다른가요?

일반 endpoint 가이드는 어떤 path를 호출할지 답합니다. GPT Image 2의 경로 판단은 API, Responses, Codex, gateway 문맥에 동시에 보일 때 어떤 경로가 작업을 소유하는지 답해야 합니다. 경로를 잘못 고르면 demo는 동작해도 권한, 과금, 운영 설명에서 막힐 수 있습니다.