RikkaHub API 중계 서비스 연동 튜토리얼: APIYI를 예로 든 3단계 설정 가이드 및 /v1과 /v1beta 채널 차이점 상세 설명

작성자 주: RikkaHub은 여러 대규모 언어 모델을 지원하는 안드로이드 클라이언트입니다. 이번 글에서는 APIYI를 예로 들어 타사 API 중계 서비스를 연동하는 전체 과정을 상세히 알아보고, 특히 /v1과 /v1beta 채널 유형의 차이점과 자주 발생하는 실수들을 짚어보겠습니다.

스마트폰에서 AI 대규모 언어 모델을 사용할 때, 더 이상 ChatGPT, Gemini, Claude 앱을 번갈아 가며 사용할 필요가 없습니다. RikkaHub은 네이티브 안드로이드 LLM 클라이언트로, 타사 API 중계 서비스를 통해 모든 주요 모델을 연동할 수 있습니다. 하지만 많은 사용자가 설정 과정에서 한 가지 함정에 빠지곤 합니다. 바로 같은 API 키를 사용함에도 PC 버전의 Cherry Studio에서는 모든 모델이 잘 작동하는데, RikkaHub에서는 Google 모델만 작동하고 GPT나 Claude는 안 되는 현상입니다.

문제는 채널 유형인 /v1과 /v1beta의 차이에 있습니다. 이번 글에서는 APIYI를 예로 들어 이 설정 디테일을 확실하게 정리해 드립니다.

핵심 가치: 이 글을 읽고 나면 RikkaHub에서 APIYI 중계 서비스를 올바르게 설정하는 방법과 /v1 및 /v1beta의 차이를 이해하게 되며, 하나의 앱으로 Claude, GPT, Gemini의 모든 모델을 호출할 수 있게 됩니다.

RikkaHub 연동 APIYI 핵심 요점

요점	설명	중요도
채널 유형 선택	/v1은 전체 모델용, /v1beta는 Gemini 전용	가장 중요
Base URL	`https://vip.apiyi.com/v1`	끝 경로 확인 필수
API 키	APIYI 플랫폼에서 획득	하나의 키로 모든 모델 사용
모델 선택	모델명을 직접 입력하거나 목록에서 선택	필요에 따라 설정
설정 방식	채널 유형별로 각각 Provider 생성	권장 방식

RikkaHub란 무엇인가요?

RikkaHub은 오픈 소스 안드로이드 네이티브 LLM 채팅 클라이언트로, Kotlin과 Jetpack Compose로 개발되었으며 Material You 디자인 언어를 채택했습니다. 가장 큰 특징은 하나의 앱에서 여러 AI 서비스 업체를 연동할 수 있고, 대화 중에 자유롭게 모델을 전환할 수 있다는 점입니다.

기본 정보	상세 내용
오픈 소스 주소	`github.com/rikkahub/rikkahub`
최신 버전	v2.1.7 (2026.3.28)
지원 플랫폼	Android + Web
지원 API	OpenAI 호환, Google Gemini 네이티브, Anthropic 호환
핵심 기능	다중 모델 전환, 멀티모달 입력, 검색 연동, MCP 지원
설치 방법	Google Play / GitHub Release / 공식 홈페이지 다운로드

RikkaHub의 주요 기능은 다음과 같습니다:

멀티모달 입력: 이미지, PDF, DOCX 파일 지원
메시지 분기: 대화 중 다양한 답변 방향 탐색
검색 연동: Exa, Tavily, Brave 등 검색 엔진 내장
MCP 지원: Model Context Protocol 호환
Markdown 렌더링: 코드 하이라이트, LaTeX 수식, Mermaid 차트
캐릭터 카드 가져오기: SillyTavern 캐릭터 카드 호환

RikkaHub 설정 APIYI 완벽 가이드

1단계: APIYI API 키 발급받기

먼저 APIYI 플랫폼에서 API 키를 발급받으세요:

APIYI(apiyi.com)에 접속하여 계정을 생성합니다.
콘솔에 진입하여 API 키를 생성합니다.
발급된 키를 복사하여 안전하게 보관하세요(형식: sk-xxxxxxxx).

2단계: RikkaHub에 Provider 추가하기

RikkaHub 앱을 열고 설정 → AI Provider → 새 Provider 추가로 이동하세요:

