OpenAI 圖像格式

RouteAPI 透過 OpenAI 相容的 images 端點提供圖像生成能力。本頁說明所有廠商共用的請求格式，以及 OpenAI gpt-image 系列——目前在售的是 gpt-image-2。其他廠商的請求會被適配到同一組端點，模型特有的行為另行說明：Nano Banana 介紹 Gemini 圖像模型，Seedream 介紹火山引擎 Seedream。

一個模型能否生成圖像，可以在模型列表中看到：其 supported_endpoint_types 包含 image-generation。欄位的讀法見模型。

端點

POST /v1/images/generations
POST /v1/images/edits

完整地址：

https://api.routeapi.ai/v1/images/generations
https://api.routeapi.ai/v1/images/edits

/v1/images/generations 接收 JSON 請求體。/v1/images/edits 接收 multipart/form-data——或者在 OpenAI 相容渠道上，接收透過 URL 或 Base64 引用圖像的 JSON 請求體（見 JSON 編輯）。

生成圖像

請求參數

欄位	類型	必填	說明
`model`	string	是	來自 `GET /v1/models` 的模型 ID，例如 `gpt-image-2`
`prompt`	string	是	待生成圖像的文字描述
`n`	integer	否	圖像數量，上限 `128`。省略或為 `0` 時視為 `1`
`size`	string	否	輸出尺寸，例如 `1024x1024`、`1024x1536`，或 `1K` / `2K` 這類分檔，取決於模型。在 JSON 請求體中請用 `x` 作為分隔符——使用全形 `×` 會被拒絕並回傳 `400`
`quality`	string	否	品質等級，例如 `standard`、`hd`、`high`、`medium`、`low` 或 `auto`。可接受的值取決於模型
`response_format`	string	否	`url` 或 `b64_json`。會原樣轉發給上游；模型實際採用哪個值由供應商決定
`style`	string	否	風格提示（例如 `vivid` 或 `natural`）。僅對接受該參數的模型有意義
`user`	string	否	終端使用者識別碼，轉發給上游
`watermark`	boolean	否	是否為輸出加上浮水印，僅對支援該參數的供應商有效

網關還能識別的欄位包括 background、output_format、output_compression、input_fidelity、moderation 和 partial_images，請求中帶上時會轉發給 OpenAI 相容上游。網關不認得的 JSON 欄位會被丟棄、不會轉發，除非該渠道開啟了請求體透傳。

請求範例

curl https://api.routeapi.ai/v1/images/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A calico cat playing a piano on a small stage, soft studio lighting",
    "size": "1024x1024",
    "n": 1
  }'

Python（OpenAI SDK）

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],
    base_url="https://api.routeapi.ai/v1",
)

result = client.images.generate(
    model="gpt-image-2",
    prompt="A calico cat playing a piano on a small stage, soft studio lighting",
    size="1024x1024",
    n=1,
)

for item in result.data:
    print(item.url or item.b64_json[:40])

回應

OpenAI 相容渠道會原樣回傳上游回應體。取決於模型，data[] 中會出現 b64_json、url 或兩者，讀到哪個用哪個。

{
  "created": 1740000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 4160,
    "total_tokens": 4172
  }
}

欄位	說明
`created`	生成時間的 Unix 時間戳
`data`	生成的圖像陣列，每張圖一項
`data[].url`	上游回傳 URL 時的圖像位址
`data[].b64_json`	上游回傳 Base64 時的圖像位元組
`data[].revised_prompt`	模型給出改寫 prompt 時回傳
`usage`	token 用量，僅在上游回傳時存在

url / b64_json 用哪個讀哪個，不要假設兩者都會出現；解析時把 usage 當作可選欄位。

編輯圖像

POST /v1/images/edits 根據 prompt 修改已有圖像，可選擇性傳入遮罩。

multipart 欄位

