OpenAI Image Generation API Example: 지금 바로 쓸 수 있는 JavaScript, Python, cURL

지금 OpenAI image generation API example 을 찾고 있다면, 가장 안전한 시작점은 Images API 와 gpt-image-1.5 입니다. 2026년 3월 23일 기준으로도 단순한 이미지 생성 요청을 가장 빠르게 통과시키는 기본 경로는 여전히 이 조합입니다. Responses API 는 이미지 생성이 더 큰 멀티모달 workflow 안의 tool 일 때만 선택하면 됩니다.

이 주제가 계속 헷갈리는 이유는 SDK 문법보다도 답이 여러 문서에 흩어져 있기 때문입니다. 메인 image generation guide는 직접 생성과 편집을 다루고, image_generation tool guide는 responses.create() 안에서의 tool 호출을 다룹니다. Images API reference는 raw endpoint 와 request shape 를 확인하는 곳입니다. 한 페이지만 읽으면 멀쩡해 보이는 코드를 잘못된 surface 에 붙이기 쉽습니다.

가장 안전한 순서는 단순합니다. 먼저 직접 생성 요청 한 번을 성공시키고, 반환된 base64 이미지를 파일로 저장하는 데까지 확인합니다. 그 다음에 edits, 투명 배경, 압축, streaming 을 추가합니다. conversation state, tools, 멀티모달 orchestration 이 정말 필요해졌을 때만 Responses 로 넘어가면 됩니다.

가장 빠르게 동작하는 OpenAI image generation API 예제

이 키워드에서는 Images API가 가장 좋은 출발점입니다. 현재 endpoint 는 POST /v1/images/generations 이고, 새 예제의 기본 model ID 로 가장 적절한 값은 gpt-image-1.5 입니다. 이미지를 한 장 생성해 저장하고 싶은 것뿐이라면 처음부터 assistant workflow로 문제를 키울 필요가 없습니다.

기억하기 쉬운 흐름은 이렇습니다.

• prompt 를 보낸다
• base64 이미지 데이터를 받는다
• decode 한다
• 로컬 파일로 저장한다

JavaScript 최소 예제:

js
import fs from "fs";
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",
});

const imageBase64 = result.data[0].b64_json;
const imageBuffer = Buffer.from(imageBase64, "base64");
fs.writeFileSync("openai-image-example.png", imageBuffer);

Python 예제:

python
from openai import OpenAI
import base64

client = OpenAI()

result = 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",
)

image_base64 = result.data[0].b64_json
image_bytes = base64.b64decode(image_base64)

with open("openai-image-example.png", "wb") as f:
    f.write(image_bytes)

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"
  }' \
  | jq -r '.data[0].b64_json' \
  | base64 --decode > openai-image-example.png

환경에 따라 base64 --decode 가 없을 수 있으니, 그 경우 시스템에 맞는 플래그로 바꿔 주세요. macOS 에서는 보통 base64 -D 입니다.

이 예제가 좋은 이유는 현재의 direct contract 를 가장 짧게 보여주기 때문입니다. tool orchestration 을 너무 일찍 끌어오지 않아도 됩니다. 또 오래된 글들이 자주 놓치는 사실 하나는 GPT image models 는 기본적으로 hosted URL 이 아니라 base64 image data 를 반환한다는 점입니다. 그래서 쓸모 있는 첫 예제는 request 뿐 아니라 decode 와 저장까지 보여줘야 합니다.

Images API 와 Responses 는 어떻게 나눠 써야 하나

이미지를 생성하거나 편집하는 일 자체가 목적이라면 Images API 가 더 이해하기 쉽고 디버깅도 단순합니다. 텍스트, tools, 이미지, 대화 맥락을 함께 다루는 assistant 를 만든다면 Responses 가 더 자연스럽습니다.

page one 이 아직 충분히 직설적으로 말하지 않는 규칙은 이것입니다. Responses 가 더 새로워 보인다고 해서 첫 기본값으로 잡지 마세요. 멀티모달 orchestration 이 실제로 필요할 때만 Responses 로 가면 됩니다.

또 하나 자주 나오는 실수는 Responses 의 model 필드에 gpt-image-1.5 를 직접 넣는 것입니다. tool guide 에서 설명하듯이 GPT Image 는 image_generation tool 뒤에서 동작하고, 상위 model 에는 gpt-5 같은 reasoning model 이 들어갑니다.

이 차이는 디버깅 순서도 바꿉니다. Images API 에서는 access, payload, file write 를 먼저 보면 되지만, Responses 는 tool invocation 과 output parsing 도 봐야 합니다. 그래서 이 글의 첫 working example 은 direct Images API 에 고정했습니다.

더 넓은 라우팅 설명이 필요하다면 한국어 OpenAI Image API 튜토리얼 로 이어서 보는 편이 좋습니다.

