RikkaHub 중계 API 연동 튜토리얼: 안드로이드 AI 채팅 클라이언트 설정

发布时间2026年9月16日 04:44
语言ko

RikkaHub(안드로이드 오픈 소스 AI 채팅 클라이언트) 연동 튜토리얼: sk- 키 생성, 모델 그룹별 Provider 유형 선택 및 Base URL 설정을 통해 간편하게 Gemini / Claude / GPT 모델을 호출해 보세요.

1. RikkaHub이란 무엇인가

RikkaHub는 오픈 소스 안드로이드 AI 채팅 클라이언트로, Anthropic(Claude), OpenAI(GPT), Google(Gemini) 등 다양한 모델 채널을 지원합니다. Provider(공급자)를 중계 게이트웨이로 설정하고 sk- 키를 입력하면 플랫폼 크레딧을 사용하여 각 모델 시리즈를 토큰 단위로 과금하여 호출할 수 있습니다.

2. 준비 작업

지능형 API 제어판에 로그인하여 'API 키'에서 sk-xxxxxx 키를 생성합니다(한 번만 표시되므로 반드시 저장해 두세요).
사용할 모델 슬러그(예: gemini-3.7-flash, claude-sonnet-5, gpt-5.5)를 확인합니다. 제어판의 '토큰' 페이지 우측 상단의 '모델 ID'에서 확인할 수 있습니다.
게이트웨이 주소를 확인합니다: https://www.relay-api.com

3. RikkaHub 설정 방법

RikkaHub 실행 → '설정' → '공급자(Provider)' → 우측 상단의 '+'를 눌러 추가하고, 사용할 모델에 맞는 Provider 유형을 선택하세요:

① Gemini 호출 (Google 유형, 권장)

Provider 유형 : Google / Gemini
Base URL      : https://www.relay-api.com/v1beta
API Key       : sk-본인의 키
모델 ID        : gemini-3.7-flash

Base URL에는 반드시 /v1beta가 포함되어야 합니다. RikkaHub는 Base URL 뒤에 자동으로 /models/{모델}:generateContent를 붙입니다. /v1beta를 누락하면 요청이 /models/...로 전달되어 404(페이지를 찾을 수 없음) 오류가 발생합니다.

② Claude 호출 (Anthropic 유형)

Provider 유형 : Anthropic / Claude
Base URL      : https://www.relay-api.com
API Key       : sk-본인의 키
모델 ID        : claude-sonnet-5

Anthropic 유형의 Base URL에는 /v1을 추가하지 마세요. 클라이언트가 자체적으로 /v1/messages를 추가하므로 중복될 경우 /v1/v1/messages가 되어 오류가 발생합니다.

③ GPT 호출 (OpenAI 호환 유형)

Provider 유형 : OpenAI 호환 / OpenAI Compatible
Base URL      : https://www.relay-api.com/v1
API Key       : sk-본인의 키
모델 ID        : gpt-5.5

4. 인터페이스 주소 대조표

모델 그룹	Provider 유형	Base URL	프로토콜
Gemini	Google / Gemini	`https://www.relay-api.com/v1beta`	Google generateContent
Claude	Anthropic	`https://www.relay-api.com`	Anthropic Messages
GPT	OpenAI 호환	`https://www.relay-api.com/v1`	OpenAI Chat Completions

5. 중요: 모델은 그룹별로 분리되어 있으며, 교차 호출 불가

본 사이트의 세 가지 프로토콜은 각각 독립된 네이티브 입구이며, 모델은 그룹별로 분리됩니다:

Gemini 그룹 모델(gemini-3.7-flash 등)은 반드시 Google / Gemini 유형 + /v1beta를 사용해야 합니다.
Gemini 모델명을 Anthropic 유형에 입력하면 400 미사용 또는 존재하지 않는 Claude 모델: gemini-xxx 오류가 반환됩니다.
Gemini 모델명을 OpenAI 유형에 입력하면 400 미사용 또는 존재하지 않는 OpenAI 모델: gemini-xxx 오류가 반환됩니다.

따라서 '모델 ID'와 'Provider 유형'이 일치해야 합니다: 사용하려는 모델 그룹에 해당하는 Provider 유형을 선택하세요.

6. 자주 묻는 질문(FAQ) 및 문제 해결

현상	원인 및 조치
`404` 오류 발생(웹페이지/HTML)	Base URL에 버전 접미사 누락(예: Gemini에서 `/v1beta` 누락). 요청 경로가 잘못되었습니다. `/v1beta` 또는 `/v1`을 추가하세요.
경로에 `/v1beta/v1beta/` 또는 `/v1/v1/` 포함됨	Base URL에 버전 번호 중복 기재. Base URL에는 한 번만 기재해야 합니다.
`400 미사용 또는 존재하지 않는 Claude/OpenAI 모델: gemini-xxx`	모델 그룹과 Provider 유형 불일치. Gemini 모델을 Claude/OpenAI 유형에 입력한 경우입니다. Google / Gemini 유형으로 변경하세요.
`401 / 403`	키 무효, 비활성화, 잔액 부족 또는 해당 토큰이 경로/모델에 접근 권한이 없음. 키와 계정 잔액을 확인하세요.
`400 Request contains an invalid argument`	상위 서버에서 특정 매개변수(예: 추론 레벨 대소문자, 도구 호출 tools 등) 검증 시 발생하는 오류. 일시적인 현상이므로 재시도하세요.
모델 목록 가져오기 실패	일부 클라이언트가 중계 서버의 모델 목록 응답을 엄격하게 처리함. '모델 ID 직접 입력' 기능을 사용하세요.

7. 보안 권장 사항

API 키를 공개 저장소에 올리거나 스크린샷으로 공유하지 마세요. 환경 변수나 로컬 보안 저장소를 사용하는 것이 좋습니다.
기기나 도구별로 별도의 키를 생성하여 사용량을 파악하고, 필요 시 즉시 비활성화할 수 있도록 관리하세요.