연결과 사용

어떤 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를 반환합니다

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

/v1이 중복되었거나 빠졌습니다. 위 표를 참고하세요. /v1/v1/chat/completions 같은 경로는 없습니다.
base URL 끝의 슬래시를 일부 클라이언트가 그대로 이어 붙입니다.
공개 범위에 포함되지 않은 엔드포인트입니다. BeatAPI는 텍스트, 작업, 파일, 사용량, 웹훅, 실시간 등 정해진 목록만 공개합니다. 그 밖의 엔드포인트는 의도적으로 오류 대신 404를 반환합니다. /v1/embeddings, /v1/rerank, /v1/audio/*는 제공하지 않습니다.
존재하지 않는 모델 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에서 키가 아직 활성 상태인지 확인하세요. 폐기된 키는 즉시, 영구적으로 실패합니다.
일부 클라이언트는 대신 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입니다. 오류를 참고하세요.

402 insufficient_credits

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

429 rate_limit_exceeded

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

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

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

요청 시간이 초과됩니다

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

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

작업이 끝나지 않습니다

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

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

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

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

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

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

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