텍스트 API

• BeatAPI는 텍스트 모델을 토큰 단위로 계량하는 동기식 API로 제공합니다. BeatAPI 키 하나로 애플리케이션이 이미 쓰는 요청 형식을 그대로 보내세요.
• 모든 텍스트 모델에 키 하나, 기본 URL 하나: https://direct.beatapi.io(권장) 또는 https://api.beatapi.io(대안).
• 네 가지 요청 형식: OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, Gemini 네이티브. 어떤 형식을 쓰는지는 모델 계열에 따라 다르며, 아래 표를 참고하세요.
• 텍스트 호출은 JSON을 바로 반환하거나 서버 전송 이벤트를 스트리밍합니다. 비동기 BeatAPI 작업을 만들지 않습니다.
• GET /v1/text/models는 공개되어 있어 키 없이 모델 ID, 컨텍스트 창, 출력 한도, 가격을 읽을 수 있습니다.

프로토콜 선택

기본 URL과 인증

텍스트 요청에는 https://direct.beatapi.io를 사용하세요. Cloudflare의 100초 제한을 받지 않습니다. https://api.beatapi.io는 대안입니다. 키는 SDK가 이미 쓰는 헤더로 보내세요. 어느 헤더든 같은 BeatAPI 계정과 USD 잔액을 가리킵니다. 키는 sk- 접두사가 있든 없든 동작합니다.

모델별로 사용할 형식

• GPT는 OpenAI Chat Completions나 OpenAI Responses로 호출합니다. 추론과 도구 호출을 새로 연동한다면 Responses를 권장합니다.
• Claude는 Anthropic Messages(POST /v1/messages)로 호출합니다.
• Gemini는 Chat Completions, Responses, Anthropic Messages, Gemini 네이티브 네 형식 모두로 호출할 수 있습니다.
• 그 밖의 모든 계열은 Chat Completions, Responses, Anthropic Messages로 호출할 수 있습니다. Messages 요청에는 anthropic-version 헤더가 들어갑니다. 확실하지 않다면 Chat Completions를 사용하세요.

빠른 시작

curl --request POST \
  --url https://direct.beatapi.io/v1/chat/completions \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "glm-5.3",
  "messages": [{ "role": "user", "content": "Say hello in one sentence." }]
}'

모델 찾기

GET /v1/text/models

공개되어 있으며 익명으로 호출할 수 있어 키가 필요 없습니다. https://api.beatapi.io/v1/text/models에서 호출하세요. direct.beatapi.io는 이 목록이 아니라 모델 호출을 처리합니다. data.data에 모델마다 항목 하나씩을 반환합니다.

무료 모델(ID가 -free로 끝남)은 id, family, endpoints만 표시하며 가격, 컨텍스트 창, 설명은 공개하지 않습니다. 무료 모델을 참고하세요.

목록에는 텍스트 모델만 있습니다.

GET /v1/models

키가 필요합니다. 해당 키로 호출할 수 있는 모델을 OpenAI 목록 형식(id, object, created, owned_by, supported_endpoint_types)으로 data에 감싸 반환합니다. x-api-key와 anthropic-version이 있으면 Anthropic 목록 형식으로, x-goog-api-key 또는 ?key=가 있으면 Gemini 목록 형식으로 응답합니다. 키의 그룹이 접근할 수 없는 모델과, 무료 크레딧 상태에서 계정이 쓸 수 없는 모델은 제외합니다. 요청 속도 제한이 없습니다.

스트리밍

Chat Completions, Responses, Messages에서는 "stream": true를 설정하세요. Gemini 네이티브는 :streamGenerateContent?alt=sse를 호출하세요. 응답은 text/event-stream이며, 스트리밍하지 않으면 application/json입니다. 모델 호출 전에 발생한 실패는 스트림 이벤트가 아니라 HTTP 상태와 함께 일반 JSON 오류로 반환됩니다.

max_tokens와 출력 한도

• 게이트웨이가 max_tokens(Chat Completions, Messages)와 max_output_tokens(Responses)에 받는 최댓값은 1,073,741,823입니다. 그보다 크면 400 bad_request입니다.
• 게이트웨이는 이 값을 카탈로그에 있는 모델의 max_output_tokens와 비교하지 않습니다. 그 값 이하로 설정하세요. 초과했을 때의 동작은 모델 라인이 결정하며 보장되지 않습니다.
• max_tokens는 요청에 필요한 잔액을 추정하는 데도 쓰입니다. 실제 출력이 작더라도 값이 너무 크면 402 insufficient_credits로 거부될 수 있습니다. 필요한 만큼만 설정하세요.

