1. Core Integration Patterns
1.1 Unified Authentication and Routing
1.2 Special Handling Points
- Empty Tools Fix: When
tools=[]
andtool_choice
exists, automatically removetool_choice
- File Extensions: Automatically set correct file extensions based on
mediaType
- Cache Control: Support
<cache>
tags for cache control
2. Unified Integration Implementation
2.1 Core Client Wrapper
2.2 Special Handling and Utility Functions
3. Deployment and Configuration
3.1 Environment Variables
3.2 Error Handling
4. Reference Implementations and Alignment Checklist
4.1 cherry-studio Client Reference (TypeScript)
The following key points fromcherry-studio
’s AihubmixAPIClient.ts
can serve as a landing pattern for third-party frontend/desktop applications integrating with aihubmix on the TypeScript side:
- Unified Discount Code Addition: Merge
extra_headers
at Provider level and setAPP-Code
(usingMLTG2087
in the project) - Multi-client Routing:
claude*
→ Use Anthropic clientgemini*
/imagen*
that don’t end with-nothink
/-search
and don’t containembedding
→ Use Gemini client (apiHost: https://aihubmix.com/gemini
)- OpenAI series (excluding
gpt-oss
) → Use OpenAI compatible response client - Others → Fallback to default OpenAI client
- BaseURL Retrieval: Export from current routed specific client, maintaining endpoint differences for each provider
4.2 dify-plugin-aihubmix Reference (Python)
The following key points fromdify-plugin-aihubmix
implementation can serve as a landing pattern for third-party Python tools integrating with aihubmix:
- Unified Discount Code Addition: Merge
extra_headers
at Provider level and setAPP-Code
(usingDify2025
in the project) - Multi-client Routing:
claude*
→ Use Anthropic clientgemini*
/imagen*
that don’t end with-nothink
/-search
and don’t containembedding
→ Use Gemini client (apiHost: https://aihubmix.com/gemini
)- OpenAI series (excluding
gpt-oss
) → Use OpenAI compatible response client - Others → Fallback to default OpenAI client
- BaseURL Retrieval: Export from current routed specific client, maintaining endpoint differences for each provider
4.3 Alignment Checklist
- Provider entry unifies merging of
extra_headers
and injectsAPP-Code
- Gemini client uses
https://aihubmix.com/gemini
asapiHost
- Routing rules consistent with
claude*
,gemini*/imagen*
, OpenAI series (excludinggpt-oss
) - Default fallback to OpenAI client, maintaining OpenAI compatible interface behavior
getBaseURL()
always exports from current routed client, avoiding hardcoding
5. Migration Checklist
- Replace API Key with aihubmix API Key
- Replace Base URL with
https://aihubmix.com
- Add
APP-Code
header for discount - Implement model routing logic (claude/gemini/openai)
- Handle
tool_choice
fix when tools are empty - Configure MIME type handling for file uploads
- Test various model calls