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

# 연결과 사용

> base URL, 인증 실패, 404 오류, 시간 초과, BeatAPI에 도달하지 않는 요청을 진단합니다.

# 연결과 사용

## 어떤 base URL을 사용해야 하나요?

`https://api.beatapi.io`입니다. 끝에 `/v1`을 붙일지는 클라이언트가 무엇을 자동으로 덧붙이는지에 따라 다릅니다.

| 클라이언트 유형                       | Base URL                                               | 자동으로 덧붙이는 경로         |
| ------------------------------ | ------------------------------------------------------ | -------------------- |
| OpenAI SDK 및 OpenAI 호환 도구      | `https://api.beatapi.io/v1`                            | `/chat/completions`  |
| Anthropic SDK 및 Claude 네이티브 도구 | `https://api.beatapi.io`                               | `/v1/messages`       |
| Gemini SDK 및 Gemini 네이티브 도구    | `https://api.beatapi.io`                               | `/v1beta/models/...` |
| 직접 HTTP 호출                     | 전체 경로(예: `https://api.beatapi.io/v1/chat/completions`) | 없음                   |

이 값을 잘못 설정하면 모든 요청에서 `404`가 발생하며, 대부분의 클라이언트는 이를 잘못된 URL이 아니라 '연결할 수 없음'으로 표시합니다.

## 모든 요청이 404를 반환합니다

가능성이 높은 순서대로 확인하세요.

1. **`/v1`이 중복되었거나 빠졌습니다.** 위 표를 참고하세요. `/v1/v1/chat/completions` 같은 경로는 없습니다.
2. base URL 끝의 **슬래시**를 일부 클라이언트가 그대로 이어 붙입니다.
3. **공개 범위에 포함되지 않은 엔드포인트입니다.** BeatAPI는 텍스트, 작업, 파일, 사용량, 웹훅, 실시간 등 정해진 목록만 공개합니다. 그 밖의 엔드포인트는 의도적으로 오류 대신 `404`를 반환합니다. `/v1/embeddings`, `/v1/rerank`, `/v1/audio/*`는 제공하지 않습니다.
4. **존재하지 않는 모델 ID입니다.** ID는 대소문자를 구분하며 공급사 접두사가 붙지 않습니다. `anthropic/claude-fable-5-1`이 아니라 `claude-fable-5-1`입니다.

## 401 missing_api_key 또는 invalid_api_key

`missing_api_key`는 키가 BeatAPI에 전달되지 않았다는 뜻입니다. `invalid_api_key`는 키가 전달되었지만 잘못되었거나 만료, 비활성화, 소진되었다는 뜻이며, 메시지에 원인이 표시됩니다. 오래된 클라이언트에서는 두 경우 모두 이전 이름인 `unauthorized`가 보일 수 있습니다.

