OpenAI 이미지 생성 API 엔드포인트: 무엇을 써야 할까

지금 OpenAI 이미지 생성을 붙이려면, 가장 안전한 기본 출발점은 Responses가 아니라 직접 Images API입니다. 한 번의 요청으로 이미지를 만들 때는 POST /v1/images/generations, 기존 이미지를 수정할 때는 POST /v1/images/edits, 그리고 이미지 생성이 더 큰 멀티모달 또는 agent 워크플로의 한 단계일 때만 Responses의 image_generation tool로 이동하는 편이 맞습니다.

이 구분이 중요한 이유는 OpenAI의 현재 문서가 답을 여러 페이지에 흩어 놓고 있기 때문입니다. image generation guide는 Images API와 Responses API의 역할을 설명하고, Images API reference는 원시 경로를 보여 주며, image_generation tool guide는 Responses 안에서의 이미지 생성을 설명합니다. 그런데 2026년 3월 23일 기준 공식 Images and vision 페이지에는 아직 최신 이미지 생성 모델이 gpt-image-1이라고 적혀 있어 현재 모델 카탈로그와 어긋납니다.

그래서 이 키워드에 필요한 것은 단순한 URL 하나가 아닙니다. 진짜 필요한 것은 내가 지금 하는 작업을 어느 API surface에서 시작해야 하는지를 정하는 규칙입니다. 먼저 “이미지 한 장을 안정적으로 받을 수 있느냐”를 확인하고 싶다면 직접 Images API부터 시작하는 편이 맞습니다. 이후 대화 상태, 다른 도구, 추론 모델과 함께 이미지 생성을 엮어야 할 때 Responses로 옮기면 됩니다.

현재 OpenAI 이미지 엔드포인트를 한 표로 정리하면

현재 OpenAI의 이미지 스택은 직접 이미지 작업과 도구 중심 멀티모달 오케스트레이션을 분리해서 보면 훨씬 쉽게 이해됩니다.

이 표가 가장 실용적인 이유는 OpenAI의 현재 문서 구성을 그대로 반영하기 때문입니다. image generation guide는 크게 두 가지 경로가 있다고 설명하고, 단일 이미지 작업은 Image API로 유도합니다. 반면 Responses용 tool guide는 이미지 생성이 더 큰 추론 흐름의 일부일 때를 다룹니다.

실무 규칙은 단순합니다. 명확한 이유가 없다면 먼저 직접 Images API로 시작하라. 그래야 첫 요청도, 팀 내 재현도, 디버깅의 분리도 훨씬 쉬워집니다.

모델 선택 자체가 아직 애매하다면, 먼저 같은 언어의 OpenAI image generation API models를 보는 편이 좋습니다. 이 페이지는 deliberately 더 좁고, surface 선택에만 집중합니다.

단발 생성은 POST /v1/images/generations부터 시작하라

대부분의 새 통합에서 이 엔드포인트는 첫 확인용으로 가장 좋습니다. 현재 Images API reference는 생성용 원시 엔드포인트를 **POST /images/generations**로 제시하고, 실제 호출은 **https://api.openai.com/v1/images/generations**가 됩니다. 모델 기본값은 GPT Image 1.5 모델 페이지를 기준으로 잡는 것이 가장 안전합니다.

첫 요청은 일부러 단순해야 합니다. 하나의 프롬프트, 정사각형 사이즈, 현재 주력 모델. 이것만으로도 API key, project, model access, payload shape가 정상인지 확인할 수 있습니다. 처음부터 투명 배경, 다중 이미지 편집, Responses, 출력 형식을 한꺼번에 해결하려고 하면 문제 위치를 파악하기가 훨씬 어려워집니다.

가장 짧은 cURL 예시는 다음과 같습니다.

bash
curl https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-1.5",
    "prompt": "Create a clean editorial illustration of a robot camera operator in a bright studio",
    "size": "1024x1024",
    "quality": "medium"
  }'

JavaScript SDK 대응은 거의 그대로입니다.

js
import OpenAI from "openai";

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

const result = await client.images.generate({
  model: "gpt-image-1.5",
  prompt: "Create a clean editorial illustration of a robot camera operator in a bright studio",
  size: "1024x1024",
  quality: "medium",
});

여기서 약한 글들이 자주 놓치는 실무 포인트가 하나 있습니다. 현재 Images API reference에 따르면 GPT Image 계열은 기본적으로 b64_json 을 돌려줍니다. 즉 첫 번째 “성공”은 HTTP 200을 보는 것으로 끝나지 않고, 그 응답을 decode해 저장하거나 전달할 수 있는지까지 포함해서 확인해야 합니다. 그래서 첫 단계는 직접 endpoint가 더 유리합니다. 요청에서 실제로 쓸 수 있는 이미지까지 가는 가장 짧은 루프가 가장 잘 보이기 때문입니다.

