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

# Claude Code에서 BeatAPI 사용하기

> Claude Code가 BeatAPI로 요청을 보내도록 설정해, 키 하나로 계정의 모든 Claude 모델을 사용합니다.

# Claude Code에서 BeatAPI 사용하기

Claude Code는 터미널에서 파일을 읽고 쓰고, 명령을 실행하며 작업을 처리하는 명령줄 코딩 에이전트입니다. BeatAPI가 `POST /v1/messages`에서 직접 제공하는 Anthropic Messages 형식을 사용하므로, 변환 계층 없이 기본 URL만 바꾸면 BeatAPI로 연결됩니다.

## 사전 준비

1. **Claude Code 설치** — 아직 설치하지 않았다면 1단계를 참고하세요.
2. **BeatAPI API 키** — [대시보드 → API Keys](https://beatapi.io/dashboard/apikeys)에서 만드세요.

## 1단계: Claude Code 설치

#### macOS / Linux

공식 스크립트로 설치합니다.

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

또는 Homebrew로 설치합니다.

```bash
brew install --cask claude-code
```

#### Windows

PowerShell:

```powershell
irm https://claude.ai/install.ps1 | iex
```

CMD:

```cmd
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
```

#### npm

Node.js 18 이상이 있으면 어떤 운영 체제에서든 설치할 수 있습니다.

```bash
npm install -g @anthropic-ai/claude-code
```

설치를 확인합니다.

```bash
claude --version
```

## 2단계: Claude Code를 BeatAPI로 연결

설정 방법은 세 가지이며, 오래 유지되는 순서로 나열했습니다. 하나를 고르세요.

### 방법 1: settings.json

가장 안정적인 방법입니다. 한 번 설정하면 모든 터미널에서 유지됩니다.

설정 디렉터리를 찾습니다.

* macOS / Linux: `~/.claude`
* Windows: `%userprofile%\.claude`

디렉터리가 없으면 `claude`를 한 번 실행하고 `Ctrl + C`를 눌러 종료하세요. 디렉터리가 자동으로 만들어집니다.

`settings.json`을 만들거나 편집합니다.

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.beatapi.io",
    "ANTHROPIC_AUTH_TOKEN": "<BEATAPI_API_KEY>",
    "ANTHROPIC_MODEL": "claude-fable-5-1",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}
```

| 변수                                         | 값                                                                     |
| ------------------------------------------ | --------------------------------------------------------------------- |
| `ANTHROPIC_BASE_URL`                       | `https://api.beatapi.io` — `/v1` 접미사 없음. 클라이언트가 `/v1/messages`를 덧붙입니다 |
| `ANTHROPIC_AUTH_TOKEN`                     | BeatAPI API 키                                                         |
| `ANTHROPIC_MODEL`                          | 아래 표의 모델 ID                                                           |
| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | `1`로 백그라운드 요청을 줄입니다                                                   |

파일을 저장하고 Claude Code를 다시 시작하세요.

### 방법 2: 영구 환경 변수

#### macOS (zsh)

```bash
echo 'export ANTHROPIC_BASE_URL="https://api.beatapi.io"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN="<BEATAPI_API_KEY>"' >> ~/.zshrc
echo 'export ANTHROPIC_MODEL="claude-fable-5-1"' >> ~/.zshrc
source ~/.zshrc
```

#### Linux (bash)

```bash
echo 'export ANTHROPIC_BASE_URL="https://api.beatapi.io"' >> ~/.bashrc
echo 'export ANTHROPIC_AUTH_TOKEN="<BEATAPI_API_KEY>"' >> ~/.bashrc
echo 'export ANTHROPIC_MODEL="claude-fable-5-1"' >> ~/.bashrc
source ~/.bashrc
```

#### Windows (PowerShell)

```powershell
[System.Environment]::SetEnvironmentVariable('ANTHROPIC_BASE_URL', 'https://api.beatapi.io', 'User')
[System.Environment]::SetEnvironmentVariable('ANTHROPIC_AUTH_TOKEN', '<BEATAPI_API_KEY>', 'User')
[System.Environment]::SetEnvironmentVariable('ANTHROPIC_MODEL', 'claude-fable-5-1', 'User')
```

그런 다음 터미널을 다시 시작하세요.

### 방법 3: 현재 터미널에서만

빠르게 테스트할 때 유용합니다. 터미널을 닫으면 값이 사라집니다.

```bash
export ANTHROPIC_BASE_URL="https://api.beatapi.io"
export ANTHROPIC_AUTH_TOKEN="<BEATAPI_API_KEY>"
export ANTHROPIC_MODEL="claude-fable-5-1"
claude
```

## 3단계: 확인하고 작업 시작

```bash
claude "Hello"
```

답변이 오면 설정이 적용된 것입니다. 로그인 화면, `401` 또는 `403`이 나타나면 적용되지 않은 것이니 아래 FAQ를 참고하세요.

Claude Code에는 두 가지 사용 모드가 있습니다.

* **대화형** — `claude`를 실행해 세션을 이어 가며, 여러 단계의 작업에 적합합니다.
* **단발형** — `claude "your question"`을 실행해 답변 하나만 받습니다.

## 모델

