OpenAI Image Generation API cURL: 지금 통하는 생성 요청과 편집 요청

현재 시점에 실제로 동작하는 OpenAI image generation API cURL 요청이 필요하다면, 가장 안전한 기본 경로는 POST /v1/images/generations 입니다. 먼저 raw JSON 응답을 저장하고, .data[0].b64_json 을 명시적으로 디코드해 파일로 만든 뒤에야 다음 단계로 넘어가는 방식입니다. 단발성 prompt-to-image 를 shell 이나 backend smoke test 로 확인하려면 이 경로가 지금도 가장 짧고 가장 덜 깨집니다.

이 기본 경로를 바꿔야 하는 경우는 두 가지뿐입니다. 이미 입력 이미지가 있고 그 이미지를 수정해야 한다면 POST /v1/images/edits 로 이동합니다. 이미지 생성이 더 큰 multimodal workflow 의 한 tool 단계일 뿐이라면 POST /v1/responses 로 이동해 image_generation tool 을 사용합니다. 그 외의 복잡화는 대개 첫 성공 루프를 불필요하게 멀리 보냅니다.

이 키워드가 괜히 더 복잡해 보이는 이유는 OpenAI 가 답을 여러 공식 페이지로 나눠 놓았기 때문입니다. image generation guide 는 전체적인 경로와 주요 파라미터를 설명하고, Images API reference 는 raw endpoint 계약을 제시합니다. Responses image_generation tool guide 는 다른 surface 의 tool 경로를 설명합니다. 그리고 2026년 3월 24일 기준으로도 guide 에는 https://api.openai.com/v1/images 를 사용하는 GPT Image cURL 조각이 남아 있지만, reference 는 /images/generations 과 /images/edits 를 raw route 로 적고 있습니다. 이 글은 그 조각들을 실제 운영에 맞는 하나의 shell workflow 로 다시 묶기 위한 글입니다.

핵심 요약

• 첫 cURL 테스트는 POST /v1/images/generations 와 gpt-image-1.5 로 시작한다.
• GPT image models 는 기본적으로 b64_json 을 반환하며 hosted URL 을 기본값으로 기대하지 않는다.
• 입력 이미지가 있을 때만 POST /v1/images/edits 로 이동한다.
• 이미지 생성이 더 큰 tool workflow 의 일부일 때만 POST /v1/responses 로 이동한다.

POST /v1/images/generations 로 시작해 단일 이미지 생성부터 검증하기

실제 할 일이 "터미널에서 prompt 를 보내고 이미지 한 장을 받는 것"이라면, 지금도 가장 먼저 써야 하는 surface 는 direct Images API 입니다. 공식 Images API reference 는 POST /images/generations 를 raw generation route 로 적고 있으므로, 완전한 URL 은 https://api.openai.com/v1/images/generations 입니다.

이 경로를 먼저 추천해야 하는 이유는 첫 성공 루프를 가장 작게 만들기 때문입니다.

• JSON 을 보낸다
• JSON 을 받는다
• base64 를 꺼낸다
• 이미지 파일로 저장한다

그리고 이것은 현재의 model lineup 과도 맞습니다. 공식 All models 페이지는 GPT Image 1.5 를 current state-of-the-art image generation model 로 두고, chatgpt-image-latest, gpt-image-1, gpt-image-1-mini 를 각각 다른 lane 으로 보여 줍니다. 따라서 새로운 cURL 예제의 기본값은 gpt-image-1.5 여야 하며, 예전 mental model 을 끌고 오면 안 됩니다.

가장 먼저 써 볼 request 는 이렇게 두면 됩니다.

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"
  }' > response.json

