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

Documentation Index

Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt

Use this file to discover all available pages before exploring further.

1. コア統合パターン

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

// Core logic: Replace API Key, Base URL, add APP-Code
const config = {
  apiKey: 'your-aihubmix-api-key',  // Replace with aihubmix API Key
  baseURL: 'https://aihubmix.com',   // Replace with aihubmix gateway
  headers: {
    'APP-Code': 'App Code'  // App Code can be obtained from https://aihubmix.com/appstore
  }
};

// Model routing rules
function routeModel(modelName: string) {
  if (modelName.startsWith('claude')) {
    // Claude models: Use Anthropic SDK
    return 'anthropic';
  } else if (modelName.startsWith('gemini') && !modelName.endsWith('-nothink') && !modelName.endsWith('-search')) {
    // Gemini models: Use Google SDK, endpoint https://aihubmix.com/gemini
    return 'gemini';
  } else {
    // Other models: Use OpenAI compatible interface
    return 'openai';
  }
}

1.2 特殊処理ポイント

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

2. 統一統合の実装

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

class AihubmixModelClient {
  private config: {
    apiKey: string;
    baseURL: string;
    appCode: string;
  };

  constructor(apiKey: string) {
    this.config = {
      apiKey,
      baseURL: 'https://aihubmix.com',
      appCode: 'App Code can be obtained from https://aihubmix.com/appstore'
    };
  }

  async chatCompletion(model: string, messages: any[], options: any = {}) {
    // Automatically route to corresponding SDK based on model name
    if (model.startsWith('claude')) {
      return this.claudeCompletion(model, messages, options);
    } else if (model.startsWith('gemini')) {
      return this.geminiCompletion(model, messages, options);
    } else {
      return this.openaiCompletion(model, messages, options);
    }
  }

  private async claudeCompletion(model: string, messages: any[], options: any) {
    const { Anthropic } = await import('@anthropic-ai/sdk');
    const client = new Anthropic({
      apiKey: this.config.apiKey,
      baseURL: this.config.baseURL,
      defaultHeaders: { 'APP-Code': this.config.appCode }
    });
    return client.messages.create({ model, messages, ...options });
  }

  private async geminiCompletion(model: string, messages: any[], options: any) {
    const { GoogleGenerativeAI } = await import('@google/generative-ai');
    const genAI = new GoogleGenerativeAI(this.config.apiKey, {
      baseURL: `${this.config.baseURL}/gemini/v1beta`,
      defaultHeaders: { 'APP-Code': this.config.appCode }
    });
    const genModel = genAI.getGenerativeModel({ model });
    return genModel.generateContent(messages);
  }

  private async openaiCompletion(model: string, messages: any[], options: any) {
    const OpenAI = await import('openai');
    const client = new OpenAI.default({
      apiKey: this.config.apiKey,
      baseURL: `${this.config.baseURL}/v1`,
      defaultHeaders: { 'APP-Code': this.config.appCode }
    });
    return client.chat.completions.create({ model, messages, ...options });
  }
}

// Usage example
const client = new AihubmixModelClient('your-aihubmix-api-key');
await client.chatCompletion('gpt-4o-mini', messages);
await client.chatCompletion('claude-3-5-sonnet-20241022', messages);
await client.chatCompletion('gemini-2.5-flash', messages);

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

// Empty tools fix
function fixToolChoice(requestBody: any): any {
  if (requestBody.tools?.length === 0 && requestBody.tool_choice) {
    delete requestBody.tool_choice;
  }
  return requestBody;
}

// File extension mapping
function setFileExtension(mediaType: string): string {
  const mimeToExt: Record<string, string> = {
    'audio/mpeg': 'mp3', 'audio/wav': 'wav', 'audio/flac': 'flac'
  };
  return mimeToExt[mediaType] || 'bin';
}

// Cache control
function processCacheTags(content: string): { content: string; cacheControl?: any } {
  if (content.includes('<cache>')) {
    return { content: content.replace('<cache>', ''), cacheControl: { type: 'ephemeral' } };
  }
  return { content };
}

3. デプロイと設定

3.1 環境変数

const config = {
  apiKey: process.env.AIHUBMIX_API_KEY || '',
  baseURL: process.env.AIHUBMIX_BASE_URL || 'https://aihubmix.com',
  appCode: process.env.AIHUBMIX_APP_CODE || 'App Code can be obtained from https://aihubmix.com/appstore'
};

3.2 エラーハンドリング

class AihubmixError extends Error {
  constructor(message: string, public code?: string, public status?: number) {
    super(message);
    this.name = 'AihubmixError';
  }
}

function handleAihubmixErrors(error: any): AihubmixError {
  const message = error.message || 'Unknown error';
  if (message.toLowerCase().includes('rate limit')) {
    return new AihubmixError('Rate limit exceeded', 'RATE_LIMIT', 429);
  } else if (message.toLowerCase().includes('unauthorized')) {
    return new AihubmixError('Authentication failed', 'AUTH_ERROR', 401);
  } else {
    return new AihubmixError(message, error.code, error.status);
  }
}

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