> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# Cherry Studio에서 BeatAPI 사용하기

> Cherry Studio에 BeatAPI를 OpenAI 유형 제공자로 추가하고, 데스크톱 앱 하나에서 Chat Completions를 지원하는 모델과 대화합니다.

# Cherry Studio에서 BeatAPI 사용하기

Cherry Studio는 여러 제공자를 나란히 사용할 수 있는 데스크톱 채팅 클라이언트입니다. BeatAPI를 OpenAI 유형 제공자로 추가한 뒤, 계정에서 사용할 수 있고 Chat Completions를 지원하는 모델을 선택하세요. 선택 목록에 모델이 있다고 해서 선택한 제공자 유형과 호환된다는 보장은 없습니다.

## 사전 준비

1. **Cherry Studio 설치** — [공식 사이트](https://cherry-ai.com/)에서 받으세요.
2. **BeatAPI API 키** — [대시보드 → API Keys](https://beatapi.io/dashboard/apikeys)에서 만드세요.

## 1단계: 제공자 설정 열기

오른쪽 위의 설정 아이콘을 클릭하거나 `Ctrl+,`(macOS에서는 `Cmd+,`)를 누른 다음 왼쪽 메뉴에서 **Model Service**를 선택하세요.

## 2단계: BeatAPI를 제공자로 추가

모델 서비스 페이지 아래쪽에서 **+ Add**를 클릭하고 다음을 입력하세요.

| 필드            | 값         |
| ------------- | --------- |
| Provider Name | `BeatAPI` |
| Provider Type | `OpenAI`  |

**Confirm**을 클릭하세요. 오른쪽 설정 패널에 다음을 입력합니다.

| 필드      | 값                        |
| ------- | ------------------------ |
| API Key | BeatAPI API 키            |
| API URL | `https://api.beatapi.io` |

> **Note**
>
> `/v1` 접미사나 뒤쪽 경로 **없이** `https://api.beatapi.io`를 입력하세요. Cherry Studio가 `/v1/chat/completions`를 직접 붙이므로, `/v1`을 직접 추가하면 `/v1/v1/chat/completions`가 되어 메시지마다 404 오류가 발생합니다.

오른쪽 위의 BeatAPI 제공자 토글이 **켜져** 있는지(초록색) 확인하고, 모델을 추가하기 전에 **Test** 버튼으로 연결을 확인하세요.

## 3단계: 모델 추가

제공자를 설정했으면 **Models** 섹션에서 **Manage**를 클릭해 모델 선택 창을 여세요. 원하는 ID를 검색하고 \*\*+\*\*를 클릭해 추가합니다.

| 모델 ID                  | 추천 용도                                  |
| ---------------------- | -------------------------------------- |
| `gpt-6-astra`          | 최신 OpenAI 세대. 입력 토큰이 272K를 넘으면 요금이 높아짐 |
| `gpt-5.6-terra`        | 균형 잡힌 일상 대화                            |
| `gemini-3.7-flash`     | 빠르고 저렴한 멀티모달                           |
| `deepseek-v4-pro-0813` | 저렴한 요금의 강력한 추론                         |
| `glm-5.3-flash`        | 대량 대화에 가장 저렴한 등급                       |
| `kimi-k3`              | 긴 컨텍스트 작업                              |
| `qwen3.8-max`          | 중국어 작업                                 |

전체 목록은 [텍스트 API](/text-api) 페이지와 [가격 페이지](https://beatapi.io/pricing)에 있습니다. 원하는 만큼 추가할 수 있으며, 채팅 헤더의 드롭다운에서 전환합니다.

## 4단계: 대화하기

메인 창으로 돌아가 \*\*+\*\*로 새 채팅을 시작하고, 위쪽의 모델 선택기를 클릭해 **BeatAPI** 제공자 아래의 모델을 고르세요.

## 자주 묻는 질문

### Cherry Studio가 연결되지 않음

1. API URL은 `/v1` 없이 `https://api.beatapi.io`여야 합니다.
2. 키가 활성 상태여야 합니다. [대시보드 → API Keys](https://beatapi.io/dashboard/apikeys)에서 확인하세요.
3. 제공자 토글이 켜져 있어야 합니다.

### 모델 목록이 비어 있거나 갱신되지 않음

모델 관리자에서 ID로 모델을 직접 추가하세요. ID는 [가격 페이지](https://beatapi.io/pricing)에 있으며 대소문자를 구분합니다.

### 대화 중 오류

| 상태            | 의미                                                                      | 조치                                                                      |
| ------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `401`         | `missing_api_key` 또는 `invalid_api_key`: 키가 없거나 잘못되었거나 만료, 비활성화, 소진되었습니다 | 대시보드에서 키를 다시 복사하세요                                                      |
| `402`         | `insufficient_credits`: 잔액이 0이거나 가격보다 적습니다                              | 충전하세요                                                                   |
| `404`         | 모델 ID나 API URL이 잘못되었습니다                                                 | 위의 참고 사항과 둘 다 비교하세요                                                     |
| `429`         | 요청 속도 초과                                                                | 기다리세요. 누적 충전액이 늘면 한도도 올라갑니다                                             |
| `500` / `503` | BeatAPI 측의 일시적인 문제(`internal_error`, `processing_*`)                    | `request_id`를 보관한 채 백오프를 두고 재시도하세요. [오류](/errors#text-endpoints)를 참고하세요 |

### 사용량과 지출 확인

대시보드에서 API 키별 호출 수, 토큰, 비용을 볼 수 있습니다. [`GET /v1/usage`](/quick-guide)에서도 같은 수치를 받을 수 있습니다.

## 지원

[대시보드](https://beatapi.io/dashboard)에서 지원 티켓을 열고 실패한 응답의 `request_id`를 함께 보내 주세요.