Images API

兩個端點：生成（文字 → 圖）、編輯（圖 + 文字 → 圖）。回應都是 OpenAI 標準結構 data[0].b64_json。

我要做什麼	端點	支援的模型
文字生成圖片	`POST /v1/images/generations`	GPT Image、Nano Banana（Gemini）、Seedream、Qwen-Image、MAI Image 各系列
上傳圖片 + 指令改圖	`POST /v1/images/edits`	GPT 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.io/v1

文生圖介面https://api.ofox.io/v1/images/generations

改圖介面https://api.ofox.io/v1/images/edits

模型 IDopenai/gpt-image-2.5-flare

Python

gen.py


import base64
from openai import OpenAI
 
client = OpenAI(
    api_key="YOUR_OFOX_API_KEY",
    base_url="https://api.ofox.io/v1",
    timeout=600,  # 圖像介面同步回傳，耗時較長
)
 
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))

介面同步回傳，用戶端逾時請設為 600 秒。 高品質、大尺寸及改圖請求可能需要數分鐘，見實測耗時。

各系列呼叫方式一致，換模型只改 model。取值範圍與專屬參數不同，見下方各參數說明。

生成圖像


POST https://api.ofox.io/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。

▸ 詳情

支援的模型見本頁開頭的表格。建議填寫帶廠商前綴的完整 ID，如 openai/gpt-image-2.5-flare。

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.type展开

output_compressioninteger· 可選0–100

壓縮率，僅對 jpeg / webp 生效。

backgroundstring· 預設 opaque· 可選opaquetransparentauto

背景。transparent 需要支援 alpha 通道的格式（png / webp）。

moderationstring· 可選autolow

內容審核強度。

streamboolean· 可選truefalse

是否串流回傳。搭配 partial_images 可在生成過程中收到中間圖。

partial_imagesinteger· 可選0–3

串流回傳的中間圖張數，需同時傳入 stream: true。依 OpenAI 官方說明，每張中間圖額外計 100 個輸出 token。

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
  }
}

data[].b64_jsonstring

圖片的 base64 編碼，不帶 data:image/png;base64, 前綴。

▸ 詳情

解碼後寫入檔案；在瀏覽器中顯示需自行加上前綴。回應中沒有 url 欄位。

data[].indexinteger

圖片序號，n > 1 時用於區分多張圖片。

sizestring

實際輸出尺寸。未傳 size 或傳了 auto 時，從這裡讀取實際尺寸。

qualitystring

實際使用的品質檔位。未傳 quality 時，從這裡確認實際使用了哪一檔。

background · output_formatstring

實際使用的背景與格式。不一定回傳，請勿依賴這兩個欄位。

usageobject

計費用量。output_tokens 為輸出的圖片 token，input_tokens_details.text_tokens 為提示詞 token。

▸ 詳情

依這裡的數字核算單次成本。

編輯圖像


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 系列。

必填

model必填stringform

模型 ID，規則同生成介面。支援的模型見本頁開頭的表格。

image必填fileform· 可選PNGJPEG

參考圖，傳入本機檔案（cURL 用 @ 前綴），不是 URL。

▸ 詳情

多張時欄位名寫 image[] 重複傳入。單張 ≤ 15 MB，請求主體 ≤ 50 MB；張數閘道不另行限制，建議不超過 16 張。

prompt必填stringform

編輯指令。

常用

maskfileform· 可選PNG（帶 alpha）

局部重繪遮罩：帶 alpha 通道的 PNG，尺寸與 image 一致，透明區域 = 要重畫的部分。

▸ 詳情

只在本端點生效，傳到生成介面會被靜默忽略。製作方法與實測效果見 GPT Image · mask 局部重繪。

sizestringform· 預設 auto· 可選寬x高auto

輸出尺寸，限制同生成介面。

▸ 詳情

不傳或傳 auto 時由模型決定，不保證與原圖一致。若要保持原尺寸請明確傳入。