欄位	類型	必填	說明
`model`	string	是	來自 `GET /v1/models` 的模型 ID
`image`	file	是	來源圖像。重複該欄位或使用 `image[]` 可傳多張
`prompt`	string	是	描述編輯指令
`mask`	file	否	標記待編輯區域的遮罩圖。遮罩語義由上游模型定義
`n`	integer	否	結果數量，上限 `128`（預設 `1`）
`size`	string	否	輸出尺寸，規則與生成相同
`quality`	string	否	模型接受的品質等級
`watermark`	boolean	否	是否為輸出加上浮水印

其他表單欄位會原樣轉發給 OpenAI 相容上游，因此 response_format、input_fidelity 等參數可以透傳。

multipart 請求範例

curl https://api.routeapi.ai/v1/images/edits \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -F model="gpt-image-2" \
  -F prompt="Replace the background with a sunset beach" \
  -F image=@"cat.png" \
  -F size="1024x1024"

Python（OpenAI SDK）

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],
    base_url="https://api.routeapi.ai/v1",
)

with open("cat.png", "rb") as image:
    result = client.images.edit(
        model="gpt-image-2",
        image=image,
        prompt="Replace the background with a sunset beach",
        size="1024x1024",
    )

print(result.data[0].b64_json[:40])

JSON 編輯

在 OpenAI 相容渠道上，/v1/images/edits 也接受 JSON 請求體。RouteAPI 會下載或解碼每個圖像引用，並在上游重建 multipart 請求——當圖像已經託管在 URL 上或是 Base64 字串時，用這種方式。

curl https://api.routeapi.ai/v1/images/edits \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Repaint this photo as a watercolor illustration",
    "images": [
      { "image_url": "https://example.com/photo.png" }
    ],
    "size": "1024x1024"
  }'

images 中每一項可以包含 image_url（或 url），值為 http(s) 連結或 data:image/...;base64,... 字串。mask 使用相同的結構。該路徑要求 images 陣列，單獨的 image 欄位不會被讀取。其他渠道族可能仍然要求真正的 multipart 請求體，因此在依賴 JSON 編輯前，請先測試目標模型。

同一端點上的其他廠商

端點以及 prompt / n / size 這套請求格式是共用的，但各廠商適配器對它們的映射方式不同。

廠商系列	頁面
Google Gemini 圖像模型（`gemini--image`）	Nano Banana
火山引擎 Seedream（`seedream-5.0-pro`、`seedream-5.0-lite`）	Seedream

計費

gpt-image 模型按 token 計費：生成的圖像計為輸出 token，按輸出價格收費；prompt 和參考圖計為輸入 token。尺寸更大、品質更高的輸出會消耗更多 token。完整規則見模型定價，具體採用哪種方式以模型詳情頁為準。

在按尺寸分檔的按張計費模型上，價格在選渠道之前根據你請求的 size 對應的像素數確定；n 按張計費，省略或無法識別的 size 會回退到最高單價。

錯誤與限制

狀態碼	含義	常見原因
400	請求無效	缺少 `model`、`n` 超過 `128`、模型不支援該 `size`、在 JSON 請求體中用 `×` 作為尺寸分隔符
401	認證失敗	API Key 缺失、無效、過期或額度耗盡
403	餘額或額度不足	`insufficient_user_quota` 或 `pre_consume_token_quota_failed`；儲值或提高 Key 額度
429	觸發限流	降低並行
500	轉換或內部錯誤	請求無法為所選渠道轉換，或編輯請求沒有可用圖像
501	`api_not_implemented`	端點存在但不受支援

POST /v1/images/variations 不受支援，會回傳 501，錯誤碼為 api_not_implemented，請改用基於 prompt 的編輯。/v1/images/edits 至少需要一張圖像，image、image[] 以及 image[0] 形式的表單欄位名均可識別。

接下來

Nano Banana — Gemini 圖像模型，包括原生 generateContent 呼叫方式。
Seedream — 火山引擎 Seedream 的尺寸、連續生成與編輯。
模型 — 查找圖像模型並確認 image-generation 支援。
模型定價 — 按 token 與按張計費、尺寸分檔。
常見錯誤 — 共用的狀態碼與錯誤回應體格式。