여기서 중요한 점은 첫 request 를 일부러 단순하게 두는 것입니다. 공식 guide 는 정사각형 이미지가 보통 가장 빠르고, 1024x1024 가 기본 크기라고 여전히 설명합니다. 첫 한 번의 요청으로 투명 배경, 가로형 구도, streaming partial images, 압축 형식, 복잡한 edits 까지 동시에 증명하려고 하면 실패했을 때 원인 분리가 어려워집니다. 첫 request 에서 확인해야 하는 것은 account access, endpoint, payload shape, response shape, 그리고 file output path 정도입니다.

대부분의 독자가 실제로 필요로 하는 route split 은 다음 표면 충분합니다.

이 표가 중요한 이유는 SERP 상위 문서들이 generation, edits, Responses 를 하나의 "image API example" 처럼 평평하게 다루는 경우가 많기 때문입니다. 실제로는 그렇지 않습니다. 맡는 역할이 다릅니다.

다음 질문이 "품질보다 비용을 먼저 보고 싶다" 라면 현행 카탈로그의 gpt-image-1-mini 가 budget lane 이 됩니다. endpoint 는 같아도 처음 benchmark 할 model 은 달라질 수 있습니다. 그 판단을 더 보려면 한국어판 OpenAI image generation API models 가 더 자연스러운 다음 읽을거리입니다.

응답이 실제로 무엇을 반환하는지와 안전한 디코드 방법

cURL 에서 제일 자주 막히는 지점은 대부분 POST 자체가 아닙니다. 문제는 그다음에 무엇을 하느냐입니다.

공식 Images API reference 는 Image object 에 b64_json, revised_prompt, url 가 있다고 적은 뒤, shell 사용자에게 가장 중요한 한 줄도 붙입니다. GPT image models 에서는 b64_json 이 기본 반환값이고, URL output 을 기본 happy path 로 두지 않는다 는 점입니다. 그래서 좋은 cURL 문서는 request body 만 보여 주고 끝나면 안 되고, decode step 까지 닫아 줘야 합니다.

가장 안전한 운영 습관은 먼저 raw response 를 저장하는 것입니다.

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"
  }' > response.json

jq '.data[0] | {has_b64_json: has("b64_json"), revised_prompt, url}' response.json

이 jq 확인 단계는 우회가 아닙니다. response shape 를 먼저 확인할 수 있어서 request 자체는 성공했는데 최종 파일이 깨지는 경우를 훨씬 쉽게 분리할 수 있습니다.

Linux 나 GNU base64 가 있는 환경이라면 decode 는 짧게 쓸 수 있습니다.

bash
jq -r '.data[0].b64_json' response.json | base64 --decode > openai-image.png

macOS 에서는 보통 -D 를 씁니다.

bash
jq -r '.data[0].b64_json' response.json | base64 -D > openai-image.png

GNU 와 BSD 차이를 완전히 피하고 싶다면 Python 에 맡기는 편이 가장 견고합니다.

bash
jq -r '.data[0].b64_json' response.json \
  | python -c 'import sys, base64; sys.stdout.buffer.write(base64.b64decode(sys.stdin.read()))' \
  > openai-image.png

바로 이 부분이 page one 평균을 이길 수 있는 지점입니다. 약한 cURL 예제는 request 를 보내는 데서 멈추거나, 작성자 환경에서만 동작하는 base64 pipe 를 보여 주고 끝납니다. 그러면 독자는 broken output file 문제를 혼자 떠안게 됩니다.

또 하나 중요한 점은, 오래된 image API mental model 을 끌고 오지 않는 것입니다. 예전 콘텐츠는 .data[0].url 을 happy path 중심으로 다루는 경우가 많았지만, 현재 GPT image route 는 그렇지 않습니다. script 가 아직도 .data[0].url 을 기다린다면 지금의 API 세대와 맞지 않습니다.

guide 와 reference 의 불일치가 실제 문제가 되는 곳도 여기입니다. guide 에 /v1/images 조각이 남아 있더라도, raw contract 로서는 /images/generations 에 anchor 를 두는 쪽이 더 안전합니다. cURL-first 독자에게는 그 편이 구현적으로 더 방어 가능하기 때문입니다.

