Images API

엔드포인트는 두 개：생성（텍스트 → 이미지）, 편집（이미지 + 텍스트 → 이미지）. 응답은 모두 OpenAI 표준 구조 data[0].b64_json입니다.

하려는 작업	엔드포인트	지원 모델
텍스트로 이미지 생성	`POST /v1/images/generations`	`openai/gpt-image-2`, `google/gemini-3.1-flash-image`, `bailian/qwen-image-3.0-pro`
이미지를 업로드하고 지시문으로 편집	`POST /v1/images/edits`	OpenAI / Azure 전용: `openai/gpt-image-2`, `openai/gpt-image-1.5`

이미지-투-이미지에는 두 가지 예외가 있습니다. Qwen 계열은 edits가 아니라 generations 엔드포인트의 input_images 필드를 사용합니다. Gemini 계열은 이 페이지의 두 엔드포인트 모두에서 편집할 수 없으므로 Gemini 네이티브 프로토콜을 사용하세요.

공급자 지정

provider.type은 요청을 특정 공급자에 고정합니다. 둘 이상의 공급자가 제공하는 모델에서만 의미가 있으며, 현재는 openai/gpt-image-2(azure_foundry와 openai)입니다. 해당 모델을 제공하지 않는 공급자를 지정하면 400 provider_type_unavailable이 반환됩니다.

공급자	설명	콘텐츠 심사
`azure_foundry`	Microsoft Azure에서 호스팅	엄격한 편
`openai`	OpenAI 공식 API	상대적으로 완화

openai/gpt-image-2의 두 공급자는 심사 기준이 다릅니다: azure_foundry는 엄격한 편, openai는 상대적으로 완화되어 있습니다. 프롬프트가 반복해서 거부되면 provider.type: "openai"를 명시적으로 지정하세요 — 지정하지 않으면 가중 분배로 azure_foundry에 걸릴 수 있습니다.

전체 참고는 API · 공급자 라우팅을 보세요.

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

/v1/images/generations은 JSON 본문이므로 본문 필드와 헤더 모두 사용할 수 있습니다.

Python

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"}}},
)

TypeScript

gen_pinned.ts


const resp = await client.images.generate({
  model: 'openai/gpt-image-2',
  prompt: 'A simple red apple on a white table',
  size: '1024x1024',
  extra_body: { provider: { type: 'openai' } },
})

cURL

Terminal


curl https://api.ofox.run/v1/images/generations \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "...",
    "n": 1,
    "size": "1024x1024",
    "extra_body": { "provider": { "type": "openai" } }
  }'

공식 OpenAI SDK를 사용할 때 extra_body는 요청 본문에 문자 그대로의 키로 존재해야 합니다. TypeScript SDK는 파라미터 객체에 작성한 그대로 전송합니다. Python SDK의 extra_body= 인자는 내용을 본문 최상위로 병합하므로, 키를 한 단계 더 중첩하거나 요청 헤더로 전달해야 합니다.

이미지 편집 — `/v1/images/edits`

/v1/images/edits는 multipart 업로드라 extra_body를 중첩할 JSON 본문이 없습니다. 따라서 여기서는 헤더만 유효합니다. extra_body를 폼 필드로 넘기면 무시되고 제약 없이 요청이 진행됩니다.

Terminal


curl https://api.ofox.run/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"

/v1/images/edits에서 폼 필드로 넘긴 extra_body는 조용히 무시됩니다 — 이미지는 생성되지만 제약이 적용되지 않습니다. X-OfoxAI-Provider-Type을 사용하세요.

이미지 생성


POST https://api.ofox.run/v1/images/generations

파라미터

파라미터	타입	필수	설명
`model`	string	✅	`openai/gpt-image-2`, `google/gemini-3.1-flash-image`, `bailian/qwen-image-3.0-pro`
`prompt`	string	✅	자연어 설명
`quality`	string	✅	`auto` / `low` / `medium` / `high` / `standard` / `hd`
`n`	number	—	1–10, 기본값 1. Gemini 모델은 미지원
`size`	string	—	`auto` / `1024x1024` / `1536x1024` / `1024x1536` / `256x256` / `512x512` / `1792x1024` / `1024x1792`
`input_images`	string[]	—	참조 이미지 배열（URL 또는 base64）. Qwen 계열 이미지 모델 지원, 1–3장. 적용 시 응답에 `usage.num_input_images` 포함
`output_format`	string	—	`png` / `jpeg` / `webp`
`background`	string	—	`transparent` / `opaque` / `auto`
`stream`	boolean	—	기본값 `false`
`extra_body.provider.type`	string	—	공급자를 지정합니다. 여러 공급자가 제공하는 모델에서만 의미가 있습니다（본 엔드포인트에서는 현재 `openai/gpt-image-2`）. 헤더 `X-OfoxAI-Provider-Type`와 동등합니다

응답


