OpenRouter 發布圖片生成 API 指南：模型選擇、引數支援與錯誤排查

《影像生成教學》會帶你逐步完成請求本身。你將模型與提示送往 POST /api/v1/images，解碼 data[0].b64_json，然後將位元組寫入磁碟。本本文說明瞭教學中留給你的兩項決策。哪個模型放在 model 欄位，以及當 API 回傳錯誤而非影像時應該如何處理。

《模型目錄》在端點背後涵蓋主要的影像實驗室，且 slug 隨每次發布而變更。目錄的變更使得模型選擇需採用方法而非書籤，也解釋了為何有些錯誤訊息屢次出現。

簡言之

• 先按工作類別挑選模型（文字轉圖、編輯參考圖、向量輸出、可讀文字），再按引數支援，最後按價格。GET /api/v1/images/models 列出 Image API 所提供的每一個模型，並結合其供應商的 supported_parameters，每一項都連結到供應商細節。
• 資料顯示，我們的 對照 將一個提示送進 20 個模型並記錄每個模型的費用，且 影像基準測試 在 15 個提示上評分 39 個模型。
• 沒有任何影像模型帶有 :free 字尾，因此每次生成都會扣除您的信用餘額。低成本模型每張圖約一分。
• 「No endpoints found that support image input」表示你將影像送往 /chat/completions 上不接受影像輸入的模型。請切換到其 input_modalities 包含 image 的模型。
• 在 /api/v1/images，若收到 400 或 404 並引用你的模型 slug，表示 slug、功能或供應商過濾器有問題。疑難排解區段 將每個訊息對應到對應的修復方法。
• 一旦你擁有模型，教學中包含可執行的 Python 與 JavaScript 呼叫範例。

哪些影像模型可用？

目錄包括 Google (the Gemini image family)、OpenAI (GPT Image)、Black Forest Labs (FLUX)、xAI (Grok Imagine)、ByteDance (Seedream)、Microsoft (MAI-Image)、Recraft、Krea、以及 Sourceful (Riverflow)。具體模型名稱隨每次發布而變動，若要查詢目前的組合、功能與每模型價格，請參考 影像模型目錄。

尋找影像模型的三種方式：

• 從程式碼： GET /api/v1/images/models 列出所有 POST /api/v1/images 接受的模型。GET /api/v1/models?output_modalities=image 回傳更廣泛的影像輸出模型，包括僅透過 /chat/completions 產生的模型。
• 從 UI： 模型頁面篩選器 以視覺方式呈現相同結果，價格一目瞭然。
• 從聊天室： 影像按鈕允許你在將提示接入應用前先對模型進行測試，無需編寫程式碼。

我該如何選擇？

先以工作為起點。目錄按幾個功能線分割，每一條線對應模型記錄中的欄位，你可在扣除信用前先檢查。除非行內說明不同，否則欄位來源於 GET /api/v1/images/models。

Then price. One image at default settings billed between $0.006 and $0.134 across the 20 models in our comparison, a 22x spread, and on OpenAI models the quality setting alone moved the same image from $0.006 to $0.211. Pricing units differ too. Some endpoints bill per image, some per megapixel, and some per token, so a longer prompt costs more on a token-priced model and nothing extra on a per-image one. When the response includes usage, its cost field reports what that call billed, and recording it next to the model slug during test runs is the fastest way to build your own price table. usage is optional in the response schema, so fall back to the activity page for any call that omits it.

Then quality on your own prompts. The benchmarks and the comparison are a shortlist, not a verdict. Run three or four of your production prompts through the two or three finalists in the Chatroom before committing. For editing work specifically, the Nano Banana tutorial shows the reference-image flow end to end.

How do I check what a model supports?

GET /api/v1/images/models is the authoritative source. Each model’s top-level supported_parameters is the union across its providers, so if input_references, n, or a given aspect_ratio is missing there, no provider serves it and the request will fail. If it is present, at least one provider accepts it and routing narrows to those providers when you send it. To see which provider accepts what, follow the model’s endpoints URL (GET /api/v1/images/models/{author}/{slug}/endpoints), which lists each provider’s own supported_parameters. Check it before pinning a provider with provider.only or provider.order.

curl https://openrouter.ai/api/v1/images/models \
  -H "Authorization: Bearer $OPENROUTER_API_KEY"

The parameters you’ll filter on most:

Providers can also take provider-specific options through provider.options, and models with supports_streaming: true can stream partial images over SSE with stream: true. The image generation doc covers the full request schema.