JavaScript, Python, cURL 을 모두 포괄하는 더 넓은 예제가 필요하다면 OpenAI image generation API example 로 가면 충분합니다. 이 글은 raw HTTP workflow 를 안정화하는 데 집중합니다.

입력 이미지가 있을 때만 multipart POST /v1/images/edits 로 전환하기

이미 product image, brand asset, reference image 가 있다면 generation route 를 억지로 editing tutorial 로 늘릴 이유가 없습니다. 올바른 움직임은 surface 를 바꾸는 것이 아니라, direct Images API 안에서 edit branch 로 이동하는 것입니다.

공식 Images API reference 는 POST /images/edits 를 raw edit endpoint 로 적고 있고, image generation guide 에는 image[] 를 반복하는 multipart cURL example 도 있습니다.

형태는 대략 다음과 같습니다.

bash
curl -s -D >(grep -i x-request-id >&2) \
  -o >(jq -r '.data[0].b64_json' | base64 --decode > edited-image.png) \
  -X POST "https://api.openai.com/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F "model=gpt-image-1.5" \
  -F "image[]=@product-shot.png" \
  -F "image[]=@logo.png" \
  -F 'prompt=Place the logo on the product box as if it were printed on the packaging.'

여기서 가장 먼저 기억해야 할 규칙은 하나입니다. generation 은 JSON, edits 는 multipart 입니다. 많은 400 오류는 파라미터가 exotic 해서가 아니라, 편집 request 를 prompt-only generation 과 같은 JSON shape 로 보내기 때문에 시작됩니다.

또 하나의 분기는 fidelity 입니다. 공식 guide 는 gpt-image-1.5 를 사용할 때 첫 5 장의 입력 이미지에 대해 input_fidelity=high 를 쓰면 preservation 이 강해진다고 설명합니다. logo, 얼굴, 구도, 브랜드 요소를 더 지키고 싶은 edit 에서는 이 옵션이 의미가 있습니다.

raw cURL 에서는 이렇게 됩니다.

bash
curl -s \
  -X POST "https://api.openai.com/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F "model=gpt-image-1.5" \
  -F "image[]=@woman.jpg" \
  -F "image[]=@logo.png" \
  -F "input_fidelity=high" \
  -F 'prompt=Add the logo to the woman'\''s jacket as if stitched into the fabric.' \
  > edit-response.json

다만 input_fidelity=high 는 항상 넣는 상위 호환 옵션이 아닙니다. source image 보존이 실제로 중요한 경우에만 써야 하고, 속도나 비용을 우선하는 느슨한 변환에서는 굳이 넣지 않아도 됩니다.

이 대목에서 많은 튜토리얼이 잘못된 방향으로 갑니다. image task 가 더 고급스러워졌다는 이유로 곧바로 Responses 로 보내 버립니다. 하지만 그 결론은 틀렸습니다. Editing 은 여전히 direct Images API 의 1급 use case 입니다. 바뀌는 것은 request shape 이지, 올바른 surface 자체가 아닙니다.

편집에 특화된 더 깊은 설명이 필요하다면 OpenAI image editing API 를 보는 것이 맞습니다. 이 키워드에서는 multipart edits 로 넘어가는 조건을 분명히 하는 것만으로 충분합니다.

이미지 생성이 더 큰 workflow 의 일부일 때만 /v1/responses 로 가기

Responses image_generation tool guide 가 해결하는 문제는 다릅니다. 이미지 생성이 독립 output 이 아니라 더 큰 model interaction 안의 tool 이 되었을 때 어떻게 써야 하는지를 설명합니다.

여기서 핵심은 "Responses 가 더 최신이다" 가 아니라, field 책임이 바뀐다는 것 입니다.

