Skip to Content
API 레퍼런스OpenAI 호환 프로토콜Images

Images API

엔드포인트는 두 개입니다. 생성(텍스트 → 이미지)과 편집(이미지 + 텍스트 → 이미지)이며, 응답은 모두 OpenAI 표준 구조 data[0].b64_json을 따릅니다.

하려는 작업엔드포인트지원 모델
텍스트로 이미지 생성POST /v1/images/generationsGPT Image, Nano Banana(Gemini), Seedream, Qwen-Image, MAI Image 각 시리즈
이미지를 업로드하고 지시문으로 편집POST /v1/images/editsGPT Image, Nano Banana(Gemini), MAI Image

Seedream과 Qwen-Image는 /v1/images/edits를 지원하지 않으며, 이미지-투-이미지는 generations 엔드포인트로 수행합니다. 단, 참조 이미지 필드가 다릅니다. Seedream은 image, Qwen은 input_images를 사용하므로 서로 바꿔 쓰지 않도록 주의하십시오. Gemini에서 해상도(512~4K)를 제어해야 할 때는 Gemini 네이티브 프로토콜을 사용하십시오. 시리즈별 파라미터 차이는 해당 시리즈 페이지를 참고하십시오.

빠른 시작

바로 실행할 수 있는 최소 요청입니다. 1024×1024 이미지 한 장을 생성하고 디코딩하여 output.png로 저장합니다.

base_urlhttps://api.ofox.ai/v1
생성 엔드포인트https://api.ofox.ai/v1/images/generations
편집 엔드포인트https://api.ofox.ai/v1/images/edits
모델 IDopenai/gpt-image-2.5-flare
gen.py
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 시리즈를 참고하십시오.

필수
model필수string

모델 ID입니다. 대소문자를 구분하며, 잘못 입력하면 404 model_not_found가 반환됩니다.

▸ 자세히

지원 모델은 이 페이지 상단의 표를 참고하십시오. openai/gpt-image-2.5-flare처럼 공급업체 접두사를 포함한 전체 ID를 사용하는 것을 권장합니다.

prompt필수string

생성할 이미지를 설명합니다.

자주 사용
sizestring· 기본값 auto· 허용 값너비x높이auto

출력 크기입니다. 너비와 높이를 직접 지정할 수 있지만 네 가지 제약을 충족해야 하며, 그렇지 않으면 400 Invalid size가 반환됩니다.

▸ 자세히

네 가지 제약:

  • 너비와 높이 모두 16으로 나누어떨어질 것
  • 긴 변 ≤ 3840
  • 종횡비 1:3 ~ 3:1
  • 총 픽셀 수 ≥ 655,360(768x768은 거부되고 1024x768은 허용됨)

생략하거나 auto로 두면 모델이 결정하며, 실측 결과 1254×1254가 반환되었습니다. 고정 크기가 필요하면 명시적으로 지정하십시오. 다른 시리즈는 크기 규칙이 다르므로 해당 시리즈 페이지를 참고하십시오. 자세한 내용은 GPT Image · 크기를 참고하십시오.

qualitystring· 허용 값lowmediumhighxhighmaxauto

품질 단계이며 가격에 직접 영향을 줍니다. gpt-image-2에는 xhigh / max가 없습니다.

▸ 자세히
  • gpt-image-2에는 xhigh / max가 없으며, 전달하면 400이 반환됩니다.
  • DALL·E 시절의 standard / hd는 허용되지 않으며, 전달하면 400이 반환됩니다.
  • 생략하는 것은 medium과 같지 않습니다. 모델이 단계를 직접 선택합니다(실측 결과 low). 품질과 비용을 안정적으로 유지하려면 명시적으로 지정하십시오.

다른 시리즈는 대부분 품질 단계가 없으므로 해당 시리즈 페이지를 참고하십시오. 자세한 내용은 GPT Image · 품질을 참고하십시오.

ninteger· 기본값 1· 허용 값1–10

생성할 이미지 수이며, 각 이미지가 개별 과금됩니다. Gemini 모델은 지원하지 않으므로 전달하지 마십시오.