Do I need an image model or a vision model?

Two different jobs run through the same base URL and key, and confusing them produces the most-searched error in this article.

Use generation when the output is a new visual asset. Use understanding when you already have an image and need OCR, alt-text, classification, or a description from it. Some models do both, and those are the ones that can return a picture and a text reply in a single chat turn.

There’s a third option for apps where the conversation itself should decide when an image is needed. The openrouter:image_generation server tool (beta) lets a chat model generate an image mid-conversation without your application code making that call explicitly. Add { "type": "openrouter:image_generation" } to the request’s tools array, and the model determines when to invoke it. It defaults to openai/gpt-5-image. The server-tool doc covers the available parameters.

Is there a free way to generate images?

Not at the moment. The free tier covers models with the :free suffix at 50 requests/day and 20 RPM with no credit card (1,000 requests/day with $10 or more in credits), and no image generation model currently carries that suffix. The free pool changes as models come and go, so it’s worth re-checking /models?output_modalities=image.

Generation therefore draws on your credit balance, but testing costs little. Per-image pricing on low-cost models starts around a cent, and each response’s usage.cost reports what the request cost when the endpoint returns usage. The free models guide covers the free tier’s mechanics for text models.

Do routing and failover work for image calls?

Yes. On /api/v1/images, the provider object accepts order, only, ignore, sort, and allow_fallbacks. An image model served by more than one provider can fail over between them if the first is unavailable or slow.

{
  "model": "google/gemini-2.5-flash-image",
  "prompt": "A minimalist logo for a coffee roaster",
  "provider": {
    "order": ["google-ai-studio", "google-vertex"],
    "allow_fallbacks": true
  }
}

This request prefers one provider and falls back to the next if it fails. You pay the catalog rate with no markup from us, and under Zero Completion Insurance, an image call that fails over and never completes isn’t billed. For how the router picks a provider, see how OpenRouter model routing works.

The same provider object is also the most common reason a request that used to work starts returning “No endpoint found”. The next section covers that.

How do I fix Image API errors?

Log the HTTP status, and log the response body only when the status isn’t 2xx. A successful body carries the image as base64 in data[].b64_json, often megabytes of it, which doesn’t belong in application logs. Every error below names the thing that didn’t match, and the fix follows from the message.

”No endpoints found that support image input”

This is a /chat/completions error, not an Image API error. You sent an image_url content part to a model that doesn’t accept image input. We filter available endpoints by request content, so when the model you named has no endpoint that supports images, the request fails with this 404 instead of silently dropping the image.

Fix it in three steps:

1. Confirm the model supports image input. Its input_modalities must include image. Text-only models never will.
2. Find a vision-capable model. Run GET /api/v1/models?input_modalities=image, or use the input modality filter on the Models page.
3. Update the model string in your request and resend.

Two variants narrow the cause further. “No endpoints found that support base64 image input” means the model takes images but its available endpoints only accept URLs, so host the file and send a URL. “No endpoints found that support image URLs” is the reverse, so fetch the file and send it as a base64 data URL.

Generation models can hit this too. Image generation still works on /chat/completions, and an image-to-image request there fails with this message when the generation model you named doesn’t accept image input. Pick a generation model whose input_modalities include image, or move the request to /api/v1/images and send the reference through input_references.

No model found for "<slug>"

A 404 from /api/v1/images. The slug isn’t in the catalog. Check for a typo, then check whether the model was retired or renamed, which happens often in the image catalog. Copy the slug from GET /api/v1/images/models or from the model’s page in the collection rather than from memory.

Model "<slug>" does not support image output

從 /api/v1/images 收到 400 錯誤。Slug 存在，但它是文本或視覺模型，而非生成模型。google/gemini-2.5-flash 讀取影像，google/gemini-2.5-flash-image 生成影像，且此模式在整個目錄中保持一致。從 GET /api/v1/images/models 選擇一個模型。該列表為帶有 Image API 介面器的影像輸出模型，因此排除了僅透過 /chat/completions 生成的少數影像輸出模型。

No endpoint found for model "<slug>"

從 /api/v1/images 收到 404 錯誤。模型存在且能生成影像，但所有提供此模型的服務商在請求上游之前已被過濾。常見原因，按檢查順序列出：

1. provider.only 或 provider.order 搭配 allow_fallbacks: false 指的是不提供此模型的服務商。移除該列表或將 allow_fallbacks 設為 true。
2. provider.ignore 涵蓋該模型的所有服務商。
3. 您的帳號資料政策 排除了剩餘的端點。Image API 的 provider 物件不接受 data_collection，因此此設定在 隱私設定 中，而非請求中。
4. 該模型目前沒有活躍端點。 模型頁面顯示其服務商及狀態。