guide 는 GPT image models 를 Responses API 의 top-level model field 에 두지 않는다 고 명시합니다. /v1/responses 를 쓸 때 top-level model 은 gpt-4.1 이나 gpt-5 같은 text-capable model 이고, image_generation tool 이 내부에서 image layer 를 담당합니다.

raw cURL 은 다음과 같습니다.

bash
curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
      }
    ]
  }' > responses-output.json

jq -r '.output[] | select(.type=="image_generation_call") | .result' responses-output.json \
  | python -c 'import sys, base64; sys.stdout.buffer.write(base64.b64decode(sys.stdin.read()))' \
  > plane.png

이 route 가 맞는 경우는 다음과 같습니다.

• 한 request 에서 text 와 image 가 함께 나올 수 있다
• model 이 언제 image tool 을 호출할지 결정해야 한다
• image output 이 assistant / agent flow 의 일부다

반대로 다음 경우에는 과합니다.

• 단순히 이미지 한 장을 만들고 싶다
• 먼저 raw endpoint access 를 확인해야 한다
• account state, model name, decode path 확인이 아직 끝나지 않았다

실무 규칙은 단순합니다. 최신처럼 보인다는 이유만으로 Responses 에서 시작하지 않는다. tool orchestration 이 본업일 때만 Responses 를 사용합니다. 그렇지 않으면 첫 성공 루프가 오히려 더 멀어집니다.

더 넓은 설명이 필요하다면 OpenAI image API tutorial 로 가면 됩니다. 이 글에서는 Responses branch 를 의도적으로 좁게 유지합니다. 그래야 default workflow 가 흐려지지 않기 때문입니다.

Troubleshooting: 어떤 cURL 실패가 payload 문제이고 어떤 실패가 access 문제인지 구분하기

이 키워드에서 상위 문서가 가장 약해지기 쉬운 곳이 여기입니다.

cURL 예제가 실패했을 때 다음에 해야 할 질문은 "어떤 파라미터를 랜덤하게 바꿀까" 가 아닙니다. 먼저 "이게 어떤 failure class 인가" 를 나눠야 합니다. payload, key, organization state, model assumption, rate limit 은 fix order 가 완전히 다르기 때문입니다.

첫 구분은 다음 표가 도움이 됩니다.

특히 403 은 코드 문제처럼 보이기 쉬워서 주의가 필요합니다. 공식 API Organization Verification 문서는 verification 이 image generation capabilities 를 unlock 하며, not-verified wording 이 남아 있으면 최대 30분 대기, 새 API key 생성, 세션 새로고침, 올바른 organization 이 active 인지 확인 순서를 권합니다. 이것은 optional cleanup 이 아니라 이 failure class 에서 가장 가치가 큰 fix sequence 입니다.

또한 API Model Availability by Usage Tier and Verification Status 는 gpt-image-1 과 gpt-image-1-mini 가 tiers 1 through 5 에서 사용 가능하지만 일부 access 는 organization verification 에 달려 있다 고 적습니다. 따라서 403 이나 429 를 보면 처음부터 JSON typo 로 단정하면 위험합니다.

404 는 다른 종류의 시간차입니다. OpenAI 의 GPT-Image-1.5 rollout thread 를 보면 2025년 12월 16일 rollout 초기에 model does not exist 가 나왔던 기록이 있습니다. 이것이 지금도 오래된 snippet 이 SERP 에 남는 이유를 설명합니다. 하지만 그것을 오늘의 기본 진단으로 삼으면 안 됩니다. 오늘의 순서는 먼저 path, 그다음 model name, 그 다음 copied snippet 의 낡음을 의심하는 쪽이 맞습니다.

또 하나 자주 놓치는 failure mode 는 HTTP error 가 아닙니다. 200 OK 인데 최종 파일이 비어 있거나 깨져 있는 경우 입니다. 이때는 API 가 아니라 decode step 이 틀린 경우가 많습니다. 그래서 response.json 을 남기고 .data[0].b64_json 존재 여부를 명시적으로 확인하는 습관이 중요합니다.