코드 전에 access 와 model ID 를 확인하기

“예제가 고장 났다”처럼 보이는 문제의 상당수는 사실 코드가 아니라 access 문제입니다. 2026년 3월 23일 기준 GPT Image 1.5 모델 페이지는 Free not supported 를 명시하고 있고, Tier 1 starting at 100,000 TPM and 5 IPM 이라고 적혀 있습니다. 코드가 맞아도 model access 자체가 막힐 수 있다는 뜻입니다.

또 하나 중요한 점은 API model availability by usage tier and verification status 문서가 gpt-image-1 과 gpt-image-1-mini 가 tiers 1 through 5 의 API 사용자에게 제공되며, 일부 access 는 organization verification 의 영향을 받는다고 설명한다는 점입니다. 즉, 멀쩡해 보이는 예제를 복사했는데도 실패하면 먼저 account surface 를 확인해야 합니다.

확인 순서는 다음이 가장 안전합니다.

1. 최신 SDK 설치
2. OPENAI_API_KEY 확인
3. account 가 호환되는 usage tier 인지 확인
4. active organization 확인
5. current model name 확인
6. 그 다음 prompt 와 parameter 조정

Node.js:

bash
npm install openai

Python:

bash
pip install openai

verification 을 막 끝냈는데도 not verified 비슷한 오류가 계속 나오면, API Organization Verification 문서가 최대 30분 대기, 새 API key 생성, 세션 새로고침, 올바른 organization 확인 을 권장합니다. 이건 사소한 팁이 아니라 실제로 많이 걸리는 첫 번째 분기입니다.

실무적으로는 먼저 access, 다음 request shape, 마지막으로 prompt quality 순서로 보는 것이 맞습니다. 많은 개발자가 이 순서를 거꾸로 잡아서 시간을 낭비합니다.

API 를 바꾸지 않고 edits 와 output controls 추가하기

기본 예제가 돌아간 뒤에도 바로 Responses 로 갈 필요는 없습니다. image edits, transparent background, output tuning 은 그대로 direct Images API 에 속합니다.

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-photo.png"),
    fs.createReadStream("logo.png"),
  ],
  prompt: "Add the logo to the product box as if it were printed on the packaging.",
  input_fidelity: "high",
});

const imageBase64 = result.data[0].b64_json;
fs.writeFileSync("product-with-logo.png", Buffer.from(imageBase64, "base64"));

input_fidelity: "high" 는 입력 이미지의 디테일 보존이 중요할 때 유용하지만 image-token cost 를 늘립니다. 무조건 켜는 기본값이 아니라, 정말 fidelity 가 필요한 경우에만 쓰는 편이 안전합니다.

같은 direct API 에서 다음도 조정할 수 있습니다.

• size: 첫 테스트는 1024x1024
• quality: 초기 검증에는 medium
• background: GPT image models 의 png, webp 에서 transparent background 지원
• output_format: 파일 크기나 latency 가 중요하면 jpeg 또는 webp
• output_compression: JPEG / WebP 압축 제어

가장 실용적인 규칙은 첫 요청을 지루하게 유지하는 것입니다. 정사각형, medium quality, 단일 출력이 access, payload, decode, file write 중 어디가 문제인지 보기 쉽습니다. 그 다음에 transparency, high quality, multi-image edit 를 추가하면 됩니다.

운영 전 비용까지 보고 싶다면 한국어 OpenAI image generation API pricing guide 를 함께 보는 것이 좋습니다.

언제 Responses 로 넘어가야 하나

“이미지 한 장 생성”에서 “assistant 가 reasoning 하고 tools 를 호출하며 때때로 이미지를 반환”하는 수준으로 넘어가면, 그때 Responses 가 맞는 abstraction 입니다.

js
import fs from "fs";
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",
    },
  ],
});

const imageBase64 = response.output
  .filter((item) => item.type === "image_generation_call")
  .map((item) => item.result)[0];

fs.writeFileSync("paper-airplane.png", Buffer.from(imageBase64, "base64"));

이 예제는 맞는 코드지만, 해결하는 문제 자체가 다릅니다. 더 넓은 interaction 안에서 이미지 생성이 한 단계일 때 좋지, “우선 한 번 동작하는 예제가 필요하다”는 요구에 더 좋은 것은 아닙니다.

Responses 를 쓰는 편이 좋은 경우:

• 하나의 호출에서 텍스트와 이미지를 함께 반환할 수 있다
• 이미지 생성이 assistant workflow 의 tool 이다
• model 이 스스로 생성 시점을 판단해야 한다
• 이미지 단계가 다른 tools 와 나란히 존재한다

direct Images API 에 머무는 편이 좋은 경우:

• 가장 짧은 onboarding 이 필요하다
• backend endpoint 가 하나의 image task 만 담당한다
• generation / editing 을 디버깅 중이다
• 동료나 주니어에게 줄 가장 깔끔한 예제가 필요하다

