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. Patrones de integración principales
1.1 Autenticación y enrutamiento unificados
// 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';
}
}
# Core logic: Replace API Key, Base URL, add APP-Code
credentials = {
"api_key": "your-aihubmix-api-key", # Replace with aihubmix API Key
"base_url": "https://aihubmix.com", # Replace with aihubmix gateway
"extra_headers": {
"APP-Code": "App Code" # App Code can be obtained from https://aihubmix.com/appstore
}
}
# Model routing rules
def route_model(model_name: str):
if model_name.startswith("claude"):
# Claude models: Use Anthropic SDK
return "anthropic"
elif model_name.startswith("gemini") and not model_name.endswith(("-nothink", "-search")):
# Gemini models: Use Google SDK, endpoint https://aihubmix.com/gemini
return "gemini"
else:
# Other models: Use OpenAI compatible interface
return "openai"
1.2 Puntos de manejo especiales
- Corrección de tools vacíos: Cuando
tools=[] y existe tool_choice, elimina automáticamente tool_choice
- Extensiones de archivo: Establece automáticamente las extensiones de archivo correctas según
mediaType
- Control de caché: Admite etiquetas
<cache> para el control de caché
2. Implementación de integración unificada
2.1 Wrapper del cliente principal
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);
class AihubmixModelClient:
def __init__(self, api_key: str):
self.api_key = api_key
self.base_url = "https://aihubmix.com"
self.headers = {
"Authorization": f"Bearer {api_key}",
"APP-Code": "App Code can be obtained from https://aihubmix.com/appstore"
}
def chat_completion(self, model: str, messages: list, **kwargs):
"""Unified chat completion interface"""
if model.startswith("claude"):
return self._claude_completion(model, messages, **kwargs)
elif model.startswith("gemini"):
return self._gemini_completion(model, messages, **kwargs)
else:
return self._openai_completion(model, messages, **kwargs)
def _claude_completion(self, model: str, messages: list, **kwargs):
import anthropic
client = anthropic.Anthropic(
api_key=self.api_key,
base_url=self.base_url,
extra_headers={"APP-Code": "App Code can be obtained from https://aihubmix.com/appstore"}
)
return client.messages.create(model=model, messages=messages, **kwargs)
def _gemini_completion(self, model: str, messages: list, **kwargs):
import google.generativeai as genai
genai.configure(
api_key=self.api_key,
client_options={"api_endpoint": f"{self.base_url}/gemini/v1beta"}
)
genai._client._http_client._session.headers.update({"APP-Code": "App Code can be obtained from https://aihubmix.com/appstore"})
model_instance = genai.GenerativeModel(model)
return model_instance.generate_content(messages)
def _openai_completion(self, model: str, messages: list, **kwargs):
import openai
client = openai.OpenAI(
api_key=self.api_key,
base_url=f"{self.base_url}/v1",
extra_headers={"APP-Code": "App Code can be obtained from https://aihubmix.com/appstore"}
)
return client.chat.completions.create(model=model, messages=messages, **kwargs)
# Usage example
client = AihubmixModelClient("your-aihubmix-api-key")
await client.chat_completion("gpt-4o-mini", messages)
await client.chat_completion("claude-3-5-sonnet-20241022", messages)
await client.chat_completion("gemini-2.5-flash", messages)
2.2 Funciones auxiliares y manejo especial
// 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 };
}
# Empty tools fix
def fix_tool_choice(request_body: dict) -> dict:
if request_body.get("tools") == [] and "tool_choice" in request_body:
del request_body["tool_choice"]
return request_body
# File extension mapping
def set_file_extension(media_type: str) -> str:
mime_to_ext = {
'audio/mpeg': 'mp3', 'audio/wav': 'wav', 'audio/flac': 'flac'
}
return mime_to_ext.get(media_type, 'bin')
# Cache control
def process_cache_tags(content: str):
if "<cache>" in content:
return {
"content": content.replace("<cache>", ""),
"cache_control": {"type": "ephemeral"}
}
return {"content": content}
3. Despliegue y configuración
3.1 Variables de entorno
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'
};
import os
config = {
"api_key": os.getenv("AIHUBMIX_API_KEY", ""),
"base_url": os.getenv("AIHUBMIX_BASE_URL", "https://aihubmix.com"),
"app_code": os.getenv("AIHUBMIX_APP_CODE", "App Code can be obtained from https://aihubmix.com/appstore")
}
3.2 Manejo de errores
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);
}
}
class AihubmixError(Exception):
def __init__(self, message: str, code: str = None, status: int = None):
super().__init__(message)
self.code = code
self.status = status
def handle_aihubmix_errors(e: Exception) -> AihubmixError:
message = str(e).lower()
if "rate limit" in message:
return AihubmixError("Rate limit exceeded", "RATE_LIMIT", 429)
elif "unauthorized" in message:
return AihubmixError("Authentication failed", "AUTH_ERROR", 401)
else:
return AihubmixError(f"Request failed: {e}")
4. Implementaciones de referencia y lista de comprobación
4.1 Referencia del cliente cherry-studio (TypeScript)
Los siguientes puntos clave del AihubmixAPIClient.ts de cherry-studio pueden servir como patrón para que aplicaciones de terceros (frontend/escritorio) integren aihubmix con TypeScript:
- Adición unificada de código de descuento: Combina
extra_headers a nivel de Provider y establece APP-Code (el proyecto utiliza MLTG2087)
- Enrutamiento multicliente:
claude* → Usa el cliente de Anthropic
gemini*/imagen* que no terminan con -nothink/-search y no contienen embedding → Usa el cliente de Gemini (apiHost: https://aihubmix.com/gemini)
- Serie OpenAI (excluyendo
gpt-oss) → Usa el cliente compatible con OpenAI
- Otros → Recae en el cliente OpenAI predeterminado
- Obtención de la BaseURL: Se exporta desde el cliente específico al que se ha enrutado actualmente, manteniendo las diferencias de endpoint entre proveedores
4.2 Referencia de dify-plugin-aihubmix (Python)
Los siguientes puntos clave de la implementación de dify-plugin-aihubmix pueden servir como patrón para que herramientas de terceros en Python integren aihubmix:
- Adición unificada de código de descuento: Combina
extra_headers a nivel de Provider y establece APP-Code (el proyecto utiliza Dify2025)
- Enrutamiento multicliente:
claude* → Usa el cliente de Anthropic
gemini*/imagen* que no terminan con -nothink/-search y no contienen embedding → Usa el cliente de Gemini (apiHost: https://aihubmix.com/gemini)
- Serie OpenAI (excluyendo
gpt-oss) → Usa el cliente compatible con OpenAI
- Otros → Recae en el cliente OpenAI predeterminado
- Obtención de la BaseURL: Se exporta desde el cliente específico al que se ha enrutado actualmente, manteniendo las diferencias de endpoint entre proveedores
4.3 Lista de comprobación de alineación
- La entrada del Provider unifica la combinación de
extra_headers e inyecta APP-Code
- El cliente de Gemini usa
https://aihubmix.com/gemini como apiHost
- Las reglas de enrutamiento son consistentes para
claude*, gemini*/imagen*, serie OpenAI (excluyendo gpt-oss)
- Fallback predeterminado al cliente OpenAI, manteniendo el comportamiento de la interfaz compatible con OpenAI
getBaseURL() siempre se exporta desde el cliente actualmente enrutado, evitando valores codificados
5. Lista de comprobación para la migración
- Sustituye la clave API por la de aihubmix
- Sustituye la Base URL por
https://aihubmix.com
- Añade la cabecera
APP-Code para el descuento
- Implementa la lógica de enrutamiento del modelo (claude/gemini/openai)
- Gestiona la corrección de
tool_choice cuando los tools están vacíos
- Configura el manejo del tipo MIME para las subidas de archivos
- Prueba diversas llamadas a modelos
Última actualización: 2026-06-01