output_formatstring· 기본값 png· 허용 값pngjpegwebp

출력 파일 형식입니다.

▶고급 · 7output_compression · background · moderation · stream · partial_images · input_images · extra_body.provider.typeExpand
output_compressioninteger· 허용 값0–100

압축률이며 jpeg / webp에만 적용됩니다.

backgroundstring· 기본값 opaque· 허용 값opaquetransparentauto

배경입니다. transparent에는 알파 채널을 지원하는 형식(png / webp)이 필요합니다.

moderationstring· 허용 값autolow

콘텐츠 심사 강도입니다.

streamboolean· 허용 값truefalse

스트리밍 응답 여부입니다. partial_images와 함께 사용하면 생성 도중 중간 이미지를 받을 수 있습니다.

partial_imagesinteger· 허용 값0–3

스트리밍으로 받을 중간 이미지 수이며, stream: true가 필요합니다. OpenAI 공식 문서에 따르면 중간 이미지 한 장마다 출력 토큰 100개가 추가로 과금됩니다.

input_imagesstring[]· 허용 값1–3장

참조 이미지 배열(URL 또는 base64)이며, Qwen 시리즈만 지원합니다. 1–3장을 전달할 수 있습니다.

▸ 자세히

다른 시리즈는 전달해도 오류 없이 적용되지 않습니다. Seedream의 참조 이미지 필드는 image입니다.

extra_body.provider.typestring· 허용 값azure_foundryopenai

공급자를 지정합니다. 선택 사항이며 보통은 필요하지 않습니다. 게이트웨이가 자동으로 라우팅합니다. 콘텐츠 심사와 관련된 요구가 있을 때 지정을 고려하십시오. 공급자를 지정하면 해당 공급자를 사용할 수 없을 때 다른 공급자로 전환되지 않습니다.

▸ 자세히

요청 헤더 X-OfoxAI-Provider-Type과 동일합니다. 고급: 공급자 지정을 참고하십시오.

응답