{
  "created": 1777385517,
  "data": [
    { "b64_json": "<이미지 Base64>", "index": 0 }
  ],
  "model": "openai/gpt-image-2",
  "size": "1024x1024",
  "quality": "low",
  "usage": {
    "input_tokens": 14,
    "input_tokens_details": { "text_tokens": 14 },
    "output_tokens": 208,
    "total_tokens": 222
  }
}

이미지는 data[0].b64_json에 있으며, base64 디코딩 후 직접 저장하세요.

OpenAI 계열（gpt-image-2）

Python

gen.py


import base64
from openai import OpenAI
 
client = OpenAI(api_key="YOUR_OFOX_API_KEY", base_url="https://api.ofox.run/v1")
 
resp = client.images.generate(
    model="openai/gpt-image-2",
    prompt="A simple red apple on a white table",
    size="1024x1024",
    quality="low",
    output_format="png",
    # 선택: 공급자 지정. 생략하면 플랫폼이 자동으로 라우팅합니다
    # extra_body={"extra_body": {"provider": {"type": "openai"}}},
)
 
with open("output.png", "wb") as f:
    f.write(base64.b64decode(resp.data[0].b64_json))

TypeScript

gen.ts


import OpenAI from 'openai'
import fs from 'node:fs'
 
const client = new OpenAI({ apiKey: 'YOUR_OFOX_API_KEY', baseURL: 'https://api.ofox.run/v1' })
 
const resp = await client.images.generate({
  model: 'openai/gpt-image-2',
  prompt: 'A simple red apple on a white table',
  size: '1024x1024',
  quality: 'low',
  output_format: 'png',
  // 선택: 공급자 지정. 생략하면 플랫폼이 자동으로 라우팅합니다
  // extra_body: { provider: { type: 'openai' } },
})
 
fs.writeFileSync('output.png', Buffer.from(resp.data[0].b64_json!, 'base64'))

cURL

Terminal


# 선택: 공급자 지정. 생략하면 플랫폼이 자동으로 라우팅합니다
# "extra_body": { "provider": { "type": "openai" } }
curl -X POST 'https://api.ofox.run/v1/images/generations' \
  -H 'Authorization: Bearer YOUR_OFOX_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "A simple red apple on a white table",
    "size": "1024x1024",
    "quality": "low",
    "output_format": "png"
  }'

실제 출력：

gpt-image-2가 생성한 빨간 사과

Gemini 계열（gemini-3.1-flash-image）

같은 엔드포인트에서 Gemini 이미지 모델도 사용할 수 있습니다. n을 전달하지 마세요 —— 게이트웨이가 n을 numberOfImages 필드로 잘못 매핑하여 400 오류를 반환하며, 매번 1장만 고정 생성됩니다.

Python

gen_gemini.py


import base64
from openai import OpenAI
 
client = OpenAI(api_key="YOUR_OFOX_API_KEY", base_url="https://api.ofox.run/v1")
 
resp = client.images.generate(
    model="google/gemini-3.1-flash-image",
    prompt="A simple red apple on a white table, photorealistic",
    size="1024x1024",
    quality="low",
    output_format="png",
)
 
with open("output.png", "wb") as f:
    f.write(base64.b64decode(resp.data[0].b64_json))

TypeScript

gen_gemini.ts


import OpenAI from 'openai'
import fs from 'node:fs'
 
const client = new OpenAI({ apiKey: 'YOUR_OFOX_API_KEY', baseURL: 'https://api.ofox.run/v1' })
 
const resp = await client.images.generate({
  model: 'google/gemini-3.1-flash-image',
  prompt: 'A simple red apple on a white table, photorealistic',
  size: '1024x1024',
  quality: 'low',
  output_format: 'png',
})
 
fs.writeFileSync('output.png', Buffer.from(resp.data[0].b64_json!, 'base64'))

cURL

Terminal


curl -X POST 'https://api.ofox.run/v1/images/generations' \
  -H 'Authorization: Bearer YOUR_OFOX_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "google/gemini-3.1-flash-image",
    "prompt": "A simple red apple on a white table, photorealistic",
    "size": "1024x1024",
    "quality": "low"
  }'

실제 출력：

Gemini가 생성한 빨간 사과

Qwen 계열（qwen-image-3.0-pro）

bailian/qwen-image-3.0-pro 등 Qwen 이미지 모델은 본 엔드포인트에서 참조 이미지（1–3장）를 직접 전달해 이미지-투-이미지 및 편집을 수행할 수 있습니다. 필드는 input_images（요소는 이미지 URL 또는 base64）입니다:

Terminal


curl -X POST 'https://api.ofox.run/v1/images/generations' \
  -H 'Authorization: Bearer YOUR_OFOX_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "bailian/qwen-image-3.0-pro",
    "prompt": "사과를 파란색으로 바꾸고 나머지는 그대로 두세요",
    "size": "1024x1024",
    "input_images": ["https://example.com/ref-apple.png"]
  }'