OpenAI 호환 채널 설정 (모든 모델 사용 시 권장):

설정 항목	입력 내용	설명
Provider 유형	OpenAI Compatible	OpenAI 호환 선택
Base URL	`https://vip.apiyi.com/v1`	끝에 `/v1`이 포함되어야 합니다
API 키	발급받은 APIYI 키	`sk-xxxxxxxx`
모델 이름	필요에 따라 입력	예: `claude-sonnet-4-20250514`

3단계: 모델 선택 및 대화 시작

설정이 완료되면 대화 화면에서 해당 모델을 선택하여 바로 사용할 수 있습니다. APIYI의 통합 인터페이스를 통해 RikkaHub에서 다음 모델들을 호출할 수 있습니다:

Claude 시리즈: claude-sonnet-4, claude-opus-4 등
GPT 시리즈: gpt-5.4, gpt-5.4-mini 등
Gemini 시리즈: gemini-2.5-pro, gemini-2.5-flash 등
오픈소스 모델: Llama 4, DeepSeek 등

🎯 빠른 시작: APIYI(apiyi.com)에서 API 키를 발급받은 후, RikkaHub에 Provider 하나만 추가하면 모바일에서도 자유롭게 주요 AI 모델을 전환하며 사용할 수 있습니다.

/v1 및 /v1beta 채널 유형 상세 설명: 가장 중요한 설정 차이

RikkaHub에서 동일한 키로 특정 모델을 사용할 수 없는 이유

RikkaHub 사용자들이 가장 자주 겪는 문제입니다:

"왜 같은 토큰과 API인데 컴퓨터의 Cherry Studio에서는 되는데, 안드로이드 RikkaHub에서는 구글 모델만 되고 GPT나 Claude는 안 되나요?"

근본 원인: RikkaHub에는 두 가지 채널 유형이 있으며, 잘못 선택하면 일부 모델을 사용할 수 없습니다.

/v1과 /v1beta의 핵심 차이

특성	/v1 (OpenAI 호환)	/v1beta (Gemini 네이티브)
호환 모델	Claude + GPT + Gemini + 오픈소스	Gemini 시리즈 전용
API 형식	OpenAI Chat Completions 형식	Google Gemini 네이티브 형식
Base URL 예시	`https://vip.apiyi.com/v1`	`https://vip.apiyi.com/v1beta`
사용 시나리오	범용, 기본 권장	Gemini 특화 기능 필요 시
Google 모델 호환성	양호	최상

/v1beta의 장점과 한계

/v1beta는 Google Gemini의 네이티브 API 형식입니다. /v1beta 경로를 선택하면 RikkaHub는 OpenAI 호환 형식이 아닌 Gemini 네이티브 요청 형식을 사용하여 서버와 통신합니다.

장점:

Gemini 모델에 대한 최상의 호환성 제공
Gemini 특화 기능(Grounding, Safety Settings 등) 지원
형식 변환 없이 네이티브 응답 수신

한계:

Gemini 시리즈 모델만 사용 가능
Claude, GPT 등 Google 이외의 모델은 전혀 사용할 수 없음
요청 형식이 달라 Claude/GPT로 요청을 보내면 즉시 오류 발생

올바른 설정 방법

방법 A: /v1만 사용 (대부분의 사용자에게 권장)

Claude, GPT, Gemini를 혼합하여 사용한다면 OpenAI 호환 Provider 하나만 생성하면 됩니다:

Provider 유형: OpenAI Compatible
Base URL: https://vip.apiyi.com/v1
API 키: sk-your-apiyi-key

이 설정으로 Gemini를 포함한 APIYI의 모든 모델을 호출할 수 있습니다.

방법 B: /v1 + /v1beta 이중 Provider (고급 사용자용)

Gemini 모델에서 최상의 호환성을 원한다면 두 개의 Provider를 생성하세요:

Provider	유형	Base URL	용도
Provider 1	OpenAI Compatible	`https://vip.apiyi.com/v1`	Claude / GPT / 오픈소스 모델
Provider 2	Gemini	`https://vip.apiyi.com/v1beta`	Gemini 시리즈 (최적 호환)

두 Provider 모두 동일한 APIYI 키를 사용하며, 대화 시 모델에 따라 자동으로 적절한 Provider가 선택됩니다.