JavaScript, Python, cURL 전체 예제를 더 보고 싶다면 같은 언어의 OpenAI image generation API example로 이어서 보면 됩니다. 이 endpoint 글의 역할은 어디까지나 “어느 surface에서 시작할지”를 먼저 고정하는 것입니다.

입력 이미지가 있다면 POST /v1/images/edits를 사용하라

“image generation endpoint”를 찾는 사람 중 상당수는 실제로는 순수 생성보다 “이미 있는 이미지를 어떻게 바꿔야 하나”를 해결하려고 합니다. 이 경우에도 현재 더 나은 경로는 여전히 직접 Images API입니다. 단지 생성 branch에서 편집 branch로 바뀔 뿐입니다.

Images API reference는 **POST /images/edits**를 편집 endpoint로 명시하고, 메인 image generation guide도 GPT Image 1.5의 edit 예시를 같은 surface에서 안내합니다. 이 점이 중요한 이유는, 이미지 편집이 곧바로 Responses로 가야 한다는 뜻이 아니라는 것을 보여 주기 때문입니다.

SDK 최소형은 이렇게 생겼습니다.

js
import fs from "fs";
import OpenAI from "openai";

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

const result = await client.images.edit({
  model: "gpt-image-1.5",
  image: [fs.createReadStream("product-shot.png")],
  prompt: "Keep the product shape, but place it on a clean studio shelf with warm lighting",
  input_fidelity: "high",
});

input_fidelity: "high"를 endpoint 글에서도 언급해야 하는 이유는, 직접 edit 경로가 “가벼운 버전”이 아니라는 점을 보여 주기 때문입니다. 이것이 OpenAI가 현재 제공하는 정식 이미지 편집 main path입니다. 여기서 벗어날 이유가 있다면 그것은 이미지 작업이 복잡해서가 아니라, 워크플로 자체가 더 커졌기 때문입니다.

약한 튜토리얼은 이미지 작업이 조금만 복잡해져도 모든 것을 Responses로 몰아갑니다. 그러면 학습 비용이 불필요하게 올라갑니다. 작업의 본질이 여전히 “이 이미지를 바꿔라”라면, 직접 Images API가 request shape와 디버깅 양쪽에서 더 명확한 경우가 많습니다.

mask, input_fidelity, preservation, multi-image compositing까지 더 깊게 보고 싶다면 같은 언어의 OpenAI image editing API를 보면 충분합니다. 이 페이지가 고정해야 하는 핵심은 편집은 Images API의 1급 use case이며, 그 자체로 Responses로 이동할 이유는 아니다라는 점입니다.

이미지 생성이 더 큰 흐름의 일부일 때만 Responses로 옮겨라

Responses의 가치는 “더 최신”이라는 점이 아니라, 더 큰 워크플로에 맞는다는 점입니다. 제품이 지시를 읽고, 다른 tool을 호출하고, 대화 상태를 유지하면서 그 일부로 이미지를 생성해야 한다면, image_generation tool은 직접 endpoint보다 더 자연스러운 추상화가 됩니다.

이때 가장 흔한 구현 실수는 gpt-image-1.5를 Responses 최상위 model에 넣는 것입니다. 현재 image_generation tool guide는 GPT Image 모델이 tool 뒤에서 사용되지만, 최상위 model 값으로는 유효하지 않다고 분명히 설명합니다.

형태는 보통 이렇게 됩니다.

js
import OpenAI from "openai";

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

const response = await client.responses.create({
  model: "gpt-5",
  input: "Generate a transparent sticker-style icon of a paper airplane for a travel app",
  tools: [{ type: "image_generation", background: "transparent", quality: "high" }],
});

이 경로는 올바르지만, 해결하는 문제는 직접 Images API와 다릅니다. 적합한 경우는 다음과 같습니다.

1. 하나의 요청이 텍스트와 이미지를 함께 반환할 수 있을 때
2. 이미지 생성이 여러 tool 중 하나일 때
3. 모델이 언제 이미지를 만들고 언제 계속 추론할지 스스로 판단해야 할 때

반대로 지금 고민이 단순히 “어느 endpoint에서 시작해야 하나”라면 Responses는 층을 너무 많이 늘립니다. 상위 모델, tool invocation, tool output parsing, 더 간접적인 디버깅이 모두 추가되기 때문입니다.

그래서 원칙은 “Responses가 더 새롭기 때문에 우선”이 아닙니다. 오케스트레이션 자체가 진짜 문제일 때만 Responses가 더 낫다는 것이 정확한 규칙입니다.

이후 더 넓은 도입 흐름을 이어서 보고 싶다면, 같은 언어의 OpenAI Image API tutorial을 읽는 편이 자연스럽습니다.

문서 불일치와 접근 확인 때문에 맞는 endpoint가 틀려 보일 수 있다