200 OK (b64_json 일부 생략)
{ "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일 때 여러 이미지를 구분합니다.

sizestring

실제 출력 크기입니다. size를 생략했거나 auto로 보낸 경우 여기에서 실제 크기를 확인하십시오.

qualitystring

실제로 사용된 품질 단계입니다. quality를 생략한 경우 여기에서 어떤 단계가 사용되었는지 확인할 수 있습니다.

실제로 사용된 배경과 형식입니다. 항상 반환되지는 않으므로 이 필드에 의존하지 마십시오.

usageobject

과금 사용량입니다. 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 시리즈에 적용됩니다.

필수
model필수stringform

모델 ID이며, 규칙은 생성 엔드포인트와 같습니다. 지원 모델은 이 페이지 상단의 표를 참고하십시오.

image필수fileform· 허용 값PNGJPEG

참조 이미지이며, URL이 아닌 로컬 파일로 전달합니다(cURL에서는 @ 접두사 사용).

▸ 자세히

여러 장일 때는 필드 이름을 image[]로 하여 반복 전달합니다. 파일당 ≤ 15 MB, 요청 본문 ≤ 50 MB입니다. 게이트웨이는 장수를 별도로 제한하지 않으며, 16장 이하를 권장합니다.

prompt필수stringform

편집 지시문입니다.

자주 사용
maskfileform· 허용 값PNG(알파 채널 포함)

인페인팅 마스크입니다. 알파 채널이 있는 PNG이며 image와 크기가 같아야 합니다. 투명 영역 = 다시 그려지는 부분입니다.

▸ 자세히

이 엔드포인트에서만 적용되며, 생성 엔드포인트로 보내면 조용히 무시됩니다. 만드는 방법과 실측 효과는 GPT Image · 마스크 인페인팅을 참고하십시오.

sizestringform· 기본값 auto· 허용 값너비x높이auto

출력 크기이며, 제약은 생성 엔드포인트와 같습니다.

▸ 자세히

생략하거나 auto로 두면 모델이 결정하며, 원본과 같다는 보장은 없습니다. 원본 크기를 유지하려면 명시적으로 지정하십시오.

qualitystringform· 허용 값lowmediumhighxhighmaxauto

품질 단계이며, 규칙은 생성 엔드포인트와 같습니다. gpt-image-2에는 xhigh / max가 없습니다.

nintegerform· 기본값 1· 허용 값1–10

생성할 이미지 수이며, 각 이미지가 개별 과금됩니다.

▶고급 · 1X-OfoxAI-Provider-TypeExpand
X-OfoxAI-Provider-Typestringheader· 허용 값azure_foundryopenai

공급자를 지정합니다. 선택 사항이며 보통은 필요하지 않습니다. 게이트웨이가 자동으로 라우팅합니다. 콘텐츠 심사와 관련된 요구가 있을 때 지정을 고려하십시오. 공급자를 지정하면 해당 공급자를 사용할 수 없을 때 다른 공급자로 전환되지 않습니다.

▸ 자세히

이 엔드포인트는 multipart 업로드이므로 공급자를 지정하려면 요청 헤더만 사용할 수 있으며, 폼 필드 extra_body는 조용히 무시됩니다. 고급: 공급자 지정을 참고하십시오.

응답

구조는 생성 엔드포인트와 같으며, usage에 참조 이미지의 입력 토큰이 추가됩니다.

200 OK (b64_json 일부 생략)
{ "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개가 계산되었습니다. 같은 크기의 텍스트 기반 이미지 생성보다 편집 비용이 높은 주된 이유가 이 항목입니다.

참조 이미지 수입니다. 모델이 참조 이미지를 실제로 읽었는지 확인하는 데 사용할 수 있습니다.

나머지 필드는 생성 엔드포인트의 응답과 같습니다.

지원 모델과 가격은 모델 카탈로그 에서 확인하십시오.

호출

edit.py
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 오류 상태 코드와 함께 다음 구조가 반환됩니다(실측).

400 Bad Request
{ "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로 판단하십시오.

상태 코드오류원인해결 방법
400Invalid size '…'크기가 네 가지 제약을 충족하지 않음size의 규칙에 맞게 조정
400does not support quality '…' 또는 유효하지 않은 값gpt-image-2에 xhigh / max를 전달했거나 standard / hd를 전달함quality에 나열된 값을 사용
400Unknown parameter: '…'지원하지 않는 필드를 전달함(예: DALL·E의 style)해당 필드를 제거
400Invalid image file or mode for image 1참조 이미지가 PNG / JPEG가 아니거나, 마스크가 알파 채널이 있는 PNG가 아니거나 원본과 크기가 다름image와 mask를 확인
400provider_type_unavailable지정한 공급자가 이 모델을 제공하지 않음공급자 지정을 제거하고 게이트웨이가 자동으로 라우팅하도록 함
404model_not_found모델 ID의 철자 또는 대소문자가 틀림이 페이지의 표에서 전체 ID를 복사
429rate_limit_exceeded팀당 100 RPM을 초과함. 키를 더 만들어도 한도는 늘어나지 않음동시 요청 수를 줄이고 백오프 후 재시도

지원팀에 문의할 때는 응답의 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이 반환됩니다.

공급자설명콘텐츠 심사(gpt-image-2)
azure_foundryMicrosoft Azure에서 호스팅엄격한 편
openaiOpenAI 공식 API상대적으로 완화

openai/gpt-image-2의 두 공급자는 심사 기준이 다릅니다. 프롬프트가 반복해서 거부되면 openai를 명시적으로 지정할 수 있습니다. 지정하지 않으면 가중 분배에 따라 azure_foundry로 전송될 수 있습니다.

텍스트로 이미지 생성 /v1/images/generations

JSON 본문이므로 본문 필드 extra_body.provider.type과 요청 헤더 X-OfoxAI-Provider-Type 중 어느 쪽이든 사용할 수 있습니다.

gen_pinned.py
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 본문이 없으므로 요청 헤더만 사용할 수 있습니다.

Terminal
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 공식

OfoxAI 시리즈 페이지

마지막 업데이트