그림 — /v1/images
만들기와 고치기. 원본을 보내면 결과가 원본에 가까워집니다.
만들기는 /v1/images/generations, 이미 있는 그림을 고치는 건 /v1/images/edits 예요. 고칠 땐 원본 파일을 같이 보내야 해요 — 안 보내면 매번 새로 그려서 화풍이 통째로 바뀌어요.
curl https://oneport.kr/v1/images/edits \
-H "Authorization: Bearer $ONEPORT_API_KEY" \
-F model=gpt-image-2.5-flare \
-F image=@./before.png \
-F prompt="칠판 글씨를 '2학기 시간표'로 바꿔줘"curl https://oneport.kr/v1/images/edits \
-H "Authorization: Bearer $ONEPORT_API_KEY" \
-F model=gemini-3.1-flash-image \
-F "image[]=@./original.png" \
-F "image[]=@./style.png" \
-F prompt="첫 번째 그림을 두 번째 그림의 화풍으로 다시 그려줘"비슷한 그림 만들기(variations) 문은 없어요 — POST /v1/images/variations 는 404 not_found_error 이고 문장이 고치기 문을 알려 줘요. 본보기 그림을 image 첫 장으로 /v1/images/edits 에 보내고, prompt 에 「이 그림과 비슷한 구도 · 색감으로 새로 그려줘」처럼 적어 주세요.
import base64, os, requests
r = requests.post(
"https://oneport.kr/v1/images/edits",
headers={"Authorization": f"Bearer {os.environ['ONEPORT_API_KEY']}"},
files=[("image", ("product.jpg", open("product.jpg", "rb"), "image/jpeg"))],
data={"model": "gpt-image-2.5-flare", "prompt": "배경을 흰 스튜디오로 바꿔줘"},
timeout=180,
)
r.raise_for_status()
with open("edited.png", "wb") as f:
f.write(base64.b64decode(r.json()["data"][0]["b64_json"]))import base64, os
from openai import OpenAI
client = OpenAI(api_key=os.environ["ONEPORT_API_KEY"], base_url="https://oneport.kr/v1", timeout=180)
r = client.images.edit(
model="gpt-image-2.5-flare",
image=("product.png", open("product.png", "rb"), "image/png"),
# 여러 장이면 image=[("original.png", open("original.png", "rb"), "image/png"), ("style.png", open("style.png", "rb"), "image/png")]
# — SDK 가 image[] 로 보내고 저희는 보낸 순서대로 받아요(첫 장이 원본 · SDK 동작)
prompt="배경을 흰 스튜디오로 바꿔줘",
)
with open("edited.png", "wb") as f:
f.write(base64.b64decode(r.data[0].b64_json))import fs from "node:fs";
import OpenAI, { toFile } from "openai";
const client = new OpenAI({ apiKey: process.env.ONEPORT_API_KEY, baseURL: "https://oneport.kr/v1", timeout: 180_000 });
const r = await client.images.edit({
model: "gpt-image-2.5-flare",
// 여러 장이면 [원본, 참고, …] 배열로 넘겨요 — SDK 가 image[] 로 보내요(첫 장이 원본)
image: await toFile(fs.readFileSync("product.png"), "product.png", { type: "image/png" }),
prompt: "배경을 흰 스튜디오로 바꿔줘",
});
const b64 = r.data?.[0]?.b64_json;
if (!b64) throw new Error("그림이 안 왔어요");
fs.writeFileSync("edited.png", Buffer.from(b64, "base64"));파일마다 형식(image/png · image/jpeg · image/webp)을 붙여 보내 주세요 — curl -F 는 확장자를 보고 알아서 붙이고, Python requests · openai SDK 는 위처럼 (이름, 파일, 형식) 세 칸으로, Node openai SDK 는 toFile(바이트, 이름, { type }) 로 넣으면 돼요. 여러 장이면 openai SDK 는 image 에 리스트(Node 는 배열)로 넘기면 돼요(첫 장이 원본). 형식이 빠졌거나 그림 형식이 아니면 저희가 파일 머리로 png · jpeg · webp 를 알아보고, 그 셋이 아니면(gif 포함) 값을 잡기 전에 400 으로 알려드려요.
요청 파라미터#
만들기 — POST /v1/images/generations (JSON)
| 파라미터 | 받는 값 | 저희가 하는 일 |
|---|---|---|
| model필수 | 그림 모델 id | 글 모델을 넣으시면 400 으로 어느 문으로 보낼지 알려드려요(고치기 문도 같아요). 목록에 없는 id 는 404 model_not_found 예요. |
| prompt필수 | 문자열 | 손대지 않고 벤더에 닿아요. 값은 부르기 전에 한 장 몫을 미리 잡았다가 끝나고 실제 사용량으로 정산해요. |
| size | 1024x1024 등 | GPT 엔 그대로 넘겨요. Grok(grok-imagine-…)은 size 를 아예 안 받아서 보내시면 400 이에요 — 빼고 보내주세요. 나노바나나(gemini-…-image)는 「가로x세로」 글자를 받아 비율과 해상도(긴 변 1024 이하 1K · 2048 이하 2K · 그 위 4K)로 바꿔 넘겨요(예: 1024x1024 → 1:1 · 1K, 1536x1024 → 3:2 · 2K, 1024x1536 → 2:3 · 2K, 1920x1080 → 16:9 · 2K, 1080x1920 → 9:16 · 2K). 비율은 가로 · 세로를 최대공약수로 줄인 값이 1:1 · 2:3 · 3:2 · 3:4 · 4:3 · 4:5 · 5:4 · 9:16 · 16:9 · 21:9(줄이면 7:3 — 예: 2520x1080 → 21:9 · 4K · 2026-10-31 부터) 중 하나와 딱 맞아야 해요 — 2000x1000(2:1) 같은 다른 비율, 1000x667 처럼 가까운 값, 「16:9」 · auto 처럼 가로x세로가 아닌 글자는 400 이에요(값은 안 나가요). 원본 사진 크기를 그대로 넣지 말고 이 열 비율로 딱 나눠지는 값으로 보내 주세요. 안 보내시면 저희는 size 를 싣지 않아요 — 크기는 그 모델의 기본값이에요(벤더 동작 · 나노바나나는 1:1 · 1K). |
| n | 1 | 지금은 한 번에 한 장만 그려드려요. 1 말고 보내시면 400 이에요 — 여러 장은 여러 번 불러 주세요. |
| quality · background · output_format · output_compression · moderation · style · user | OpenAI 그림 API 값 | GPT 그림 모델엔 그대로 넘겨요. 그 모델이 못 받는 값이면 400 이고(벤더 거절 문장 — 아래 표 400 줄) 값은 안 나가요. output_format 이 jpeg · webp 면 그 형식으로 와요. 나노바나나 · Grok 엔 같은 칸이 없어서 기본값(quality · background · moderation 은 auto, 나노바나나의 output_format 은 jpeg)이 아니면 400 이에요. user 는 GPT 그림 모델엔 해시해서 넘기고(이메일을 넣으셔도 원래 글자는 안 나가요), 그림이 달라지지 않는 칸이라 나노바나나 · Grok 엔 받고 싣지 않아요. 학교 스페이스 키는 moderation 을 auto 말고는 못 보내요(400) — 스페이스의 그림 검열은 낮출 수 없어요. |
| response_format | b64_json | 그림은 언제나 data[].b64_json 으로 돌려드려요 — b64_json 은 보내셔도 빼셔도 같아요(저희가 받고 벤더엔 안 넘겨요). url 은 400 이에요 — 벤더 주소는 곧 만료돼서 저희가 b64 로만 받아요. |
| stream · partial_images | — | 아직 안 받아요. 보내시면 400 이에요 — 다 그린 한 장을 한 번에 돌려드려요. |
| 그 밖의 칸 | — | 표에 없는 칸은 400 이에요. 받아 놓고 조용히 버리지 않아요. image · mask 를 이 문에 실으셔도 400 이에요 — 그림을 고치시려면 /v1/images/edits 로 보내주세요. |
고치기 — POST /v1/images/edits (multipart/form-data)
| 파라미터 | 받는 값 | 저희가 하는 일 |
|---|---|---|
| image필수 | 이미지 파일 (여러 장 가능) | 첫 장이 고칠 원본, 그 뒤는 참고 그림(화풍 · 인물 · 물건)이에요. image 를 여러 번 넣거나 image[] 로 보내시면 돼요 — 무엇을 어떻게 쓸지는 prompt 에 적어 주세요. GPT · 나노바나나(gemini-…-image)는 16장, Grok 은 5장까지예요(넘으면 400). 모두 합쳐 4,000,000바이트까지예요(4MiB = 4,194,304바이트가 아니에요). 넘으면 413 이 와요 — 그림을 줄여서 보내주세요(요청 몸통이 약 4.5MB 를 넘을 때 오는 413 은 아래 「고칠 원본은 4MB 까지」). 둘째 장부터는 입력 그림 몫을 더 미리 잡았다가 실제 사용량으로 정산해요(셈과 Grok 의 입력 그림 몫은 아래 「값은 어떻게 매겨지나요」). |
| prompt필수 | 문자열 | 손대지 않고 벤더에 닿아요. 값은 부르기 전에 한 장 몫을 미리 잡았다가 끝나고 실제 사용량으로 정산해요. |
| model · size · n · 나머지 칸 | 만들기와 같아요 | 만들기와 같은 규칙이에요 — 한 번에 한 장, Grok 은 size 를 안 받아요(400), quality · background · output_format 같은 칸은 GPT 엔 넘기고 나노바나나 · Grok 엔 기본값이 아니면 400 이에요. multipart 라 값은 파일이 아니라 폼 필드로 넣어주세요. image 말고 같은 칸(model · prompt · n 포함)을 두 번 보내시면 400 이에요. 저희는 원본 크기를 보고 size 를 정해 드리지 않아요 — 원본 비율대로 받으시려면 size 를 원본 비율로 보내 주세요(나노바나나는 위 비율 가운데 하나 · Grok 은 size 를 못 보내서 결과 크기 · 비율은 xAI 가 정해요 — 벤더 동작). |
| input_fidelity | low · high | GPT 그림 모델엔 값을 보지 않고 그대로 넘겨요(원본의 얼굴 · 로고를 얼마나 지킬지). 저희가 잰 건 gpt-image-1.5 예요(지금 목록에 없는 gpt-image-1 도 같았어요). OpenAI 는 gpt-image-2 엔 이 칸을 빼라고 하고, gpt-image-2.5-flare · sunburst 페이지엔 이 칸 이야기가 없어요(10월 확인 · 벤더 동작) — 이 모델들엔 빼고 보내 주세요. 보내셔도 저희는 막지 않고 그대로 넘겨요 — 받는지 무시하는지는 저희가 재지 않았고(벤더 동작), 벤더가 거절하면 400 invalid_request_error 이고 값은 안 나가요. high 면 어느 GPT 그림 모델이든 원본 · 참고 그림 장마다 입력 그림 4,000 토큰 몫을 더 미리 잡았다가 실제 사용량으로 정산해요(셈은 아래 「값은 어떻게 매겨지나요」) — 잔액이 빠듯하면 이 몫 때문에 402 hold_exceeds_balance 가 날 수 있어요. 나노바나나 · Grok 은 이 칸이 없어 400 이에요 — low 를 보내셔도 400 이에요. |
| mask | — | 아직 안 받아요. 보내시면 무시하지 않고 400 으로 말씀드려요 — 조용히 무시하면 「이 부분만 고쳐졌겠지」로 읽히거든요. |
응답#
응답엔 created 와 data[].b64_json 만 와요 — OpenAI 응답의 usage(토큰 수)는 안 실려요. 저희는 만들어질 때까지 기다렸다가 돌려드리니 따로 상태를 물어보실 필요가 없어요. 벤더 몫은 100초까지 기다리고, 넘으면 504 upstream_error 에 x-should-retry: false 로 끝내요 — 값은 안 붙어요. 같은 요청을 그대로 자동으로 다시 보내지는 마세요 — quality · size 를 낮춘 요청은 새 요청이라 코드가 한 번 보내도 돼요(504 엔 값이 안 붙었고, 새 요청은 그림이 만들어졌을 때만 값이 나가요). 같은 요청이면 시간을 두고 손으로 한 번 다시 보내 주세요. SDK 타임아웃은 2분보다 길게(예: 180초) 잡아 주세요. 응답을 받기 전에 끊으셔도 저희는 끝까지 그리고 정산해요 — 그림은 못 받고 값만 나가요. 받지 못한 그림은 저희가 따로 보관하지 않아서 다시 받을 길이 없어요 — 같은 그림이 필요하면 새로 부르셔야 해서 값이 한 번 더 나가요. 그래서 SDK 의 시간 초과 · 연결 끊김 자동 재시도는 꺼 두세요(Python max_retries=0 · Node maxRetries: 0 · SDK 동작) — 켜 두면 받지 못한 그림 값에 새 그림 값이 또 나가요. 그림 문은 Idempotency-Key 를 읽지 않아요 — 실어도 중복을 막지 않고 조회 주소도 오지 않아요. 「실패하면 안 나가요」는 상태 코드(4xx · 5xx)로 돌아온 경우예요. 한 번에 실제로 사용한 크레딧은 부르기 전후 GET /v1/key 의 day.used_credits 차이로 보세요(used_credits 는 쓴 몫을 올린 정수라, 차이는 실제 값을 내리거나 올린 정수예요 — 실제가 18.39 면 18 이나 19). 머리말 기본 규칙의 「앞뒤 차이로 재지 말라」는 usage 가 오는 글 문 이야기예요 — 그림 문은 usage 가 없어서 이 차이로 봐요. 저희가 그림을 돌려드리기 전에 정산과 키 누적을 끝내서, 응답을 받은 바로 뒤에 불러도 반영돼 있어요. 같은 키로 동시에 다른 호출을 하면 그 몫도 섞여요. day 는 한국 시간 0시에 0 부터 다시 세서 자정을 사이에 두고 재면 차이가 틀려요 — 그땐 month.used_credits 차이로 보세요(month 는 매달 1일 0시에 다시 세요). GPT 그림은 output_format 을 안 주시면 PNG 로 와요(벤더 기본값). 나노바나나(gemini-…-image)는 언제나 JPEG 라, 파일로 저장하실 땐 확장자를 모델에 맞춰 주세요. Grok 은 형식을 고를 수 없어요(output_format 은 400). 받은 그대로 돌려드리니 저장할 땐 바이트 앞부분(PNG \x89PNG · JPEG \xFF\xD8\xFF)으로 확장자를 정해 주세요.
{
"created": 1788000000,
"data": [
{ "b64_json": "iVBORw0KGgoAAAANSUhEUg..." }
]
}값은 어떻게 매겨지나요#
그림은 부르기 전에 토큰 수를 알 수 없어요. 그래서 저희가 한 장 몫을 먼저 잡아뒀다가, 끝나고 실제 값으로 정산해요. 먼저 잡는 금액은 GET /v1/models 의 pricing.max_hold_credits_per_image 예요 — quality · size · output_format 과 상관없이 같고, 더 잡는 건 prompt 글 몫(UTF-8 2바이트를 1토큰으로 어림해 input_credits_per_mtok 로 · 2026-10-31 부터 · 한 장 값으로 파는 Grok 은 없어요)과 고치기의 참고 그림(둘째 장부터) · input_fidelity=high 예요(아래 목록) — max_hold 칸엔 prompt 몫이 안 들어 있어서 prompt 가 길면 실제로 잡는 몫이 그보다 커요. 실제로 그보다 적게 나오면 남는 만큼 그대로 돌아오고, 실제 차감이 잡은 몫을 넘지는 않아요(2026-10-31 부터). 실패하면(400 · 413 · 벤더 거절 포함) 예약이 통째로 풀려서 한 푼도 안 나가요 — 상태 코드로 돌아온 실패 얘기예요(받기 전에 끊으시면 값이 나가요 · 위 「응답」). 값을 매기는 방식은 모델에 따라 둘이에요.
- 토큰으로 매기는 모델(GPT · 나노바나나) — 실제 값은 prompt(글) 토큰 · 입력 그림 토큰 · 출력 그림 토큰을 각 단가로 센 합이에요. 고칠 원본 · 참고 그림은 글 입력과 다른 「입력 그림」 단가(pricing.image_input_credits_per_mtok)로 세요. 고칠 원본 한 장 몫은 이 금액에 이미 들어 있어서 원본 한 장만 보내시면 더 잡지 않아요. 둘째 장부터 장마다 입력 그림 4,000 토큰 몫(4,000 × pricing.image_input_credits_per_mtok ÷ 1,000,000 — 예: gpt-image-2.5-flare 약 29.4 크레딧)을 더 잡아요. input_fidelity=high 면 원본 · 참고 그림 모두 장마다 같은 몫을 또 잡고, low 거나 안 주시면 더 잡지 않아요.
- gpt-image-2.5-flare · sunburst 한 장 어림 — 저희 실측(10월)으로 quality · size 를 안 주면 그림 출력이 215~829 토큰(약 6~23 크레딧), quality=high 1536x1024 · 1024x1536 이면 1,372 토큰(약 38 크레딧)이었어요. 고치기 한 번은 출력 1,887 토큰 + 원본 입력 1,480 토큰으로 약 63 크레딧이었어요(prompt 글 몫은 조금 더 · quality · size 를 적어 두지 않은 한 번이에요). 먼저 잡는 금액(약 101 크레딧)보다 적게 나와서 남는 만큼 돌아와요. size 만 주고 quality 를 안 주시면 저희는 quality 를 싣지 않아서 OpenAI 기본값(auto)이 정해요(벤더 동작) — 그 조합은 저희가 재지 않았어요. 만들기를 넉넉히 어림하시려면 quality=high 값(약 38 크레딧)으로 보세요 — 고치기는 원본 입력 몫이 더해져 그보다 커요. 고치기는 아래 「잔액이 남았는데 402 가 날 수 있어요」처럼 먼저 잡는 금액과 잔액을 견주고, 내 설정의 실제 값은 한 장 불러 위 「응답」의 day.used_credits 차이로 재 보세요. 10월 기준 · 지금 단가는 GET /v1/models 가 정본이에요.
- 나노바나나 한 장 어림 — 1K 한 장은 그림 출력이 1,120 토큰쯤이에요(저희 실측). 10월 기준 gemini-3.1-flash-image 면 약 62 크레딧이고, 글 · 생각 출력 몫(pricing.rates 의 output_text 단가)이 1 크레딧 안팎 더 붙어요. 먼저 잡는 금액은 약 184 크레딧이라 잔액이 그보다 적으면 402 예요. 지금 단가는 GET /v1/models 가 정본이에요.
- 벤더가 매기는 모델(Grok) — xAI 가 알려 준 값만큼 사용하고, 한 장 값에 입력 그림 몫을 더한 값을 넘지 않아요. 원본을 포함해 입력 그림 한 장마다 약 1.84 크레딧까지 더 사용해요 — 10월 기준 grok-imagine-image 에 원본 한 장이면 약 20 크레딧까지예요. 먼저 잡는 금액은 한 장 값의 1.5배(grok-imagine-image 는 10월 기준 27.59 — 한 장 값은 약 18.4 · 잔액과 견줄 땐 GET /v1/models 의 값을 쓰세요)이고, 참고 그림은 실측의 두 배로 잡아서 둘째 장부터 장마다 약 3.68 크레딧을 더 잡아요 — 잔액이 실제 값과 먼저 잡는 금액 사이면 402 가 와요.
- 여러 장을 가장 싸게 뽑으실 땐 — 먼저 잡는 금액 순서가 실제 값 순서는 아니에요. Grok 은 한 장 값(GET /v1/models 의 max_hold_credits_per_image ÷ 1.5 · 10월 기준 약 18.4 크레딧)을 넘지 않지만 size 를 못 바꿔요. GPT 그림 모델은 토큰으로 매겨서 quality · size 에 따라 값이 달라요(위 flare 어림 6~38 크레딧) — quality 는 저희가 보지 않고 OpenAI 에 그대로 넘겨요(받는 값은 OpenAI 문서 · 벤더 동작). 정확히 견주시려면 모델마다 한 장씩 불러 GET /v1/key 의 day.used_credits 차이를 보세요.
이 문이 받는 모델#
그림
| 모델 | 입력100만 토큰당 크레딧 | 출력100만 토큰당 크레딧 |
|---|---|---|
| gpt-image-2.5-flareGPT Image 2.5 Flare | 4,599 | 27,594 |
| gpt-image-2.5-sunburstGPT Image 2.5 Sunburst | 4,599 | 27,594 |
| gpt-image-2GPT Image 2 | 4,599 | 27,594 |
| gpt-image-1.5GPT Image 1.5 | 4,599 | 29,434 |
| gpt-image-1-miniGPT Image 1 mini | 1,840 | 7,358 |
| grok-imagine-imageGrok Imagine | 한 장 18 크레딧 | |
| grok-imagine-image-2.0Grok Imagine 2.0 | 한 장 55 크레딧 | |
| grok-imagine-image-qualityGrok Imagine Quality | 한 장 46 크레딧 | |
| gemini-3.1-flash-imageNano Banana 2 (Gemini 3.1 Flash Image) | 460 | 55,188 |
| gemini-3.1-flash-lite-imageNano Banana 2 Lite (Gemini 3.1 Flash Lite Image) | 230 | 27,594 |
| gemini-3-pro-imageNano Banana Pro (Gemini 3 Pro Image) | 1,840 | 110,376 |
표의 모델은 만들기와 고치기 둘 다 받아요 — GET /v1/models 의 endpoint 칸은 기본 문이라 그림 줄은 모두 POST /v1/images/generations 로 적혀 있어요. GET /v1/models 의 그림 줄(kind 가 "image")은 pricing 객체 안에 input_credits_per_mtok(글 입력) · image_input_credits_per_mtok(입력 그림) · output_credits_per_mtok(출력 그림) · max_hold_credits_per_image(한 장 먼저 잡는 금액)가 와요 — 앞의 셋은 100만 토큰당 크레딧, 마지막은 한 장 크레딧이에요. 나노바나나의 글 · 생각 출력 단가는 pricing.rates 의 output_text 줄이에요. Grok 세 모델은 토큰 단가 칸 없이 max_hold_credits_per_image 만 와요 — 한 장 값(표의 「한 장」)의 1.5배예요. gpt-image-2.5-flare 와 sunburst 는 값 · 먼저 잡는 금액 · 받는 칸이 같아요 — 둘 다 OpenAI 모델이라 그림 성향 차이는 OpenAI 모델 페이지를 보세요. 키를 실어 GET /v1/models 를 부르면 스페이스 관리자가 끈 그림 모델과, 한 장 먼저 잡는 몫이 그 키의 월 한도보다 큰 그림 모델은 빠져요 — 그 키로 부를 수 있는지 부르기 전에 볼 때 쓰세요.
실패하면 오는 것#
실패는 {"error": {"type": "insufficient_credit", "message": "크레딧이 부족해요. …", "code": "insufficient_credit", "reason": "below_minimum_balance"}} 모양이에요 — type 과 code 는 같은 값이라 type 으로 가르세요. reason 은 401 · 402 · 한도 429 에 와요(값은 아래 표 · 503 도 저희 쪽 사정으로 모델 회사가 받지 않았으면 "provider_unavailable" — 2026-10-31 부터). 실패하면 값은 안 나가요. 그림 문은 Retry-After 를 키 한도 429 의 held_by_others(5초)와 모델 목록을 잠깐 못 읽은 503(2초)에만 실어요 — 429 rate_limit_error · 502 · 503 은 코드가 몇 초 간격으로 몇 번 다시 보내도 돼요(값은 안 나가요). 간격은 글 문의 기본값으로 잡으세요 — 402 held_by_others 5초 · 503 2초 · 429 5초부터예요(글 문 429 는 모델 회사가 알려 준 값이 있으면 그 값이에요 · 「에러」 장). 4xx upstream_error · 422 는 이 문에 오지 않아요. 문의하실 땐 응답 머리글 request-id(오류면 error.request_id 도 같은 값)와 부른 시각 · 모델 이름을 알려 주세요.
| 상태 | type | 할 일 |
|---|---|---|
| 400 | invalid_request_error | 칸 값이 틀렸거나 벤더가 거절했어요(검열 · 칸 값 — 벤더 문장을 붙여 드려요). 고쳐서 보내 주세요. 글 모델 id 를 넣으셨으면 문장이 맞는 문을 알려 드려요. 벤더가 거절한 400 은 문장이 「그림을 만들지 못했어요」로 시작해요 — 모델 회사 이유가 있으면 「— 모델 회사가 이렇게 답했어요: …」로, 못 읽었으면 「— 모델 회사가 이 요청을 받지 않았어요. 프롬프트 · 크기 · 품질 같은 칸을 고쳐 보내 주세요(같은 요청은 다시 보내도 같아요).」로 이어져요. 저희 칸 검사 400 과 type 이 같아서 이 머리로 가르세요(code 도 type 과 같은 값이라 code 로는 못 갈라요). 여러 장을 돌릴 때 이 머리가 장마다 이어지면 칸 값(size · quality · output_format) 거절일 수 있어요 — 그 장만 건너뛰지 말고 멈추고 문장을 보세요. 머리말 뒤는 갈래마다 달라요 — 나노바나나는 안전 기준에 걸렸는지, 이미 있는 그림 · 캐릭터와 너무 닮아 거절됐는지(작품 · 캐릭터 이름을 빼면 풀릴 수 있어요)를 말해요. 그 밖의 거절은 모델 회사가 준 이유가 200자보다 짧을 때만 원문을 붙이고, 길거나 못 읽었으면 위 「받지 않았어요」 쪽 문장이에요. 벤더가 거절한 400 엔 「잠시 후 다시」가 붙지 않아요(그 말은 429 · 502 · 503 에 와요). |
| 401 | authentication_error | 키가 없거나 쓸 수 없는 키예요 — error.reason 이 까닭이에요(「인증」 장의 「키가 안 열릴 때」 표). |
| 402 | insufficient_credit | 예약할 크레딧이 모자라요(위 「잔액이 남았는데 402 가 날 수 있어요」). error.reason 으로 갈래가 와요 — "held_by_others"(다른 호출이 잡아 둔 몫 — 충전하지 말고 잠시 뒤 그대로 다시) · "hold_exceeds_balance"(고치기의 참고 그림(둘째 장부터) · input_fidelity "high" 몫까지 잡아 잔액을 넘었어요 — 문장이 말한 것을 줄이면 통과할 수 있어요) · "below_minimum_balance"(이 모델의 한 장 몫보다 잔액이 적어요 — 충전). n 은 늘 1 이라 장 수로는 못 줄여요. 만들기와 원본 한 장 고치기(input_fidelity 를 안 주시거나 low)엔 hold_exceeds_balance 가 오지 않아요 — held_by_others 나 below_minimum_balance 예요. |
| 403 | model_not_in_plan · model_disabled_in_space | 이 크레딧으로 못 부르는 모델이거나 스페이스에서 끈 모델이에요. 다시 보내도 같아요. |
| 404 | model_not_found | 목록에 없는 id 예요. 문장에 가까운 이름을 드려요. |
| 403 · 409 · 503 | space_content_policy | 학교 스페이스 키가 스페이스 전송 정책에 걸렸어요. 관리자가 전송 정책을 켠 스페이스는 그림을 아예 못 보내서 403 이에요 — 그림 문은 prompt 를 정책 낱말로 보지 않아서 prompt 를 고쳐도 같아요. 스페이스 관리자에게 말해 주세요. 세부 이유는 code 에 싣지 않아서(code 도 space_content_policy) 상태로 가르세요 — 409 는 정책이 방금 바뀐 것이라 한 번 그대로 다시, 503 은 잠시 뒤 다시 보내요. 값은 안 나가요. |
| 413 | invalid_request_error | 그림을 모두 합쳐 4,000,000바이트를 넘었어요. 줄여서 보내 주세요. 몸통이 약 4.5MB 를 넘으면 JSON 이 아닌 영어 413 이 와요(위 「고칠 원본은 4MB 까지」). |
| 429 | rate_limit_error | 벤더가 잠시 조였어요(그림 문은 다른 경로로 다시 걸지 않아요). 잠시 뒤 다시 보내셔도 돼요. |
| 429 | key_limit_exceeded · group_limit_exceeded | 키의 하루 · 월 한도나 스페이스 강좌 몫이에요. error.reason 으로 갈래가 와요 — 키 한도는 "key_month_limit"(월 · 「쓴 몫 + 이 그림의 몫」이 한도를 넘으면 와요) · "key_day_limit"(하루) · "held_by_others"(월 · 이 키로 아직 끝나지 않은 몫까지 더하면 넘어요), 강좌 몫은 "group_budget" · "group_closed" · "group_not_started" · "group_ended", 회사·기관 부서 몫이 끝에 닿았으면 "group_tail"(그림은 다음 달 1일에 다시 열려요 · 「에러」 장). 바로 다시 보내면 같아요(x-should-retry: false) — 다만 held_by_others 는 그 호출이 끝나면 풀려서 x-should-retry: true · Retry-After: 5 가 붙어요 — 그만큼 기다렸다 그대로 다시 보내요(「에러」 장). |
| 502 | upstream_error | 벤더 쪽 실패예요. 잠시 뒤 다시 보내 주세요. |
| 503 | api_error | 벤더에 못 닿았거나 키 · 잔액 · 모델 목록을 잠깐 못 읽었어요. 잠시 뒤 그대로 다시 보내 주세요. error.reason 이 "provider_unavailable" 이면 저희 쪽 사정으로 모델 회사가 받지 않은 거예요(2026-10-31 부터 · 요금 없음). |
| 504 | upstream_error | 그림이 100초 안에 안 왔어요(x-should-retry: false · 값은 안 나가요) — 같은 요청은 자동으로 다시 보내지 말고, quality · size 를 낮춘 새 요청은 코드가 한 번 보내도 돼요(위 「응답」). |
머리글은 SDK 마다 읽는 법이 달라요 — Python openai SDK 는 except openai.APIStatusError as e: 에서 e.response.headers.get("x-should-retry"), openai SDK(Node)는 err.headers 로 읽고 v5 부터는 err.headers.get("x-should-retry") 예요(SDK 동작). 응답이 JSON 이 아닌 413 은 Python 에서 e.type 이 None 이라 e.status_code 로 갈라요(SDK 동작). SDK 기본 재시도는 이 머리글이 false 면 다시 안 보내요.