Hakila Docs
Images

生成圖片（OpenAI 形狀）

對齊 [OpenAI Images generations](https://platform.openai.com/docs/api-reference/images/create)， 給寫死 OpenAI SDK 的工具使用。與 `/v1/images` 共用同一條管線，任何生圖模型都能用（不限 OpenAI）。 - `size` 接受像素尺寸（`1536x1024`）、解析度等級（`2K`）或 `auto`；非 OpenAI 模型會換算成 `aspect_ratio` + `resolution` - `quality: standard／hd` 會對應成 `medium／high` - 回應形狀同 OpenAI（`data[].b64_json`、`output_format`、`size`、`usage.input_tokens`…），另附 `usage.cost` 與 `cost_points` - 串流事件為 `image_generation.completed`

POST/v1/images/generations

對齊 OpenAI Images generations， 給寫死 OpenAI SDK 的工具使用。與 /v1/images 共用同一條管線，任何生圖模型都能用（不限 OpenAI）。

  • size 接受像素尺寸（1536x1024）、解析度等級（2K）或 auto；非 OpenAI 模型會換算成 aspect_ratio + resolution
  • quality: standard／hd 會對應成 medium／high
  • 回應形狀同 OpenAI（data[].b64_json、output_format、size、usage.input_tokens…），另附 usage.cost 與 cost_points
  • 串流事件為 image_generation.completed

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）。

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/images/generations" \  -H "Content-Type: application/json" \  -d '{    "model": "openai/gpt-image-2.5-flare",    "prompt": "夕陽下的淡水河，電影感",    "size": "1536x1024",    "quality": "high"  }'
{  "created": 0,  "data": [    {      "b64_json": "string",      "url": "string",      "media_type": "string",      "revised_prompt": "string"    }  ],  "usage": {    "prompt_tokens": 0,    "completion_tokens": 0,    "input_tokens": 0,    "output_tokens": 0,    "total_tokens": 0,    "cost": 0,    "cost_points": 0  }}

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

對齊 [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

編輯圖片（OpenAI 形狀） POST

對齊 [OpenAI Images edits](https://platform.openai.com/docs/api-reference/images/createEdit)。 接受 `multipart/form-data`（`image`／`image[]` 檔案、選填 `mask`）或 JSON（`images: [{image_url}]`、`mask: {image_url}`）。 單張圖片上限 50 MB、整個請求上限 64 MB；網址只接受 https 或 data URL。 串流事件為 `image_edit.completed`。