참조 이미지가 적용되면 응답의 usage에 num_input_images（입력 이미지 수）가 포함됩니다. 모델이 실제로 읽었는지 프로그램으로 확인할 수 있습니다.

필드명은 반드시 input_images여야 합니다. image_urls, image, images 같은 다른 표기는 조용히 무시되어 요청이 단순 텍스트-투-이미지로 축소됩니다（HTTP는 그대로 200）.

이미지 편집


POST https://api.ofox.run/v1/images/edits

multipart/form-data로 이미지 파일을 업로드해야 합니다.

이 엔드포인트는 OpenAI / Azure OpenAI 모델만 지원합니다. google/gemini-3.1-flash-image를 호출하면 Image editing is not supported for model 오류가 반환됩니다 —— Gemini 네이티브 프로토콜로 이미지 편집을 사용하세요.

파라미터

파라미터	타입	필수	설명
`model`	string	✅	`openai/gpt-image-2` 권장
`image`	file	✅	PNG / JPEG 파일. 파일당 최대 15 MB, 요청당 최대 16장, 요청 본문 합계 50 MB. 파일당 5 MB 이내를 권장합니다: 모델이 입력 이미지를 약 1024 px 캔버스로 축소하므로 더 큰 파일은 업로드 시간만 늘어납니다
`prompt`	string	✅	편집 지시문
`quality`	string	✅	`low` / `medium` / `high`
`n`	number	—	기본값 1
`size`	string	—	`auto`는 원본과 동일한 크기
`X-OfoxAI-Provider-Type`	헤더	—	공급자를 지정합니다. 본 엔드포인트는 multipart 업로드이므로 헤더만 유효하며, 폼 필드 `extra_body`는 조용히 무시됩니다

응답

생성 응답과 동일：


{
  "created": 1777385669,
  "data": [
    { "b64_json": "<편집된 이미지 Base64>", "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
  }
}

usage.input_tokens_details.image_tokens는 입력 이미지가 소비한 토큰이며, num_input_images는 입력 이미지 장수입니다.

지원 모델과 가격은 모델 카탈로그 에서 확인하세요.

호출

Python

edit.py


import base64
from openai import OpenAI
 
client = OpenAI(api_key="YOUR_OFOX_API_KEY", base_url="https://api.ofox.run/v1")
 
with open("apple.png", "rb") as f:
    resp = client.images.edit(
        model="openai/gpt-image-2",
        image=f,
        prompt="사과를 초록색으로 바꾸고, 나머지는 그대로 두세요",
        size="auto",
        quality="low",
        # 선택: 공급자 지정. 본 엔드포인트는 multipart이므로 헤더만 유효합니다
        # extra_headers={"X-OfoxAI-Provider-Type": "openai"},
    )
 
with open("apple_edited.png", "wb") as out:
    out.write(base64.b64decode(resp.data[0].b64_json))

TypeScript

edit.ts


import OpenAI, { toFile } from 'openai'
import fs from 'node:fs'
 
const client = new OpenAI({ apiKey: 'YOUR_OFOX_API_KEY', baseURL: 'https://api.ofox.run/v1' })
 
// 선택: 공급자 지정. 본 엔드포인트는 multipart이므로 헤더만 유효합니다
// 두 번째 인자로 { headers: { 'X-OfoxAI-Provider-Type': 'openai' } } 를 전달합니다
const resp = await client.images.edit({
  model: 'openai/gpt-image-2',
  image: await toFile(fs.createReadStream('apple.png'), 'apple.png'),
  prompt: '사과를 초록색으로 바꾸고, 나머지는 그대로 두세요',
  size: 'auto',
  quality: 'low',
})
 
fs.writeFileSync('apple_edited.png', Buffer.from(resp.data[0].b64_json!, 'base64'))

cURL

Terminal


# 선택: 공급자 지정. 본 엔드포인트는 multipart이므로 헤더만 유효합니다
# -H 'X-OfoxAI-Provider-Type: openai' \
curl -X POST 'https://api.ofox.run/v1/images/edits' \
  -H 'Authorization: Bearer YOUR_OFOX_API_KEY' \
  -F 'model="openai/gpt-image-2"' \
  -F 'prompt="사과를 초록색으로 바꾸고, 나머지는 그대로 두세요"' \
  -F 'image=@/path/to/apple.png' \
  -F 'size="auto"' \
  -F 'quality="low"'

image 필드에는 로컬 파일 경로를 전달하세요（cURL은 @ 접두사 사용）. URL이 아닙니다.

실제 비교：

원본	편집 후

Images API

공급자 지정

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

Python

TypeScript

cURL

이미지 편집 — /v1/images/edits

이미지 생성

파라미터

응답

OpenAI 계열（gpt-image-2）

Python

TypeScript

cURL

Gemini 계열（gemini-3.1-flash-image）

Python

TypeScript

cURL

Qwen 계열（qwen-image-3.0-pro）

이미지 편집

파라미터

응답

호출

Python

TypeScript

cURL

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

이미지 편집 — `/v1/images/edits`