生成或編輯圖片（OpenRouter 形狀）

對齊 [OpenRouter Image API](https://openrouter.ai/docs/api/api-reference/images/create-image)。 `model` 必須是 `type: image`、已啟用、且通過組織 ∩ API Key 允許清單的 id（用 `GET /v1/images/models` 查詢）。帶 `input_references` 就是以圖生圖／編輯；同一個端點涵蓋文字生圖與編輯。 **參數處理**（依模型的 `supported_parameters`）： - 明確不支援的要求回 `400`：參考圖或遮罩、超過上限的 `n`、透明背景、enum 以外的值 - `aspect_ratio` 不在清單時自動調到最接近的支援值 - 模型沒有對應旋鈕的參數（`quality`、`seed`、`output_compression`…）直接忽略 - 所有調整與忽略列在回應 header `X-Hakila-Adjusted-Params`（例如 `aspect_ratio=5:3>16:9, seed=ignored`） **計費與限制**： - 全有全無：上游失敗或用戶端中途斷線不扣點；`n > 1` 部分成功時只算成功送達的張數 - 送出前以「每張最高費用 × 張數」預估，超過任何一層預算或儲值餘額回 `402` - API Key 與組織可設每日張數上限（台北時間 00:00 重置），超過回 `429`（`code: image_quota_exceeded`） - 提示詞與參考圖會先經過內容審核，未通過回 `400`（`code: content_policy_violation`）；各供應商的安全設定一律用最嚴格等級，`moderation: low` 會被改回 `auto` - 不支援 `hakila/auto`、Preset 與 Response Cache

POST/v1/images

對齊 OpenRouter Image API。 model 必須是 type: image、已啟用、且通過組織 ∩ API Key 允許清單的 id（用 GET /v1/images/models 查詢）。帶 input_references 就是以圖生圖／編輯；同一個端點涵蓋文字生圖與編輯。

參數處理（依模型的 supported_parameters）：

明確不支援的要求回 400：參考圖或遮罩、超過上限的 n、透明背景、enum 以外的值
aspect_ratio 不在清單時自動調到最接近的支援值
模型沒有對應旋鈕的參數（quality、seed、output_compression…）直接忽略
所有調整與忽略列在回應 header X-Hakila-Adjusted-Params（例如 aspect_ratio=5:3>16:9, seed=ignored）

計費與限制：

全有全無：上游失敗或用戶端中途斷線不扣點；n > 1 部分成功時只算成功送達的張數
送出前以「每張最高費用 × 張數」預估，超過任何一層預算或儲值餘額回 402
API Key 與組織可設每日張數上限（台北時間 00:00 重置），超過回 429（code: image_quota_exceeded）
提示詞與參考圖會先經過內容審核，未通過回 400（code: content_policy_violation）；各供應商的安全設定一律用最嚴格等級，moderation: low 會被改回 auto
不支援 hakila/auto、Preset 與 Response Cache

Authorization

bearerAuth

AuthorizationBearer <token>

在 Authorization 標頭帶入 Workspace API Key： Authorization: Bearer sk-hakila-...

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

/v1/images 用 OpenRouter 欄位；/v1/images/generations、/v1/images/edits 另接受 OpenAI 的 size、images、image。哪些欄位有效依模型的 supported_parameters（GET /v1/images/models）。

model*string

prompt*string

提示詞；長度上限為模型的 context_length（字元）。

n?integer

張數。超過上游單次上限時 Hakila 會平行拆送，部分成功時只回傳並計費成功的張數。

Range1 <= value

Default1

aspect_ratio?string

不在模型清單時自動調到最接近的值；auto 交給模型決定。

resolution?string

解析度等級（例如 512、1K、2K、4K）。必須是模型列出的值，否則回 400。

size?string

OpenAI 欄位。像素尺寸、解析度等級或 auto；非 OpenAI 模型換算成 aspect_ratio + resolution。

quality?string

依模型（例如 low、medium、high）；standard／hd 對應 medium／high；模型沒有品質選項時忽略。

output_format?string

Value in

"png"
"jpeg"
"webp"
"svg"

background?string

transparent 需要模型支援且格式為 png／webp，否則回 400。

Value in

"auto"
"transparent"
"opaque"

output_compression?integer

Range0 <= value <= 100

seed?integer

只有支援 seed 的模型有效，其餘忽略。

input_references?array<>

參考圖（以圖生圖／編輯）。image_url.url 只接受 https 或 data URL，單張 50 MB 以內。

mask?

遮罩（只有支援 mask 的模型能用，且需搭配參考圖）。

response_format?string

url 回傳 1 小時有效的簽名網址（圖片暫存 24 小時後刪除）。

Default"b64_json"

Value in

"b64_json"
"url"

stream?boolean

SSE 串流；等待期間送 keepalive，每張圖完成時送一個 completed 事件。

Defaultfalse

user?string

呼叫端的使用者識別；Hakila 會與組織、人員一起雜湊後才送給上游。

provider?

只採用 options；其中只有模型 allowed_passthrough_parameters 列出的欄位會送上游，其餘忽略。

[key: string]?any

Response Body

`application/json`

curl -X POST "https://example.com/v1/images" \  -H "Content-Type: application/json" \  -d '{    "model": "google/gemini-3.1-flash-image",    "prompt": "一隻戴著圓框眼鏡的柴犬在圖書館看書，水彩風格",    "aspect_ratio": "16:9",    "resolution": "2K"  }'

{  "created": 1791273600,  "data": [    {      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",      "media_type": "image/png"    }  ],  "usage": {    "prompt_tokens": 18,    "completion_tokens": 1290,    "total_tokens": 1308,    "cost": 0.0774,    "cost_points": 0.25542  }}

生成或編輯圖片（OpenRouter 形狀）

Authorization

Request Body

Response Body

200application/json

400application/json

401application/json

402application/json

429application/json

502application/json

503application/json

504application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`