逐一移除過濾條件並在每次更改後重新傳送。第一個使呼叫成功的條件即為正確修復的物件。

No provider for <slug> supports the requested parameter(s)

從 /api/v1/images 收到 400 錯誤。您請求了 resolution、aspect_ratio、n、output_format 或其他引數，模型端點皆不接受。訊息列出了無法符合的引數及各服務商拒絕原因。移除該引數、改為支援的值，或選擇包含該 supported_parameters 的模型。

Streaming is not supported with n > 1

從 /api/v1/images 收到 400 錯誤。部分影像串流一次只能處理一張圖。請將 n 設為 1 或移除 stream。

401 與 402

A 401 表示請求未附帶有效金鑰。請確認流程能讀取 OPENROUTER_API_KEY 而不印出其值，且標頭為 Authorization: Bearer <key>。A 402 表示您的餘額等於或低於 Image API 的 $1 事前授權。每一次付費影像請求在執行前都會檢查是否有超過 $1 的餘額，無論影像實際成本為何，實際費用會在之後結算。若帳戶餘額為 $0.50，產生一分的影像時會得到 402，因此請將餘額充值至超過 $1，而非僅為影像大小充值。沒有免費的影像模型，使用適用於 :free 文本模型的金鑰仍需影像生成的積分。

呼叫成功但影像錯誤

• 缺少 data[0].b64_json。先檢查回應主體。確認請求已送至 /api/v1/images，並在請求 n > 1 時以迭代 data 而非硬編碼索引 0。
• 檔案格式不符。從回應中讀取 media_type。部分模型返回 JPEG 或 WebP 位元組，而非 PNG，Recraft 向量模型則返回 image/svg+xml。
• 參考影像被忽略或拒絕。確認 input_references 在模型的 endpoints URL 中的服務商 supported_parameters 內顯示，並且本地檔案以正確字首（如 data:image/jpeg;base64,）作為資料 URL 傳送。
• 費用不符。在執行批次前先檢查端點的定價單位。基於 Token 的模型在更長提示時費用更高，而 quality 設定可在同一模型上將費用提升一個數量級。

一旦請求成功，影像生成教學 會說明如何儲存輸出、加入參考影像，以及讓請求可重複使用。

常見問題

OpenRouter 上可用的影像生成模型有哪些？

目錄包含 Google（Gemini image family）、OpenAI（GPT Image）、Black Forest Labs（FLUX）、xAI（Grok Imagine）、ByteDance（Seedream）、Microsoft（MAI-Image）、Recraft、Krea 與 Sourceful（Riverflow）。請過濾 /models?output_modalities=image 或瀏覽 影像模型集合 以檢視目前的產品與價格。

如何選擇影像生成模型？

先決定任務（文字轉影像、編輯參考影像、向量輸出、可讀文字），再過濾符合 supported_parameters 覆蓋您需求的模型，最後比較每張圖的價格。GET /api/v1/images/models 回傳每個端點的引數支援，usage.cost 在每個回應中報告呼叫的費用。

如何修復「未找到支援影像輸入的端點」？

您將一個 image_url 送給了位於 /chat/completions 的模型，但該模型不接受影像輸入。確認模型的 input_modalities 包含 image，尋找具備視覺功能且帶有 GET /api/v1/models?input_modalities=image 的模型，並在請求中更新模型字串。

為什麼影像 API 會顯示「未找到模型的端點」？

所有提供該模型的供應商在請求向上傳遞前已被過濾。常見原因包括 provider.only 或 provider.order 列表中有 allow_fallbacks: false 指定了不提供該模型的供應商、provider.ignore 列表覆蓋了所有供應商，或資料政策不符合端點要求。逐一移除過濾條件，直到呼叫成功。

在 OpenRouter 上有免費生成影像的方法嗎？

目前沒有。免費層級（每日 50 次請求、20 RPM、無需信用卡）僅涵蓋帶有 :free 字尾的模型，而目前沒有影像生成模型使用該字尾，故生成會使用您的餘額。低成本模型每張圖約 1 美分起。

路由與故障轉移功能適用於影像呼叫嗎？

是的。/api/v1/images 端點接受 provider.order、only、ignore、sort 與 allow_fallbacks，因此排序、成本/延遲排序及跨供應商故障轉移與聊天時相同。