Images API
엔드포인트는 두 개입니다. 생성(텍스트 → 이미지)과 편집(이미지 + 텍스트 → 이미지)이며, 응답은 모두 OpenAI 표준 구조 data[0].b64_json을 따릅니다.
Seedream과 Qwen-Image는 /v1/images/edits를 지원하지 않으며, 이미지-투-이미지는 generations 엔드포인트로 수행합니다. 단, 참조 이미지 필드가 다릅니다. Seedream은 image, Qwen은 input_images를 사용하므로 서로 바꿔 쓰지 않도록 주의하십시오. Gemini에서 해상도(512~4K)를 제어해야 할 때는 Gemini 네이티브 프로토콜을 사용하십시오. 시리즈별 파라미터 차이는 해당 시리즈 페이지를 참고하십시오.
빠른 시작
바로 실행할 수 있는 최소 요청입니다. 1024×1024 이미지 한 장을 생성하고 디코딩하여 output.png로 저장합니다.
https://api.ofox.io/v1https://api.ofox.io/v1/images/generationshttps://api.ofox.io/v1/images/editsopenai/gpt-image-2.6-flarePython
import base64
from openai import OpenAI
client = OpenAI(
api_key="YOUR_OFOX_API_KEY",
base_url="https://api.ofox.io/v1",
timeout=600, # 이미지 API는 동기식으로 응답하며 시간이 오래 걸릴 수 있습니다
)
resp = client.images.generate(
model="openai/gpt-image-2.6-flare",
prompt="흰 테이블 위에 놓인 빨간 사과 하나",
size="1024x1024",
quality="low",
)
with open("output.png", "wb") as f:
f.write(base64.b64decode(resp.data[0].b64_json))API는 동기식으로 응답하므로 클라이언트 타임아웃을 600초로 설정하십시오. 고화질, 대형 크기, 편집 요청은 몇 분이 걸릴 수 있습니다. 실측 지연 시간을 참고하십시오.
모든 시리즈의 호출 방식은 같으며, 모델을 바꿀 때는 model만 변경하면 됩니다. 허용 값과 시리즈 고유 파라미터는 서로 다르므로 아래 각 파라미터 설명을 참고하십시오.
이미지 생성
POST https://api.ofox.io/v1/images/generations요청 파라미터
아래의 허용 값과 기본값은 GPT Image 시리즈(gpt-image-2.6-flare, gpt-image-2.6-sunburst, gpt-image-2.5-flare, gpt-image-2.5-sunburst, gpt-image-2)에 적용됩니다. 다른 시리즈와 차이가 있는 부분은 따로 표시합니다. 실측 세부 내용은 GPT Image 시리즈를 참고하십시오.
출력 크기입니다. 너비와 높이를 직접 지정할 수 있지만 네 가지 제약을 충족해야 하며, 그렇지 않으면 400 Invalid size가 반환됩니다.
▸ 자세히
네 가지 제약:
- 너비와 높이 모두 16으로 나누어떨어질 것
- 긴 변 ≤ 3840
- 종횡비 1:3 ~ 3:1
- 총 픽셀 수 ≥ 655,360(
768x768은 거부되고1024x768은 허용됨)
생략하거나 auto로 두면 모델이 결정하며, 실측 결과 1254×1254가 반환되었습니다. 고정 크기가 필요하면 명시적으로 지정하십시오. 다른 시리즈는 크기 규칙이 다르므로 해당 시리즈 페이지를 참고하십시오. 자세한 내용은 GPT Image · 크기를 참고하십시오.
품질 단계이며 가격에 직접 영향을 줍니다. gpt-image-2에는 xhigh / max가 없습니다.
▸ 자세히
gpt-image-2에는xhigh/max가 없으며, 전달하면 400이 반환됩니다.- DALL·E 시절의
standard/hd는 허용되지 않으며, 전달하면 400이 반환됩니다. - 생략하는 것은
medium과 같지 않습니다. 모델이 단계를 직접 선택합니다(실측 결과low). 품질과 비용을 안정적으로 유지하려면 명시적으로 지정하십시오.
다른 시리즈는 대부분 품질 단계가 없으므로 해당 시리즈 페이지를 참고하십시오. 자세한 내용은 GPT Image · 품질을 참고하십시오.
생성할 이미지 수이며, 각 이미지가 개별 과금됩니다. Gemini 모델은 지원하지 않으므로 전달하지 마십시오.
출력 파일 형식입니다. gif, svg는 GPT Image 2.6에서만 지원합니다. GPT Image · GIF 애니메이션, SVG 벡터 이미지를 참고하십시오.
▶고급 · 11complexity · svg · frame_count · frame_duration_ms · output_compression · background · moderation · stream · partial_images · input_images · extra_body.provider.typeExpand
생성 전 계획에 들이는 양이며, quality와는 독립적이고 추가 요금이 없습니다. GPT Image 2.6 전용입니다. GPT Image · complexity를 참고하십시오.
output_format이 svg일 때 필수입니다. svg.model(필수)은 SVG를 작성할 OpenAI 텍스트 모델이며 openai/ 접두사를 붙이지 않습니다. svg.reasoning.effort(선택)는 SVG 작성 시의 추론 강도입니다. n은 반드시 1이어야 하며, 스트리밍, partial_images, prompt_rewriter, output_compression은 지원하지 않습니다. GPT Image 2.6 전용입니다.
GIF 프레임 수이며, output_format이 gif일 때만 적용됩니다. GPT Image 2.6 전용입니다.
GIF 각 프레임이 머무는 밀리초 수이며, 10밀리초 단위로 반올림되고 output_format이 gif일 때만 적용됩니다. GPT Image 2.6 전용입니다.
압축률이며 jpeg / webp에만 적용됩니다.
배경입니다. transparent에는 알파 채널을 지원하는 형식(png / webp)이 필요합니다.
콘텐츠 심사 강도입니다.
스트리밍 응답 여부입니다. partial_images와 함께 사용하면 생성 도중 중간 이미지를 받을 수 있습니다.
스트리밍으로 받을 중간 이미지 수이며, stream: true가 필요합니다. OpenAI 공식 문서에 따르면 중간 이미지 한 장마다 출력 토큰 100개가 추가로 과금됩니다.
참조 이미지 배열(URL 또는 base64)이며, Qwen 시리즈만 지원합니다. 1–3장을 전달할 수 있습니다.
▸ 자세히
다른 시리즈는 전달해도 오류 없이 적용되지 않습니다. Seedream의 참조 이미지 필드는 image입니다.
공급자를 지정합니다. 선택 사항이며 보통은 필요하지 않습니다. 게이트웨이가 자동으로 라우팅합니다. 콘텐츠 심사와 관련된 요구가 있을 때 지정을 고려하십시오. 공급자를 지정하면 해당 공급자를 사용할 수 없을 때 다른 공급자로 전환되지 않습니다.
▸ 자세히
요청 헤더 X-OfoxAI-Provider-Type과 동일합니다. 고급: 공급자 지정을 참고하십시오.
응답
{
"created": 1777385517,
"data": [
{ "b64_json": "iVBORw0KGgoAAAANSUhEUgAA…", "index": 0 }
],
"model": "openai/gpt-image-2.5-flare",
"size": "1024x1024",
"quality": "low",
"usage": {
"input_tokens": 13,
"input_tokens_details": { "text_tokens": 13 },
"output_tokens": 196,
"output_tokens_details": { "image_tokens": 196 },
"total_tokens": 209
}
}이미지의 base64 인코딩이며, data:image/png;base64, 접두사가 포함되지 않습니다.
▸ 자세히
디코딩한 뒤 파일로 저장하십시오. 브라우저에 표시하려면 접두사를 직접 붙여야 합니다. 응답에는 url 필드가 없습니다.
이미지 순번이며, n > 1일 때 여러 이미지를 구분합니다.
실제 출력 크기입니다. size를 생략했거나 auto로 보낸 경우 여기에서 실제 크기를 확인하십시오.
실제로 사용된 품질 단계입니다. quality를 생략한 경우 여기에서 어떤 단계가 사용되었는지 확인할 수 있습니다.
실제로 사용된 배경과 형식입니다. 항상 반환되지는 않으므로 이 필드에 의존하지 마십시오.
과금 사용량입니다. output_tokens는 출력 이미지 토큰이고, input_tokens_details.text_tokens는 프롬프트 토큰입니다.
▸ 자세히
이 수치로 호출 1회의 비용을 계산하십시오.
이미지 편집
POST https://api.ofox.io/v1/images/edits이 엔드포인트는 GPT Image, Nano Banana(Gemini), MAI Image를 지원합니다. Seedream과 Qwen-Image로 호출하면 400 endpoint_not_supported가 반환되므로, 생성 엔드포인트의 참조 이미지 필드를 사용하십시오. Seedream, Qwen-Image를 참고하십시오.
요청 파라미터
multipart/form-data 폼 필드로 전송하며, 이미지 파일을 업로드해야 합니다. 허용 값과 기본값은 마찬가지로 GPT Image 시리즈에 적용됩니다.
인페인팅 마스크입니다. 알파 채널이 있는 PNG이며 image와 크기가 같아야 합니다. 투명 영역 = 다시 그려지는 부분입니다.
▸ 자세히
이 엔드포인트에서만 적용되며, 생성 엔드포인트로 보내면 조용히 무시됩니다. 만드는 방법과 실측 효과는 GPT Image · 마스크 인페인팅을 참고하십시오.
출력 크기이며, 제약은 생성 엔드포인트와 같습니다.
▸ 자세히
생략하거나 auto로 두면 모델이 결정하며, 원본과 같다는 보장은 없습니다. 원본 크기를 유지하려면 명시적으로 지정하십시오.
품질 단계이며, 규칙은 생성 엔드포인트와 같습니다. gpt-image-2에는 xhigh / max가 없습니다.
생성할 이미지 수이며, 각 이미지가 개별 과금됩니다.
▶고급 · 5markup · complexity · output_format · frame_count · frame_duration_ms · X-OfoxAI-Provider-TypeExpand
주석 레이어입니다. 첫 번째 이미지 위에 겹쳐지는 투명 PNG로, 크기가 첫 번째 이미지와 같아야 하고 반드시 투명 픽셀을 포함해야 하며, mask와 함께 사용할 수 없습니다. 추가 요금은 없습니다. GPT Image 2.6, 2.5 전용입니다. GPT Image · 주석 편집을 참고하십시오.
규칙은 생성 엔드포인트와 같습니다. GPT Image 2.6 전용입니다.
gif는 GPT Image 2.6에서만 지원하며, frame_count, frame_duration_ms와 함께 사용합니다. 규칙은 생성 엔드포인트와 같고 mask와 함께 사용할 수 없습니다. 편집 엔드포인트는 svg를 지원하지 않습니다.
GIF 프레임 수와 프레임당 시간이며, 규칙은 생성 엔드포인트와 같습니다. GPT Image 2.6 전용입니다.
공급자를 지정합니다. 선택 사항이며 보통은 필요하지 않습니다. 게이트웨이가 자동으로 라우팅합니다. 콘텐츠 심사와 관련된 요구가 있을 때 지정을 고려하십시오. 공급자를 지정하면 해당 공급자를 사용할 수 없을 때 다른 공급자로 전환되지 않습니다.
▸ 자세히
이 엔드포인트는 multipart 업로드이므로 공급자를 지정하려면 요청 헤더만 사용할 수 있으며, 폼 필드 extra_body는 조용히 무시됩니다. 고급: 공급자 지정을 참고하십시오.
응답
구조는 생성 엔드포인트와 같으며, usage에 참조 이미지의 입력 토큰이 추가됩니다.
{
"created": 1777385669,
"data": [
{ "b64_json": "iVBORw0KGgoAAAANSUhEUgAA…", "index": 0 }
],
"model": "openai/gpt-image-2",
"size": "auto",
"quality": "low",
"usage": {
"input_tokens": 1041,
"input_tokens_details": { "image_tokens": 1024, "text_tokens": 17 },
"num_input_images": 1,
"output_tokens": 358,
"total_tokens": 1399
}
}참조 이미지를 환산한 입력 토큰입니다. 실측 결과 1024×1024 참조 이미지 한 장에 1,024개가 계산되었습니다. 같은 크기의 텍스트 기반 이미지 생성보다 편집 비용이 높은 주된 이유가 이 항목입니다.
참조 이미지 수입니다. 모델이 참조 이미지를 실제로 읽었는지 확인하는 데 사용할 수 있습니다.
나머지 필드는 생성 엔드포인트의 응답과 같습니다.
지원 모델과 가격은 모델 카탈로그 에서 확인하십시오.
호출
Python
import base64
from openai import OpenAI
client = OpenAI(api_key="YOUR_OFOX_API_KEY", base_url="https://api.ofox.io/v1", timeout=600)
with open("apple.png", "rb") as f:
resp = client.images.edit(
model="openai/gpt-image-2",
image=f,
prompt="사과를 초록색으로 바꾸고, 나머지는 그대로 두세요",
size="auto",
quality="low",
)
with open("apple_edited.png", "wb") as out:
out.write(base64.b64decode(resp.data[0].b64_json))image 필드에는 URL이 아닌 로컬 파일 경로를 전달하십시오(cURL에서는 @ 접두사 사용).
실측 비교:
오류
오류가 발생하면 HTTP 오류 상태 코드와 함께 다음 구조가 반환됩니다(실측).
{
"error": {
"code": null,
"message": "The model 'gpt-image-2' does not support quality 'xhigh'.",
"param": null,
"request_id": "fbe4f24c-779d-41a0-8b3a-c62886cdd1ae",
"type": "image_generation_user_error"
}
}code는 null일 수 있습니다. HTTP 상태 코드와 message로 판단하십시오.
지원팀에 문의할 때는 응답의 request_id와 오류 정보(HTTP 상태 코드와 error.message)를 함께 보내 주십시오. 이 값들은 로그에 기록해 두는 것을 권장합니다.
고급: 공급자 지정
선택 사항이며 보통은 필요하지 않습니다. GPT Image의 gpt-image-2.5-flare, gpt-image-2.5-sunburst, gpt-image-2는 azure_foundry와 openai 두 공급자가 제공하며 생성과 편집 모두 지원합니다. gpt-image-2.6-flare, gpt-image-2.6-sunburst는 현재 openai만 제공하며, azure_foundry를 지정하면 No available channel이 반환됩니다. 지정하지 않으면 게이트웨이가 자동으로 라우팅합니다.
콘텐츠 심사와 관련된 요구가 있을 때 공급자를 지정할 수 있습니다. 지정하면 요청은 해당 공급자로만 전송되며, 그 공급자를 사용할 수 없을 때 다른 공급자로 자동 전환되지 않습니다.
해당 모델을 제공하지 않는 공급자를 지정하면 400 provider_type_unavailable이 반환됩니다.
openai/gpt-image-2의 두 공급자는 심사 기준이 다릅니다. 프롬프트가 반복해서 거부되면 openai를 명시적으로 지정할 수 있습니다. 지정하지 않으면 가중 분배에 따라 azure_foundry로 전송될 수 있습니다.
텍스트로 이미지 생성 /v1/images/generations
JSON 본문이므로 본문 필드 extra_body.provider.type과 요청 헤더 X-OfoxAI-Provider-Type 중 어느 쪽이든 사용할 수 있습니다.
Python
resp = client.images.generate(
model="openai/gpt-image-2",
prompt="A simple red apple on a white table",
size="1024x1024",
extra_body={"extra_body": {"provider": {"type": "openai"}}},
)공식 OpenAI SDK를 사용할 때 extra_body는 요청 본문에 문자 그대로의 키로 존재해야 합니다. TypeScript SDK는 파라미터 객체에 extra_body를 직접 작성하면 됩니다. Python SDK의 extra_body= 인자는 내용을 본문 최상위로 병합하므로, 한 단계 더 중첩하거나 요청 헤더를 사용하십시오.
이미지 편집 /v1/images/edits
multipart 업로드에는 extra_body를 중첩할 JSON 본문이 없으므로 요청 헤더만 사용할 수 있습니다.
curl https://api.ofox.io/v1/images/edits \
-H "Authorization: Bearer $OFOX_API_KEY" \
-H "X-OfoxAI-Provider-Type: openai" \
-F "model=openai/gpt-image-2" \
-F "prompt=..." \
-F "image=@input.png"SDK 사용 시: Python에서는 extra_headers={"X-OfoxAI-Provider-Type": "openai"}를 전달하고, TypeScript에서는 두 번째 인자로 { headers: { 'X-OfoxAI-Provider-Type': 'openai' } }를 전달합니다.
/v1/images/edits에서 폼 필드로 전달한 extra_body는 조용히 무시됩니다. 이미지는 정상적으로 생성되지만 제약이 적용되지 않습니다. X-OfoxAI-Provider-Type을 사용하십시오.
전체 참고 자료는 API · 공급자 라우팅을 참고하십시오.
공식 문서 및 추가 자료
공식 문서는 OpenAI에 직접 연결하는 경우의 동작을 설명합니다. OfoxAI의 실측 동작과 다를 경우 이 사이트의 실측 결과가 우선합니다.
OpenAI 공식
- 이미지 생성 가이드 · 이미지 생성
- 이미지 생성 가이드 · 이미지 편집
- 이미지 생성 가이드 · 마스크를 사용한 부분 편집
- 이미지 생성 가이드 · 크기와 품질
- 이미지 생성 가이드 · 비용 계산
- Images API 레퍼런스
OfoxAI 시리즈 페이지
- GPT Image 시리즈 개요: 모델 선택, 크기, 품질, 지연 시간, 오류
- 텍스트로 이미지 생성
- 이미지 편집 및 다중 이미지
- 부분 수정(인페인팅)
- Nano Banana 시리즈(Gemini Image)와 오류 해결
- Seedream 시리즈
- Qwen-Image 시리즈
- MAI Image 시리즈