여기가 현재 SERP가 가장 약한 부분입니다. 많은 개발자가 endpoint를 잘못 골랐다고 생각하지만, 실제 문제는 문서의 신선도 불일치나 계정 접근 상태인 경우가 많습니다.

먼저 신선도 문제입니다. 2026년 3월 23일 기준으로 all-model catalog는 GPT Image 1.5를 현재 이미지 라인으로 보여 주고, GPT Image 1.5 모델 페이지도 이를 current flagship으로 취급합니다. 하지만 공식 Images and vision에는 아직 최신 이미지 생성 모델이 **gpt-image-1**로 남아 있습니다. 오래된 cookbook example도 gpt-image-1를 사용합니다.

이것은 공식 문서를 버리라는 뜻이 아닙니다. 뜻은, 페이지마다 해결해야 하는 질문이 다르다는 것입니다.

1. 원시 path 는 API reference에서 본다
2. 현재 어떤 모델이 main line인지 는 all-model catalog와 GPT Image 1.5 page에서 본다
3. Images API를 쓸지 Responses를 쓸지 는 main guide에서 판단한다
4. 실제로 Responses를 구현할 때만 tool guide를 본다

다음은 접근 문제입니다. GPT Image 1.5 페이지는 Free not supported라고 명시하고, 공개 제한은 Tier 1의 100,000 TPM과 5 IPM부터 시작합니다. API model availability는 gpt-image-1와 gpt-image-1-mini의 접근이 tier 1 through 5와 organization verification에 연결될 수 있다고 덧붙입니다. 즉 endpoint가 맞아도 계정이 ready가 아니면 실패합니다.

검색 결과에는 rollout 시기의 노이즈도 남아 있습니다. OpenAI의 GPT Image 1.5 rollout thread에는 model-not-found나 가시성 문제 보고가 있었습니다. 이런 정보는 오래된 튜토리얼, 포럼 답변, 캐시된 조각에 오래 남습니다.

그래서 더 안전한 디버깅 순서는 다음과 같습니다.

1. 먼저 경로가 맞는지 확인한다. Images API 먼저, Responses는 필요할 때만
2. 다음으로 모델 기본값이 현재 기준인지 확인한다. GPT Image 1.5를 기준으로 둔다
3. 그다음 tier, active org, verification을 점검한다
4. 마지막으로 payload나 SDK 코드를 의심한다

실제 문제는 access인데 endpoint를 계속 바꾸고 있다면, 더 적절한 다음 글은 같은 언어의 OpenAI image generation API verification입니다. 대부분의 경우 endpoint를 바꾸는 것으로는 그 문제가 해결되지 않습니다.

최종 추천

2026년 3월 23일 기준으로 짧게 기억해야 한다면 이 순서면 충분합니다.

• 단발 생성은 POST /v1/images/generations
• 입력 이미지 편집은 POST /v1/images/edits
• 이미지 생성이 더 큰 멀티모달 처리의 일부일 때만 Responses + image_generation
• 원시 path는 reference, 최신성은 model catalog와 GPT Image 1.5 page를 기준으로 본다

이 순서가 현재 page one 평균보다 나은 이유는, 공식 사실을 단순 나열하는 대신 실제 구현 결정으로 바꿔 주기 때문입니다. 상위 결과 다수는 여전히 reference, help page, 오래된 예제, 최신 guide 사이를 독자가 직접 꿰매게 만듭니다. 더 안전한 방법은 먼저 surface를 고르고, 최소한의 직접 요청을 성공시키고, 그다음 제품에 정말 필요한 복잡성만 추가하는 것입니다.

FAQ

일반적인 이미지 편집에도 Responses가 필요합니까?

아닙니다. 일반적인 edit workflow라면 현재 OpenAI 문서는 POST /v1/images/edits와 client.images.edit()를 기본 경로로 다룹니다. Responses가 더 적합한 것은 이미지 편집이 더 큰 assistant/agent 흐름의 일부일 때입니다.

일부 공식 페이지에 gpt-image-1가 남아 있으면 아직 그것을 써야 하나요?

새 프로젝트의 기본값으로는 권하지 않습니다. 2026년 3월 23일 기준 all-model catalog와 GPT Image 1.5 page는 GPT Image 1.5를 현재 라인으로 다룹니다. gpt-image-1는 migration 또는 legacy comparison 맥락으로 남아 있다고 보는 편이 안전합니다.

endpoint는 맞는데 왜 호출이 계속 실패하나요?

endpoint routing과 account readiness는 다른 문제이기 때문입니다. GPT Image 1.5 page는 Free 비지원 상태를 보여 주고, availability guidance도 일부 접근이 paid tier와 organization verification에 묶일 수 있음을 보여 줍니다. route가 맞아 보이면 먼저 access를 점검하세요.