요청 속도 제한

• 계정마다 분당 성공 요청 한도가 있으며, 계정의 누적 충전액에 따라 올라갑니다. 교환 코드, 추천 보너스, 프로모션 크레딧은 포함되지 않습니다. 수치는 표로 공개하지 않으니 대시보드에서 내 한도와 다음 등급을 확인하세요.
• 요청은 실행되는 동안 슬롯을 차지하며, 실패한 요청은 슬롯을 돌려줍니다.
• GET /v1/models에는 요청 속도 제한이 없습니다.
• 무료 모델은 별도의 한도가 있습니다. 무료 모델을 참고하세요.
• 한도에 도달하면 retry_after_seconds, Retry-After 헤더와 함께 429 rate_limit_exceeded가 반환됩니다. 그 시간만큼 기다린 뒤 재시도하세요.

오류

텍스트 호출은 두 단계에서 실패할 수 있으며, 단계마다 본문 형식이 다릅니다. 전체 코드 표와 재시도 정책은 오류에 있으며, 여기서는 요약만 다룹니다.

1. 모델 호출 전. /v1/chat/completions, /v1/responses, /v1/messages에서는 BeatAPI 오류 형식(code, message, retryable, request_id, 그리고 429일 때 retry_after_seconds)을 사용합니다. Gemini 네이티브 엔드포인트(/v1beta/...)와 GET /v1/models는 이 형식을 쓰지 않습니다. 오류는 retryable이나 retry_after_seconds 없이 {"error":{"message":"... (request id: ...)","type":"beatapi_error","code":...}} 형식이지만, 429에는 여전히 Retry-After 헤더가 있습니다.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded: this model allows at most 10 successful requests per minute per account. Retry after 60 seconds.",
    "retryable": true,
    "request_id": "req_abc123",
    "retry_after_seconds": 60
  }
}

알 수 없는 모델은 404 not_found입니다: The requested model is not available to this key: check the model id against GET /v1/models, or retry in a few minutes if it worked before.

2. 호출 중. 본문은 SDK 고유의 형식을 유지하므로 OpenAI와 Anthropic SDK가 파싱해 평소와 같은 예외를 발생시킵니다. 게이트웨이가 직접 거부하면 BeatAPI 코드(insufficient_credits, content_policy_violation, bad_request, not_found 또는 internal_error)를 사용하며, error.type은 beatapi_error이고 코드는 error.code에 있습니다. /v1/messages에서는 코드가 error.type에 있습니다. 모델 측 실패는 temporary_error, upstream_timeout, model_unavailable 또는 rate_limit_exceeded 코드로 바뀌고 상태는 유지되지만, 502와 504는 503이 됩니다(BeatAPI 측 계정 문제는 503 model_unavailable). 컨텍스트가 너무 긴 경우처럼 모델이 낸 영어 파라미터 오류는 입력을 고칠 수 있도록 문장 그대로 전달됩니다. 이 단계에서는 모든 message 뒤에 요청 id가 붙습니다. retryable 필드는 없으며, 여기서 429에 Retry-After가 있다고 보장하지 않으니 상태와 코드를 사용하세요. 오류를 참고하세요.

{
  "error": {
    "message": "This API key's remaining quota is below the price of this request. Raise the key's quota in the console or use another key. (request id: req_abc123)",
    "type": "beatapi_error",
    "param": "",
    "code": "insufficient_credits"
  }
}

429, 500, 503만 백오프를 두고 재시도하세요.

전체 텍스트 모델

게이트웨이 카탈로그에서 생성한 현재 텍스트 모델 전체 목록입니다. 계열을 클릭하면 프로토콜 페이지로 이동합니다. 가격은 BeatAPI가 청구하는 금액이며 1M 토큰당 USD입니다.

• 가격은 할인이 적용된 기본 등급입니다. 롱 컨텍스트 등급, 캐시 입력 요금, 캐시 쓰기는 이 표에 없습니다. 가격표를 참고하세요.
• —는 카탈로그에서 해당 수치를 공개하지 않는다는 뜻입니다.
• * 모델의 피크 시간대에는 피크 배율이 적용됩니다. 표시된 가격은 비피크 기본 가격입니다.

무료 모델

무료 모델은 토큰당 요금이 없고 분당 한도가 따로 있습니다. 무료 모델에 설명되어 있으며, 각 모델은 마지막 열에 있는 유료 모델의 무료 버전입니다.

레거시 모델

계속 동작하는 이전 모델 ID는 레거시 모델에 전환할 현재 모델과 함께 나와 있습니다.