qualitystringform· 可選lowmediumhighxhighmaxauto

品質檔位，規則同生成介面：gpt-image-2 沒有 xhigh / max。

nintegerform· 預設 1· 可選1–10

生成張數，每張單獨計費。

▶進階 · 1X-OfoxAI-Provider-Type展开

X-OfoxAI-Provider-Typestringheader· 可選azure_foundryopenai

指定供應商。可選，通常不需要，閘道會自動路由。有內容審核方面的需求時可考慮指定；指定後若該供應商不可用，不會自動切換到其他供應商。

▸ 詳情

本端點是 multipart 上傳，若要固定供應商只能使用請求標頭，表單欄位 extra_body 會被靜默忽略。見進階：指定供應商。

回應

結構與生成介面相同，usage 中多出參考圖的輸入 token：

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
  }
}

usage.input_tokens_details.image_tokensinteger

參考圖折算成的輸入 token。實測一張 1024×1024 的參考圖計 1,024 個。改圖比同尺寸的文生圖貴，主要就貴在這一項。

usage.num_input_imagesinteger

參考圖張數。可用來確認參考圖確實已被模型讀取。

其餘欄位同生成介面的回應。

支援的模型與價格見模型目錄。

呼叫

Python

edit.py


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))

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.io/v1',
  timeout: 600_000, // 毫秒
})
 
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


curl -X POST 'https://api.ofox.io/v1/images/edits' \
  --max-time 600 \
  -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。

實測對比：

原圖	編輯後

錯誤

出錯時回傳 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 判斷。

狀態碼	錯誤	原因	處理方式
400	`Invalid size '…'`	尺寸不滿足四條限制	依 size 的規則調整
400	`does not support quality '…'` 或取值無效	`gpt-image-2` 傳了 `xhigh` / `max`；或傳了 `standard` / `hd`	改用 quality 列出的值
400	`Unknown parameter: '…'`	傳了不支援的欄位，如 DALL·E 的 `style`	移除該欄位
400	`Invalid image file or mode for image 1`	參考圖不是 PNG / JPEG；或 mask 不是帶 alpha 的 PNG、尺寸與原圖不一致	檢查 image 與 mask
400	`provider_type_unavailable`	指定的供應商不提供該模型	移除供應商參數，讓閘道自動路由
404	`model_not_found`	模型 ID 拼錯或大小寫不符	從本頁表格複製完整 ID
429	`rate_limit_exceeded`	超過每個團隊 100 RPM；多建 Key 不會提高上限	降低並行數，退避後重試

聯絡支援時，請附上回應中的 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_foundry`	微軟雲端託管	較嚴格
`openai`	OpenAI 官方 API	相對寬鬆

openai/gpt-image-2 的兩個供應商審核尺度不同。提示詞反覆被拒時，可以明確指定 openai。未指定時請求會被加權分流，可能落到 azure_foundry。

文生圖 `/v1/images/generations`

JSON 請求主體，請求主體欄位 extra_body.provider.type 與請求標頭 X-OfoxAI-Provider-Type 兩種寫法均可。

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.io/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 在參數物件中直接撰寫 extra_body 即可。Python SDK 的 extra_body= 參數會將內容合併到請求主體頂層，因此需額外巢狀一層，或改用請求標頭。

圖生圖 `/v1/images/edits`

multipart 上傳沒有可供巢狀 extra_body 的 JSON 請求主體，因此只能使用請求標頭。

Terminal


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 官方

OfoxAI 系列頁

Images API

快速開始

Python

cURL

生成圖像

請求參數

回應

編輯圖像

請求參數

回應

呼叫

Python

TypeScript

cURL

錯誤

進階：指定供應商

文生圖 /v1/images/generations

Python

TypeScript

cURL

圖生圖 /v1/images/edits

官方文件與延伸閱讀

文生圖 `/v1/images/generations`

圖生圖 `/v1/images/edits`