Cherry Studio

Cherry Studio는 사용자 지정 공급자로 HiAPI에 연결할 수 있습니다. 하나의 공급자에 OpenAI, Anthropic, OpenAI Responses 세 엔드포인트를 동시에 둘 수 있고, 각각 다른 프로토콜에 대응하므로 모델이 지원하는 프로토콜에 맞는 엔드포인트를 고르면 됩니다. 아래 단계는 claude-opus-5-5, gpt-6-astra, deepseek-v4.1-flash를 예로 사용하며, 이 튜토리얼은 Cherry Studio 2.1.7에서 검증했습니다.

1. HiAPI API 키 준비

API 키 발급받기에 설명된 대로 키를 준비하고, 키 옆의 복사 아이콘을 클릭해 전체 HiAPI API 키를 복사해 아래 Cherry Studio에 입력하세요.

2. 프로토콜 선택

이 페이지의 예시 모델은 모두 위 표와 함께 테스트를 마쳤습니다. 다른 모델은 먼저 표에서 엔드포인트를 골라 메시지를 보내 시험해 보세요. 400 does not support this endpoint가 나오면 다른 엔드포인트로 바꾸세요.

3. 공급자 추가

3.1 시작 위치

Settings → Model Providers → Add Provider (设置 → 模型服务 → 添加提供商)를 클릭합니다.

3.2 세 엔드포인트에 같은 주소 입력

세 엔드포인트 모두 /v1 없이 https://api.hiapi.ai를 입력하세요. Cherry Studio가 경로를 직접 덧붙입니다. 다른 도구와 다른 점입니다.

3.3 실제 요청 경로 확인

맞지 않을 때: /v1/v1/...이 보이면 해당 항목을 https://api.hiapi.ai로 바꾸고, /v1이 빠졌다면 https://api.hiapi.ai/v1로 바꾸세요.

4. 모델 추가 및 프로토콜 설정

모델 이름을 추가한 뒤 모델의 연필 아이콘을 클릭해 Edit Model (编辑模型)을 열고, 모델의 프로토콜에 맞는 Chat protocol (对话协议)을 선택한 다음 Max output tokens (最大输出 Token)을 설정합니다.

4.1 프로토콜 예시

아래 세 모델로 먼저 모델 이름을 추가하세요:

claude-opus-5-5
gpt-6-astra
deepseek-v4.1-flash

그다음 모델의 연필 아이콘 → Edit Model (编辑模型)을 클릭하고 채팅 프로토콜을 아래와 같이 선택합니다:

5. 확인

설정을 바꾼 뒤에는 새 채팅을 시작해 테스트하세요. 기존 채팅에는 매개변수가 캐시되어 있습니다.

5.1 채팅

새 채팅을 시작하고 설정한 각 모델로 “안녕하세요, 한 문장으로 자기소개를 해 주세요.”를 보내세요. 정상적으로 답하면 연결이 된 것입니다.

5.2 도구 호출

MCP 설정 가이드의 Cherry Studio 섹션에 설명된 대로 MCP를 설정한 뒤(내장 서버 또는 마켓플레이스에서 설치한 서버), MCP가 접근할 수 있는 폴더에 tool-call-test.txt를 만들고 hello hiapi 한 줄을 써서 저장하세요. 그다음 “파일 읽기 도구를 한 번만 사용하세요. tool-call-test.txt의 전체 내용을 읽고 그대로 반환하세요. 파일을 수정하지 말고, 다른 파일을 읽지 말고, 파일 이름으로 내용을 추측하지 마세요.”를 보내세요. 도구 호출이 나타나고 hello hiapi를 반환하면 됩니다.

6. 문제 해결

여기에는 Cherry Studio에 특화된 문제만 정리했습니다. 401, 404, 429 같은 일반적인 오류는 자주 발생하는 오류를 참고하세요.