💡 주의사항: /v1beta 유형의 Provider만 생성하면 Gemini 모델만 사용할 수 있습니다. 이것이 많은 사용자가 "구글 모델만 된다"고 느끼는 이유입니다. 해결책은 /v1 유형의 Provider를 추가로 생성하거나, /v1만 단독으로 사용하는 것입니다.

RikkaHub 주요 모델 설정 예시

RikkaHub 인기 모델 설정 표

APIYI를 통해 RikkaHub에서 자주 사용하는 모델 설정은 다음과 같습니다.

모델	모델 ID	채널 유형	권장 용도
Claude Sonnet 4	claude-sonnet-4-20250514	/v1	일상 대화, 분석
Claude Opus 4	claude-opus-4-20250514	/v1	복잡한 추론
GPT-5.4	gpt-5.4	/v1	범용 플래그십
GPT-5.4 Mini	gpt-5.4-mini	/v1	경량화 및 고효율
Gemini 2.5 Pro	gemini-2.5-pro	/v1 또는 /v1beta	긴 컨텍스트 윈도우
Gemini 2.5 Flash	gemini-2.5-flash	/v1 또는 /v1beta	빠른 응답
DeepSeek V3	deepseek-chat	/v1	가성비 추론
Llama 4 Maverick	meta-llama/llama-4-maverick	/v1	오픈소스 최상위

RikkaHub 고급 설정 팁

사용자 지정 HTTP 헤더: RikkaHub는 사용자 지정 요청 헤더를 지원합니다. 추가 매개변수를 전달해야 할 경우 사용하세요:

Headers:
  X-Custom-Header: your-value

QR 코드 가져오기/내보내기: 공급자(Provider) 설정을 QR 코드로 생성하여 친구와 공유하거나 여러 기기 간에 동기화할 수 있습니다.

프롬프트 변수: 시스템 프롬프트에서 {model}(현재 모델명), {timestamp}(타임스탬프)와 같은 변수 사용을 지원합니다.

🚀 효율성 팁: APIYI(apiyi.com)의 통합 인터페이스를 사용하면 단 하나의 API 키로 RikkaHub에서 Claude, GPT, Gemini, DeepSeek 등 모든 주요 모델을 자유롭게 전환할 수 있습니다. RikkaHub의 대화 분기 기능을 활용하면 여러 모델의 답변 품질을 빠르게 비교해 볼 수 있습니다.

RikkaHub와 다른 안드로이드 AI 클라이언트 비교

비교 항목	RikkaHub	ChatGPT 앱	Gemini 앱	Claude 앱
멀티모델 지원	모든 모델	GPT 전용	Gemini 전용	Claude 전용
사용자 지정 API	지원	미지원	미지원	미지원
API 중계 서비스	지원	미지원	미지원	미지원
오픈소스	예	아니오	아니오	아니오
MCP 지원	예	아니오	아니오	아니오
검색 통합	멀티 엔진	ChatGPT Search	Google	없음
가격	무료	구독제	구독제	구독제

RikkaHub의 가장 큰 차별화된 장점은 하나의 앱으로 모든 AI 모델을 해결할 수 있다는 점입니다. APIYI와 같은 API 중계 서비스를 활용하면, 각 AI 서비스 제공업체마다 별도로 비용을 지불하거나 앱을 설치할 필요가 없습니다.

🎯 선택 가이드: 만약 한 가지 AI(예: ChatGPT만 사용)만 고집한다면 공식 앱을 사용하는 것이 더 편리합니다. 하지만 대부분의 개발자처럼 여러 모델을 번갈아 사용해야 한다면, RikkaHub와 APIYI(apiyi.com) 조합이 안드로이드에서 가장 유연한 솔루션이 될 것입니다.

RikkaHub APIYI 연동 관련 자주 묻는 질문 및 문제 해결

주요 오류 및 해결 방법

문제 현상	원인	해결 방법
Gemini만 작동하고 나머지는 오류 발생	채널 유형이 /v1beta로 설정됨	/v1으로 변경하거나 OpenAI 호환 Provider를 새로 생성
모든 모델에서 오류 발생	Base URL 입력 오류	`https://vip.apiyi.com/v1`인지 확인
인증 실패	API 키 오류 또는 만료	APIYI 콘솔에서 키 상태 확인
모델 없음	모델 ID 오타	APIYI 문서를 참조하여 모델 ID 확인
응답 형식 이상	채널 유형과 모델 불일치	Gemini는 /v1beta, 나머지는 /v1 사용

