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