1. コア統合パターン
1.1 統一認証とルーティング
- TypeScript
- Python
1.2 特殊処理ポイント
- 空の Tools の修正:
tools=[]でかつtool_choiceが存在する場合、tool_choiceを自動的に削除します。 - ファイル拡張子:
mediaTypeに基づいて正しいファイル拡張子を自動設定します。 - キャッシュ制御:キャッシュ制御のために
<cache>タグをサポートします。
2. 統一統合の実装
2.1 コアクライアントラッパー
- TypeScript
- Python
2.2 特殊処理とユーティリティ関数
- TypeScript
- Python
3. デプロイと設定
3.1 環境変数
- TypeScript
- Python
3.2 エラーハンドリング
- TypeScript
- Python
4. 参照実装とアライメントチェックリスト
4.1 cherry-studio クライアントリファレンス(TypeScript)
cherry-studio の AihubmixAPIClient.ts から得られる以下のキーポイントは、TypeScript 側で aihubmix と統合するサードパーティのフロントエンド / デスクトップアプリケーションのランディングパターンとして参考になります:
- 統一されたディスカウントコード追加:Provider レベルで
extra_headersをマージし、APP-Codeを設定(プロジェクトではMLTG2087を使用) - マルチクライアントルーティング:
claude*→ Anthropic クライアントを使用-nothink/-searchで終わらず、embeddingを含まないgemini*/imagen*→ Gemini クライアントを使用(apiHost: https://aihubmix.com/gemini)- OpenAI シリーズ(
gpt-ossを除く) → OpenAI 互換 response クライアントを使用 - その他 → デフォルトの OpenAI クライアントにフォールバック
- BaseURL の取得:現在ルーティングされている特定のクライアントからエクスポートし、各プロバイダーのエンドポイントの違いを維持
4.2 dify-plugin-aihubmix リファレンス(Python)
dify-plugin-aihubmix 実装の以下のキーポイントは、Python サードパーティツールが aihubmix と統合する際のランディングパターンとして参考になります:
- 統一されたディスカウントコード追加:Provider レベルで
extra_headersをマージし、APP-Codeを設定(プロジェクトではDify2025を使用) - マルチクライアントルーティング:
claude*→ Anthropic クライアントを使用-nothink/-searchで終わらず、embeddingを含まないgemini*/imagen*→ Gemini クライアントを使用(apiHost: https://aihubmix.com/gemini)- OpenAI シリーズ(
gpt-ossを除く) → OpenAI 互換 response クライアントを使用 - その他 → デフォルトの OpenAI クライアントにフォールバック
- BaseURL の取得:現在ルーティングされている特定のクライアントからエクスポートし、各プロバイダーのエンドポイントの違いを維持
4.3 アライメントチェックリスト
- Provider エントリで
extra_headersのマージを統一し、APP-Codeを注入する - Gemini クライアントは
https://aihubmix.com/geminiをapiHostとして使用する - ルーティングルールは
claude*、gemini*/imagen*、OpenAI シリーズ(gpt-ossを除く)と一貫させる - デフォルトで OpenAI クライアントにフォールバックし、OpenAI 互換インターフェースの挙動を維持する
getBaseURL()は常に現在ルーティングされているクライアントからエクスポートし、ハードコードを避ける
5. 移行チェックリスト
- API Key を aihubmix の API Key に置き換える
- Base URL を
https://aihubmix.comに置き換える - ディスカウントのために
APP-Codeヘッダーを追加する - モデルルーティングロジック(claude/gemini/openai)を実装する
- tools が空の場合の
tool_choice修正を処理する - ファイルアップロードのための MIME タイプ処理を設定する
- 各種モデル呼び出しをテストする
最終更新日:2026-06-01