같은 키로 계정의 모든 Claude 모델을 사용할 수 있습니다. 대화형 세션에서 `/model`로 전환하거나, `ANTHROPIC_MODEL`을 바꾸고 다시 시작하세요.

| 모델 ID                       | 추천 용도                              |
| --------------------------- | ---------------------------------- |
| `claude-fable-5-1`          | 최신 세대. 에이전트 코딩의 기본값                |
| `claude-opus-5`             | 가장 강력한 추론 등급. 어려운 아키텍처 설계와 디버깅용    |
| `claude-sonnet-5-5`         | 코딩과 에이전트 워크플로. 1M 컨텍스트, 최대 128K 출력 |
| `claude-sonnet-5`           | 일상 작업을 위한 성능과 속도의 균형               |
| `claude-haiku-4-5-20251001` | 가장 빠르고 저렴함. 간단한 수정과 대량 처리 단계용      |

모델별 가격은 [가격 페이지](https://beatapi.io/pricing)에, 요청 형식은 [Claude API](/text-api/claude/messages) 페이지에 있습니다.

### Sonnet 5.5 설정

아래 값을 `~/.claude/settings.json`에 병합하고 키 자리 표시자를 바꾼 뒤 Claude Code를 다시 시작하세요.

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.beatapi.io",
    "ANTHROPIC_AUTH_TOKEN": "<BEATAPI_API_KEY>",
    "ANTHROPIC_MODEL": "claude-sonnet-5-5"
  }
}
```

Sonnet 5.5는 기본적으로 적응형 사고를 사용합니다. 사고와 도구 설정은 Claude Code가 관리하도록 두세요. 제한과 현재 토큰 요금은 [Sonnet 5.5 모델 가이드](/text-api/claude/messages)를 참고하세요.

## 자주 쓰는 명령

| 명령                  | 설명         |
| ------------------- | ---------- |
| `claude`            | 대화형 모드 시작  |
| `claude "question"` | 단일 질의      |
| `claude --version`  | 버전 표시      |
| `/model`            | 세션 중 모델 전환 |
| `/help`             | 도움말 표시     |
| `Ctrl + C`          | 대화형 모드 종료  |

## 자주 묻는 질문

### 설정 후에도 로그인 화면이 나타남

설정이 적용되지 않았습니다.

1. `settings.json`을 사용하는 경우 — 경로가 `~/.claude/settings.json`(Windows에서는 `%userprofile%\.claude\settings.json`)인지 확인하세요.
2. 환경 변수를 사용하는 경우 — 변수를 설정한 터미널에서 Claude Code를 실행했는지 확인하세요.
3. JSON이 올바른지 확인하세요. 중괄호 짝, 마지막 쉼표, 둥근 따옴표 대신 곧은 따옴표를 썼는지 살펴보세요.

### 401 또는 403

| 상태    | 의미                                                                      | 조치                                                                         |
| ----- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `401` | `missing_api_key` 또는 `invalid_api_key`: 키가 없거나 잘못되었거나 만료, 비활성화, 소진되었습니다 | [대시보드 → API Keys](https://beatapi.io/dashboard/apikeys)에서 키가 활성 상태인지 확인하세요 |
| `403` | `forbidden`: 키나 계정이 이 모델을 사용할 수 없습니다(예: 무료 크레딧)                         | 계정 상태와 요청한 모델을 확인하세요                                                       |

`ANTHROPIC_BASE_URL`이 모델 제조사의 주소가 아니라 `https://api.beatapi.io`인지도 확인하세요.

### 시작할 때 "Auth conflict"가 표시됨

```
Auth conflict: Both a token (claude.ai) and an API key (ANTHROPIC_API_KEY) are set.
```

공식 계정에 로그인한 상태에서 API 키도 설정되어 있습니다. Claude Code에서 `/logout`을 실행해 세션을 지우고 키를 유지하세요.

### 402 insufficient_credits

잔액 부족: 계정 잔액이 0이거나 요청 가격보다 적습니다. 대시보드에서 충전하세요. 처리 중인 요청은 대기열에 들어가지 않고 실패합니다.

### 429 rate_limit_exceeded

키의 요청 속도 한도를 넘었습니다. BeatAPI가 `Retry-After`를 반환하니 그 시간만큼 기다린 뒤 재시도하세요. 분당 한도는 누적 충전액에 따라 올라가며 대시보드에 표시됩니다.

### 연결 실패

1. 전반적인 네트워크 연결을 확인하세요.
2. `ANTHROPIC_BASE_URL`에 오타나 불필요한 `/v1`이 없는지 다시 확인하세요.
3. 회사 프록시를 사용한다면 `api.beatapi.io`를 허용하세요.

### 사용량과 지출 확인

대시보드에서 키별 호출 수, 토큰 사용량, 비용을 볼 수 있습니다. [`GET /v1/usage`](/quick-guide)에서 프로그래밍 방식으로도 같은 수치를 받을 수 있습니다.

## 지원

[대시보드](https://beatapi.io/dashboard)에서 지원 티켓을 열고 실패한 응답의 `request_id`를 함께 보내 주세요. 이 값으로 로그에서 해당 호출을 정확히 찾을 수 있습니다.