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.ai/v1https://api.ofox.ai/v1/images/generationshttps://api.ofox.ai/v1/images/editsopenai/gpt-image-2.5-flarePython
import base64
from openai import OpenAI
client = OpenAI(
api_key="YOUR_OFOX_API_KEY",
base_url="https://api.ofox.ai/v1",
timeout=600, # 이미지 API는 동기식으로 응답하며 시간이 오래 걸릴 수 있습니다
)
resp = client.images.generate(
model="openai/gpt-image-2.5-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.ai/v1/images/generations요청 파라미터
아래의 허용 값과 기본값은 GPT Image 시리즈(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 모델은 지원하지 않으므로 전달하지 마십시오.
출력 파일 형식입니다.
▶고급 · 7output_compression · background · moderation · stream · partial_images · input_images · extra_body.provider.typeExpand
압축률이며 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.ai/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가 없습니다.
생성할 이미지 수이며, 각 이미지가 개별 과금됩니다.
▶고급 · 1X-OfoxAI-Provider-TypeExpand
공급자를 지정합니다. 선택 사항이며 보통은 필요하지 않습니다. 게이트웨이가 자동으로 라우팅합니다. 콘텐츠 심사와 관련된 요구가 있을 때 지정을 고려하십시오. 공급자를 지정하면 해당 공급자를 사용할 수 없을 때 다른 공급자로 전환되지 않습니다.
▸ 자세히
이 엔드포인트는 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.ai/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 두 공급자가 제공하며, 생성과 편집 모두 지원합니다. 지정하지 않으면 게이트웨이가 자동으로 라우팅합니다.
콘텐츠 심사와 관련된 요구가 있을 때 공급자를 지정할 수 있습니다. 지정하면 요청은 해당 공급자로만 전송되며, 그 공급자를 사용할 수 없을 때 다른 공급자로 자동 전환되지 않습니다.
해당 모델을 제공하지 않는 공급자를 지정하면 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.ai/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 시리즈