* 헤더는 `Authorization: Bearer <key>`입니다. `Bearer ` 접두사가 빠지면 형식이 잘못된 키로 인식됩니다.
* 키를 붙여 넣을 때 앞뒤에 들어간 공백도 키의 일부로 처리됩니다.
* [대시보드 → API Keys](https://beatapi.io/dashboard/apikeys)에서 키가 아직 활성 상태인지 확인하세요. 폐기된 키는 즉시, 영구적으로 실패합니다.
* 일부 클라이언트는 대신 `x-api-key` 또는 `x-goog-api-key` 헤더를 보내는데, 문제없습니다. 모두 같은 계정과 같은 잔액을 가리킵니다.

## 403 forbidden

인증은 성공했지만 이 계정이나 키로는 해당 작업이 허용되지 않습니다. 요청을 살펴보기 전에 키 자체의 제한(IP 허용 목록, 호출 가능한 모델 그룹)과 계정 상태를 확인하세요. 무료 크레딧만 있는 계정에서는 무료 목록에 없는 모델이 그 사실을 알리는 메시지와 함께 `403 forbidden`을 반환하며, 충전하면 사용할 수 있습니다.

BeatAPI가 반환하는 `403`은 항상 BeatAPI 자체의 판단입니다. 모델의 응답을 `403`으로 그대로 전달하는 일은 없습니다. (본문이 `error code: 1010`인 `403`은 네트워크 엣지에서 온 것이므로 `User-Agent`를 명시적으로 설정하세요.) 콘텐츠 검수에서 거부된 프롬프트는 생성 시 `400 content_policy_violation`이고, 접수된 작업에서는 `error_code`의 `content_policy_violation`입니다. [오류](/errors)를 참고하세요.

## 402 insufficient_credits

잔액이 0이거나 요청 가격보다 적습니다. 크레딧을 충전할 때까지 계정의 모든 유료 작업이 `402`로 실패하며, 키별로 적용되는 것이 아닙니다. 잔액 부족은 모든 엔드포인트에서 항상 `402`입니다. 사용자에게 노출되는 서비스를 운영한다면 알림을 설정해 두는 것이 좋습니다.

## 429 rate_limit_exceeded

서로 다른 두 가지 한도가 `429`를 반환하며, 대응 방법은 정반대입니다.

* **요청 속도** — 이 키의 분당 요청 수가 너무 많습니다. `Retry-After` 또는 `retry_after_seconds`를 따르세요. 한도는 누적 충전액에 따라 올라갑니다. 단, 무료 모델에는 별도의 고정 한도가 있습니다. 첫 충전 전에는 분당 성공 요청 1건, 충전 후에는 분당 최대 10건이며 유료 한도와 따로 계산됩니다.

첫 번째 경우는 대개 폴링 루프가 원인입니다. 작업 엔드포인트는 키당 분당 최대 120건의 요청을 허용하는데, 여러 작업을 1초 간격으로 고정 폴링하면 그것만으로도 한도를 다 씁니다. [개발 가이드](/development)를 참고하세요.

## 요청 시간이 초과됩니다

`stream: false`를 사용하는 텍스트 호출은 모델이 끝날 때까지 아무것도 반환하지 않으며, 추론이 긴 응답은 시간이 꽤 걸릴 수 있습니다. 다음 두 가지가 도움이 됩니다.

* **스트리밍하세요.** `stream: true`를 사용하면 첫 바이트가 빠르게 도착하고 연결이 끝까지 활성 상태로 유지됩니다.
* **클라이언트 시간 제한을 늘리세요.** 많은 SDK의 기본값은 30초 또는 60초로, 스트리밍하지 않는 긴 응답에는 짧습니다.

## 작업이 끝나지 않습니다

시간이 아니라 상태를 확인하세요. `GET /v1/tasks/{task_id}`는 정해진 상태 중 하나를 반환하며, 그중 두 가지는 '처리 중'이 아닙니다.

* Music Video 작업의 `storyboard_ready`와 `requires_action`은 모델이 아니라 **사용자의 조치**를 기다리는 상태입니다. 계속 폴링해도 다음 단계로 넘어가지 않습니다.

나머지는 종료 상태(`succeeded`, `failed`)이거나 실제로 처리 중인 상태입니다. 전체 표는 [빠른 시작](/quick-guide)에 있습니다.

## 서버에서는 연결이 실패하지만 노트북에서는 동작합니다

실제로 호출하는 머신에서 테스트하세요. Dify, Docker로 실행하는 AnythingLLM, CI 러너 같은 자체 호스팅 플랫폼에는 별도의 아웃바운드 규칙이 있습니다. 컨테이너나 호스트가 `api.beatapi.io`에 접근할 수 있는지 확인하고, 사내 프록시가 있다면 통과하도록 허용하세요.

## 버그 신고에는 무엇을 포함해야 하나요?

실패한 응답의 `request_id`를 포함하세요. 모든 BeatAPI 오류에 들어 있으며, 로그에서 정확한 호출을 찾는 데 사용됩니다. 모델 ID, 엔드포인트, 대략적인 시각도 함께 적어 주세요. 티켓은 [대시보드](https://beatapi.io/dashboard)에서 열 수 있습니다.