자주 묻는 질문

Q1: /v1과 /v1beta 중 무엇을 선택해야 하나요?

대부분의 경우 /v1을 선택하세요. /v1은 OpenAI 호환 형식으로, 모든 모델(Gemini 포함)을 지원합니다. /v1beta는 Gemini 전용 형식으로, Gemini 모델만 지원하지만 호환성이 더 좋습니다. Claude나 GPT를 주로 사용하신다면 /v1을 선택하세요. Gemini의 최적화된 기능을 함께 사용하고 싶다면, 두 개의 Provider를 각각 생성하여 설정할 수 있습니다. APIYI(apiyi.com)의 동일한 API 키 하나로 두 가지 채널을 모두 구성할 수 있습니다.

Q2: Cherry Studio에서는 되는데 RikkaHub에서는 안 돼요. 어떻게 하죠?

가장 흔한 원인은 채널 유형 설정 오류입니다. Cherry Studio는 기본적으로 OpenAI 호환 형식(/v1)을 사용합니다. 만약 RikkaHub에서 Gemini 유형(/v1beta)을 선택했다면 Google 이외의 모델은 사용할 수 없습니다. 해결 방법: 'OpenAI Compatible' 유형의 Provider를 새로 만들고, Base URL에 https://vip.apiyi.com/v1을 입력하세요.

Q3: RikkaHub는 무료인가요?

RikkaHub 앱 자체는 무료 오픈소스입니다. 하지만 AI 모델을 호출할 때는 API 비용이 발생합니다. APIYI(apiyi.com) 플랫폼에서 API 키를 발급받아 실제 사용량만큼만 지불하며, 월간 구독료는 없습니다. ChatGPT Plus($20/월), Claude Pro($20/월), Gemini Advanced($19.99/월)를 각각 구독하는 것보다 APIYI와 RikkaHub를 조합한 종량제 방식이 훨씬 경제적입니다.

요약

RikkaHub에 서드파티 API 중계 서비스를 연동하는 핵심 포인트는 다음과 같습니다:

채널 유형이 핵심: /v1은 모든 모델(Claude/GPT/Gemini/오픈소스)과 호환되며, /v1beta는 Gemini 전용이지만 Google 모델에 대한 호환성이 더 뛰어납니다.
듀얼 Provider 방식 추천: /v1을 범용 채널로, /v1beta를 Gemini 전용 채널로 설정하세요. 동일한 APIYI 키 하나로 모두 가능합니다.
앱 하나로 해결: RikkaHub와 APIYI(apiyi.com)를 조합하면 Android에서 Claude, GPT, Gemini 등 모든 모델을 자유롭게 전환하며 사용할 수 있습니다.

이제 여러 AI 앱을 번갈아 가며 사용할 필요가 없습니다. APIYI(apiyi.com)에서 API 키를 발급받아 보세요. 키 하나로 모든 주요 모델을 커버하고, RikkaHub와 함께 스마트폰을 나만의 AI 만능 비서로 만들어 보세요.

📚 참고 자료

RikkaHub GitHub 저장소: 오픈소스 코드 및 최신 버전 다운로드
- 링크: github.com/rikkahub/rikkahub
- 설명: 전체 소스 코드, 릴리스 다운로드 및 기능 설명 포함
RikkaHub 공식 문서: Provider 설정 및 사용 가이드
- 링크: docs.rikka-ai.com
- 설명: 각 Provider별 상세 설정 방법 포함
APIYI 문서 센터: API 키 발급 및 모델 목록
- 링크: docs.apiyi.com
- 설명: 지원되는 모든 모델의 ID, 가격 및 호출 예제 포함

작성자: APIYI 기술팀
기술 교류: 댓글로 RikkaHub 설정 경험을 공유해 주세요. 더 많은 AI 모델 연동 자료는 APIYI 문서 센터(docs.apiyi.com)에서 확인하실 수 있습니다.

RikkaHub API 중계 서비스 연동 튜토리얼: APIYI를 예로 든 3단계 설정 가이드 및 /v1과 /v1beta 채널 차이점 상세 설명