Troubleshooting: 오래된 글이 자주 빼먹는 실패 패턴

첫 번째 실수는 오래된 model name 을 계속 쓰는 것입니다. 이 검색에서는 GPT Image 1 이나 DALL·E 시대 자료가 아직도 섞여 나옵니다. 오늘 새 direct example 을 만든다면 기본 이름은 gpt-image-1.5 여야 합니다.

두 번째 실수는 Responses 의 model 필드에 gpt-image-1.5 를 직접 넣는 것입니다. tool guide 가 설명하듯 GPT Image 는 image_generation tool 뒤에 있고, 상위 model 은 gpt-5 같은 mainline model 입니다.

세 번째 실수는 access error 를 code error 로 착각하는 것입니다. availability, permission, verification 관련 응답이 나오면 먼저 tier 와 organization verification 을 봐야 합니다. 이 분기를 더 자세히 보고 싶다면 한국어 verification guide 를 참고하세요.

네 번째 실수는 DALL·E 시절의 출력 방식을 기대하는 것입니다. GPT image models 에서 direct Images API 기본 출력은 base64 이므로 decode-and-save 가 필수입니다.

다섯 번째 실수는 첫 요청에서 모든 요구사항을 해결하려는 것입니다. portrait size, transparency, high quality, multi-image edits, assistant orchestration 을 한꺼번에 넣기보다, 먼저 direct path 가 동작하는지부터 증명하는 편이 훨씬 빠릅니다.

SDK 와 cURL 을 비교해보는 것도 좋습니다. 둘 다 같은 방식으로 실패하면 문제는 보통 앱 코드가 아니라 access, model naming, organization context 입니다. cURL 은 되는데 앱만 안 되면 environment variables, request parsing, file write 를 의심해야 합니다.

실무에서는 첫 번째 성공 요청을 팀의 baseline 으로 남겨 두는 것도 큰 도움이 됩니다. prompt, model, size, quality, 그리고 저장된 결과 파일까지 한 세트로 고정해 두면, 나중에 transparency 나 edits 를 추가했을 때 무엇이 바뀌어서 깨졌는지 훨씬 빨리 좁힐 수 있습니다.

rollout 순서도 분리하는 편이 좋습니다. 먼저 SDK 와 cURL 둘 다에서 정사각형 기본 요청이 안정적으로 통과하는지 확인하고, 그다음 decode-and-save 를 따로 검증하세요. 그 뒤에야 output tuning, multi-image edits, Responses orchestration 을 올리면 로그가 더 깨끗하고 팀 안에서 원인 설명도 쉬워집니다.

팀 내부 메모도 direct example 기준으로 남겨 두면 좋습니다. “이 요청은 Images API, 이 모델명, 이 access 전제에서 통과했다”는 기록이 있으면 다음 사람이 Responses 예제와 섞어 해석할 가능성이 크게 줄어듭니다.

이 작은 기준선 하나만 있어도 모델명 변경과 환경 문제를 훨씬 빨리 구분할 수 있습니다. 그리고 팀 합의도 쉬워집니다.

FAQ

새 예제는 gpt-image-1.5 와 gpt-image-1 중 무엇을 써야 하나요?

새 direct example 이라면 gpt-image-1.5 를 쓰는 편이 맞습니다. 공식 GPT Image 1.5 페이지가 이를 latest image generation model 로 설명하고 있기 때문입니다. gpt-image-1 는 migration 이나 legacy comparison 에서는 의미가 있지만 첫 기본값은 아닙니다.

왜 direct Images API 는 URL 대신 base64 를 반환하나요?

GPT image models 가 기본적으로 base64 image data 를 반환하기 때문입니다. DALL·E 기반의 예전 기대치를 그대로 따라가면 여기서 많이 헷갈립니다.

transparent PNG 나 image edit 를 하려면 Responses 가 꼭 필요한가요?

아닙니다. direct Images API 는 edits, input_fidelity, transparent background, output_format, output_compression 을 이미 지원합니다. Responses 는 orchestration 이 필요한 경우에만 쓰면 됩니다.

최종 권장사항

openai image generation api example 에 대한 가장 정직한 현재 답은 page one 이 보여주는 것보다 더 단순합니다. 먼저 Images API 를 쓰고, gpt-image-1.5 를 선택하고, 첫 request 는 작고 정사각형으로 유지한 뒤, 반환된 base64 이미지를 실제로 저장하세요. 이것이 2026년 3월 23일 기준 가장 빨리 동작하는 경로입니다.

Responses image_generation 으로 넘어가는 것은 이미지가 더 큰 workflow 의 tool 이 되었을 때면 충분합니다. 이 경계를 분명히 하면 현재 문서군에서 생기는 혼란의 대부분은 첫 단계에서 사라집니다.