메인 콘텐츠로 건너뛰기

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