メインコンテンツへスキップ

1. コア統合パターン

1.1 統一認証とルーティング

1.2 特殊処理ポイント

  • 空の Tools の修正tools=[] でかつ tool_choice が存在する場合、tool_choice を自動的に削除します。
  • ファイル拡張子mediaType に基づいて正しいファイル拡張子を自動設定します。
  • キャッシュ制御:キャッシュ制御のために <cache> タグをサポートします。

2. 統一統合の実装

2.1 コアクライアントラッパー

2.2 特殊処理とユーティリティ関数

3. デプロイと設定

3.1 環境変数

3.2 エラーハンドリング

4. 参照実装とアライメントチェックリスト

4.1 cherry-studio クライアントリファレンス(TypeScript)

cherry-studioAihubmixAPIClient.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/geminiapiHost として使用する
  • ルーティングルールは 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