> 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.

# ChatBox에서 BeatAPI 사용하기

> ChatBox의 OpenAI, Claude 또는 Gemini 제공자 유형으로 BeatAPI를 설정합니다.

# ChatBox에서 BeatAPI 사용하기

ChatBox는 크로스 플랫폼 데스크톱 채팅 클라이언트입니다. BeatAPI는 OpenAI, Anthropic, Gemini 요청 형식을 모두 지원하므로, ChatBox의 세 가지 제공자 유형 중 원하는 모델에 맞는 유형으로 사용할 수 있습니다.

## 사전 준비

1. **ChatBox 설치** — Windows, macOS, Linux 또는 웹 버전.
2. **BeatAPI API 키** — [대시보드 → API Keys](https://beatapi.io/dashboard/apikeys)에서 만드세요.

## 1단계: 설정 열기

처음 실행하면 설정 마법사가 나타납니다. **Use your own API Key or local model**을 클릭하세요.

이미 설정했다면 왼쪽 아래의 톱니바퀴 아이콘이나 `Ctrl+,`(macOS에서는 `Cmd+,`)로 설정을 여세요.

## 2단계: 제공자 유형을 고르고 호스트 입력

클라이언트마다 덧붙이는 경로가 다르므로 API Host는 제공자 유형마다 다릅니다. 이 값을 잘못 넣는 것이 가장 흔한 실패 원인입니다.

| 제공자 유형     | API Host                    | 용도                                                     |
| ---------- | --------------------------- | ------------------------------------------------------ |
| OpenAI API | `https://api.beatapi.io`    | GPT, DeepSeek, GLM, Kimi, MiniMax, Qwen, MiMo, Hunyuan |
| Claude API | `https://api.beatapi.io/v1` | Claude 모델                                              |
| Gemini API | `https://api.beatapi.io/`   | Gemini 모델                                              |

세 경우 모두 API Key는 같은 BeatAPI 키입니다.

> **Note**
>
> 모델 계열에 대해 문서화된 형식과 일치하는 제공자 유형을 고르세요. 모든 모델이 모든 형식을 지원한다고 가정하지 마세요. OpenAI 유형은 `/v1/chat/completions`, Claude 유형은 `/messages`, Gemini 유형은 `v1beta/models/...`를 덧붙이므로 세 호스트가 다릅니다. 위의 각 조합은 실제 BeatAPI 엔드포인트로 연결됩니다.

## 3단계: 모델 선택

드롭다운에서 모델을 고르거나, 목록이 갱신되지 않았다면 ID를 직접 입력하세요.

| 모델 ID                       | 제공자 유형     | 추천 용도            |
| --------------------------- | ---------- | ---------------- |
| `gpt-6-astra`               | OpenAI API | 최신 OpenAI 세대     |
| `gpt-5.6-terra`             | OpenAI API | 균형 잡힌 일상 대화      |
| `claude-fable-5-1`          | Claude API | 최신 Claude 세대     |
| `claude-haiku-4-5-20251001` | Claude API | 빠르고 저렴함          |
| `gemini-3.7-flash`          | Gemini API | 빠른 멀티모달          |
| `deepseek-v4-pro-0813`      | OpenAI API | 저렴한 요금의 강력한 추론   |
| `glm-5.3-flash`             | OpenAI API | 대량 대화에 가장 저렴한 등급 |

전체 목록은 [텍스트 API](/text-api) 페이지와 [가격 페이지](https://beatapi.io/pricing)에 있습니다.

### 선택 파라미터

| 파라미터        | 이펙트       | 권장값                  |
| ----------- | --------- | -------------------- |
| Temperature | 출력의 무작위성  | `0.7` 창의적, `0.3` 정확함 |
| Max Tokens  | 출력 길이 상한  | 2000–4000            |
| Top P       | 누클리어스 샘플링 | `0.9`                |

Max Tokens 설정은 가장 간단한 비용 관리 방법입니다. 대부분의 대화에서 비용이 큰 쪽은 출력입니다.

## 자주 묻는 질문

### ChatBox가 연결되지 않음

1. 위 표와 API Host를 다시 비교하세요. `/v1`은 제공자 유형마다 다릅니다.
2. [대시보드 → API Keys](https://beatapi.io/dashboard/apikeys)에서 키가 활성 상태인지 확인하세요.

### 목록에 BeatAPI 모델이 나타나지 않음

모델 필드에 모델 ID를 직접 입력하세요. ID는 대소문자를 구분하며 [가격 페이지](https://beatapi.io/pricing)에 나와 있습니다.

### 대화 중 오류

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

### 사용량과 지출 확인

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

## 지원

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