1. 核心整合模式
1.1 統一驗證與路由
- TypeScript
- Python
1.2 特殊處理要點
- 空 Tools 修正:當
tools=[]且tool_choice存在時,自動移除tool_choice - 檔案副檔名:依據
mediaType自動設定正確的檔案副檔名 - 快取控制:支援透過
<cache>標籤進行快取控制
2. 統一整合實作
2.1 核心 Client 封裝
- TypeScript
- Python
2.2 特殊處理與工具函式
- TypeScript
- Python
3. 部署與設定
3.1 環境變數
- TypeScript
- Python
3.2 錯誤處理
- TypeScript
- Python
4. 參考實作與對齊檢查清單
4.1 cherry-studio Client 參考(TypeScript)
下列來自cherry-studio 的 AihubmixAPIClient.ts 的關鍵要點,可作為第三方前端/桌面應用程式在 TypeScript 端整合 aihubmix 的落地模式:
- 統一加入折扣碼:在 Provider 層合併
extra_headers並設定APP-Code(專案中使用MLTG2087) - 多 client 路由:
claude*→ 使用 Anthropic client- 未以
-nothink/-search結尾且不包含embedding的gemini*/imagen*→ 使用 Gemini client(apiHost: https://aihubmix.com/gemini) - OpenAI 系列(不包含
gpt-oss)→ 使用 OpenAI 相容 response client - 其他 → 預設使用 OpenAI client
- BaseURL 取得:從目前路由所對應的具體 client 匯出,維持各供應商的端點差異
4.2 dify-plugin-aihubmix 參考(Python)
下列來自dify-plugin-aihubmix 實作的關鍵要點,可作為第三方 Python 工具整合 aihubmix 的落地模式:
- 統一加入折扣碼:在 Provider 層合併
extra_headers並設定APP-Code(專案中使用Dify2025) - 多 client 路由:
claude*→ 使用 Anthropic client- 未以
-nothink/-search結尾且不包含embedding的gemini*/imagen*→ 使用 Gemini client(apiHost: https://aihubmix.com/gemini) - OpenAI 系列(不包含
gpt-oss)→ 使用 OpenAI 相容 response client - 其他 → 預設使用 OpenAI client
- BaseURL 取得:從目前路由所對應的具體 client 匯出,維持各供應商的端點差異
4.3 對齊檢查清單
- Provider 入口統一合併
extra_headers並注入APP-Code - Gemini client 使用
https://aihubmix.com/gemini作為apiHost - 路由規則與
claude*、gemini*/imagen*、OpenAI 系列(不包含gpt-oss)一致 - 預設使用 OpenAI client,維持 OpenAI 相容介面行為
getBaseURL()一律從目前路由的 client 匯出,避免硬編碼
5. 遷移檢查清單
- 將 API Key 替換為 aihubmix API Key
- 將 Base URL 替換為
https://aihubmix.com - 加入
APP-Code標頭以享有折扣 - 實作模型路由邏輯(claude/gemini/openai)
- 處理 tools 為空時的
tool_choice修正 - 設定檔案上傳的 MIME 類型處理
- 測試各種模型呼叫
最後更新:2026-06-01