圖片生成

Hakila 提供生圖 API，一把 API Key 就能呼叫 OpenAI、Google、xAI，以及經 OpenRouter 轉接的 FLUX、Seedream、Recraft。 有兩種請求格式，共用同一條管線：

兩種格式都能用任何生圖模型，不限 OpenAI；Hakila 會把參數換算成各供應商的原生 API。

支援的模型

種子目錄目前包含（單價以 GET /v1/images/models/{id}/endpoints 為準）：

指定 openai/gpt-image-2 時，Hakila 會改用同價位的 openai/gpt-image-2.5-flare（回應標頭 X-Hakila-Adjusted-Params）； Flare 不在 API Key 的允許清單內時才用 openai/gpt-image-2。

xAI 的 x-ai/grok-imagine-image-2.0、x-ai/grok-imagine-image-quality 也在目錄中，但預設停用： xAI 的內容審核較寬鬆，被擋下的生成仍會收費，平台管理者確認後才會開放。

「每張最高」是依張數或 tokens 計價的上限，用於送出前的預算檢查；實際費用依解析度、品質與 tokens 計算， 回應的 usage.cost（USD）與 usage.cost_points（點數）是這次實際扣的金額。

快速開始

curl https://api.hakila.ai/v1/images \
  -H "Authorization: Bearer $HAKILA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-3.1-flash-image",
    "prompt": "一隻戴著圓框眼鏡的柴犬在圖書館看書，水彩風格",
    "aspect_ratio": "16:9",
    "resolution": "2K"
  }' | jq -r '.data[0].b64_json' | base64 --decode > shiba.png

以圖生圖與編輯

在 /v1/images 帶 input_references 就是以參考圖生成或編輯；網址只接受 https:// 或 data: URL，單張 50 MB 以內。

{
  "model": "openai/gpt-image-2.5-sunburst",
  "prompt": "把背景換成夜晚的台北街景，保留人物不變",
  "input_references": [
    { "type": "image_url", "image_url": { "url": "data:image/png;base64,iVBORw0KGgo..." } }
  ],
  "mask": { "image_url": { "url": "data:image/png;base64,..." } }
}

用 OpenAI SDK 時改呼叫 client.images.edit(image=[open("a.png", "rb")], mask=open("mask.png", "rb"), ...)， Hakila 接受 multipart 的 image、image[] 與 mask 欄位。遮罩只有支援 mask 的模型能用（目前是 OpenAI 系列）， 透明處是要重畫的區域。

參數怎麼處理

每個模型能用的參數列在 GET /v1/images/models 的 supported_parameters（格式同 OpenRouter）： enum 給允許值、range 給上下限、boolean 表示支援；沒列出的就是不支援。Hakila 依下列規則處理：

所有調整與忽略都列在回應 header X-Hakila-Adjusted-Params，例如 aspect_ratio=5:3>16:9, seed=ignored。

provider.options 可以帶供應商專屬參數，但只有模型 allowed_passthrough_parameters 列出的欄位會送上游 （例如 Recraft 的 style），其餘忽略。

串流與交付方式

• stream: true：回 text/event-stream。生圖通常要 10～60 秒，等待期間每 10 秒送一行 : keepalive 避免連線被代理切斷； 每張圖完成時送一個 image_generation.completed 事件（OpenAI edits 為 image_edit.completed），usage 只在最後一個事件，最後是 data: [DONE]。 目前沒有局部預覽圖（partial image）。
• response_format: "url"：回傳 1 小時有效的簽名網址，不必在 JSON 裡傳 base64。圖片暫存 24 小時後刪除。
• 預設為 b64_json。

計費、預算與張數上限

• 全有全無：上游失敗、逾時（預設 300 秒）或用戶端中途斷線都不扣點。n > 1 時 Hakila 可能拆成多個上游請求， 部分成功時只回傳並計費成功的張數。
• 送出前預算檢查：以「每張最高 × 張數（＋參考圖單價）」預估，超過 API Key、人員、單位、組織任一層預算或儲值餘額時回 402，不會先產圖再超支。
• 每日張數上限：Console 可分別替 API Key 與組織設定每天最多幾張（台北時間 00:00 重置），超過回 429、code: image_quota_exceeded。 適合學校或團隊控管用量。
• 直連 OpenAI、Google 的價格由平台維護；OpenRouter 模型每天同步價格，並以 OpenRouter 回報的實際費用扣點。
• 不支援 hakila/auto、Preset 與 Response Cache。

內容安全

• 提示詞與參考圖送出前會先經過內容審核，未通過回 400、code: content_policy_violation，不扣點。
• 各供應商的安全設定一律用最嚴格等級；moderation: low 會被改回 auto（記在 X-Hakila-Adjusted-Params）。
• Hakila 會把組織、人員與你帶的 user 一起雜湊成匿名識別碼送給上游，供應商可據此追蹤濫用，又不會拿到真實身分。
• 少數供應商（xAI）在生成後才擋下的圖片仍會收費，這種情況會照上游實際收費扣點，並在 Logs 標示「內容違規」。

紀錄與原圖保留

Logs 只記錄摘要（提示詞、參數、張數、格式、大小、費用），不存圖片本身。 工作區管理員可在 Console 的工作區設定開啟「生成圖片原圖保留天數」（1～90 天），之後的請求會保存原圖， 在 Log 明細中查看縮圖，到期自動刪除。預設不保留。

錯誤

錯誤形狀與 OpenAI 相容：{"error": {"message", "type", "code"}}。

完整欄位見 API 參考。