그리고 공식 edit example 이 보여 주듯이, 가능하면 request ID 를 출력해 두면 다음 분기까지 훨씬 빨라집니다.

bash
curl -s -D >(grep -i x-request-id >&2) \
  -o response.json \
  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"
  }'

request ID 자체가 bad request 를 고치진 않지만, 문제가 OpenAI 쪽인지 account state 쪽인지로 넘어갈 때 시간을 많이 줄여 줍니다.

verification 이 blocker 라는 것이 확실하다면 다음 읽을거리는 OpenAI image generation API verification 입니다.

첫 request 가 성공한 뒤에만 바꿔야 할 파라미터

base request 가 성공한 뒤에야 optimization 으로 들어갈 수 있습니다. 공식 guide 와 reference 를 합치면 현재 중요한 knobs 는 다음과 같습니다.

• size: 1024x1024, 1024x1536, 1536x1024, 또는 auto
• quality: low, medium, high, 또는 auto
• background: transparent, opaque, 또는 auto
• output_format: png, webp, jpeg

여기서도 가장 중요한 것은 순서입니다. 첫 request 가 아직 성공하지 않았는데 size, quality, output format, transparency 를 동시에 바꾸면 access 문제인지, payload shape 문제인지, output handling 문제인지 기준선이 사라집니다.

대부분의 one-shot generation test 에서는 다음 default 가 안전합니다.

• size 는 1024x1024
• quality 는 medium
• 투명 배경이 실제 requirement 가 아니면 background 는 기본값 유지
• file-format optimization 은 route 가 증명된 뒤

투명 배경이 필요하다면 current docs 에 그 branch 도 있습니다. request 를 조금 더 명시적으로 만들면 됩니다.

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": "Draw a transparent sticker-style icon of a paper airplane for a travel app",
    "size": "1024x1024",
    "quality": "high",
    "background": "transparent",
    "output_format": "png"
  }' > transparent-response.json

전송 크기를 더 줄이고 싶다면 core path 를 확인한 뒤 jpeg 나 webp 로 옮기면 됩니다. streaming 이나 partial_images 도 current guide 에 있지만, 그것은 optimize-later feature 이지 이 키워드의 main answer 가 아닙니다.

이 주제에서는 prompt tuning 을 첫 최적화로 삼고 싶어지기 쉽지만, raw API workflow 에서는 순서가 다릅니다. 더 안전한 순서는 다음과 같습니다.

1. endpoint 와 output path 를 증명한다
2. decode path 를 증명한다
3. 올바른 route branch 를 증명한다
4. 그 뒤에 quality, size, background, prompt detail 을 최적화한다

다음 질문이 raw HTTP shape 가 아니라 cost 라면, 한국어판 OpenAI image generation API pricing 으로 넘어가는 편이 자연스럽습니다. 가격은 route 가 안정된 뒤에야 제대로 판단하기 쉬워집니다.

최종 권고

이 키워드에 대한 가장 짧고 안전한 rule 은 다음과 같습니다. 먼저 POST /v1/images/generations 로 시작하고, b64_json 을 명시적으로 디코드한 다음, 입력 이미지가 있을 때만 multipart /v1/images/edits 로 가고, 이미지 생성이 더 큰 tool-driven flow 안에 들어갈 때만 /v1/responses 로 간다.

이 rule 이 SERP 평균보다 강한 이유는, 보기 좋은 request snippet 하나로 끝나지 않고 shell workflow 전체를 닫기 때문입니다. OpenAI 의 current docs 가 guide, reference, model pages, help pages 로 흩어져 있다는 현실도 그대로 반영합니다. 강한 cURL 문서에 필요한 것은 흩어진 정보를 하나의 구현 흐름으로 꿰어, 독자가 실제로 끝까지 작동시키게 만드는 것입니다.