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

# 텍스트 API

> API 키 하나로 OpenAI Chat Completions, OpenAI Responses, Anthropic Messages 또는 Gemini 네이티브 요청을 통해 BeatAPI 텍스트 모델을 호출합니다.

* 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, 컨텍스트 창, 출력 한도, 가격을 읽을 수 있습니다.

> **Note**
>
> 텍스트 요청의 기본 URL로는 `https://direct.beatapi.io`를 사용하세요. Cloudflare의 100초 제한을 받지 않으므로 스트리밍하지 않는 긴 요청도 끊기지 않습니다. `https://api.beatapi.io`도 동작하며, 네트워크에서 `direct.beatapi.io`에 접근할 수 없을 때의 대안입니다. 키, 모델, 가격은 양쪽이 같습니다. 이미지와 영상 API는 `https://api.beatapi.io`만 사용합니다.

## 프로토콜 선택

| 프로토콜                    | 엔드포인트                                         | SDK                            | 계열                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ----------------------- | --------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| OpenAI Chat Completions | `POST /v1/chat/completions`                   | OpenAI SDK(`chat.completions`) | [GPT](/text-api/gpt/chat-completions), [Gemini](/text-api/gemini/chat-completions), [Grok](/text-api/grok/chat-completions), [DeepSeek](/text-api/deepseek/chat-completions), [GLM](/text-api/glm/chat-completions), [Qwen](/text-api/qwen/chat-completions), [Kimi](/text-api/kimi/chat-completions), [MiniMax](/text-api/minimax/chat-completions), [MiMo](/text-api/mimo/chat-completions), [Hunyuan](/text-api/hunyuan/chat-completions), [Muse](/text-api/muse/chat-completions) |
| OpenAI Responses        | `POST /v1/responses`                          | OpenAI SDK(`responses`)        | [GPT](/text-api/gpt/responses), [Gemini](/text-api/gemini/responses), [Grok](/text-api/grok/responses), [DeepSeek](/text-api/deepseek/responses), [GLM](/text-api/glm/responses), [Qwen](/text-api/qwen/responses), [Kimi](/text-api/kimi/responses), [MiniMax](/text-api/minimax/responses), [MiMo](/text-api/mimo/responses), [Hunyuan](/text-api/hunyuan/responses), [Muse](/text-api/muse/responses)                                                                              |
| Anthropic Messages      | `POST /v1/messages`                           | Anthropic SDK(`messages`)      | [Claude](/text-api/claude/messages), [Gemini](/text-api/gemini/messages), [Grok](/text-api/grok/messages), [DeepSeek](/text-api/deepseek/messages), [GLM](/text-api/glm/messages), [Qwen](/text-api/qwen/messages), [Kimi](/text-api/kimi/messages), [MiniMax](/text-api/minimax/messages), [MiMo](/text-api/mimo/messages), [Hunyuan](/text-api/hunyuan/messages), [Muse](/text-api/muse/messages)                                                                                   |
| Gemini 네이티브             | `POST /v1beta/models/{model}:generateContent` | Gemini SDK 또는 일반 HTTP          | [Gemini](/text-api/gemini/native)                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

## 기본 URL과 인증

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

| 형식                                        | 키 헤더                                                           |
| ----------------------------------------- | -------------------------------------------------------------- |
| OpenAI Chat Completions, OpenAI Responses | `Authorization: Bearer <BEATAPI_API_KEY>`                      |
| Anthropic Messages                        | `x-api-key: <BEATAPI_API_KEY>` 또는 `Authorization: Bearer`      |
| Gemini 네이티브                               | `x-goog-api-key: <BEATAPI_API_KEY>` 또는 `Authorization: Bearer` |

> **Note**
>
> 영구 BeatAPI API 키는 신뢰할 수 있는 서버에 보관하세요. 브라우저나 모바일 앱에 포함해 배포하지 마세요.

## 모델별로 사용할 형식

* **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`**

```bash title="cURL"
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." }]
}'
```

**`Python`**

```python title="Python"
import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["BEATAPI_API_KEY"], base_url="https://direct.beatapi.io/v1")
completion = client.chat.completions.create(
    model="glm-5.3",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
print(completion.choices[0].message.content)
```

**`JavaScript`**

```javascript title="JavaScript"
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.BEATAPI_API_KEY,
  baseURL: "https://direct.beatapi.io/v1",
});
const completion = await client.chat.completions.create({
  model: "glm-5.3",
  messages: [{ role: "user", content: "Say hello in one sentence." }],
});
console.log(completion.choices[0].message.content);
```

## 모델 찾기

### `GET /v1/text/models`

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

| 필드                                                | 의미                                                                                                                                                                            |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                                              | `model`로 보낼 모델 ID입니다.                                                                                                                                                         |
| `family`                                          | 모델이 라우팅되고 과금되는 그룹입니다. 키가 해당 계열에 접근할 수 있어야 모델을 호출할 수 있습니다.                                                                                                                     |
| `endpoints`                                       | 모델 라인이 네이티브로 지원하는 형식: `openai`(Chat Completions), `anthropic`(Messages), `openai-response`(Responses). 호출할 수 있는 형식의 전체 목록은 **아닙니다**. 모델별로 문서화된 형식은 이 필드가 아니라 계열 페이지에 나와 있습니다. |
| `context_length`                                  | 토큰 단위 컨텍스트 창입니다. 공개되지 않으면 생략됩니다.                                                                                                                                              |
| `max_output_tokens`                               | 토큰 단위 최대 출력입니다. 공개되지 않으면 생략됩니다.                                                                                                                                               |
| `input_usd_per_million`, `output_usd_per_million` | 할인이 적용된 1M 토큰당 USD 가격입니다. 기본 등급이며 롱 컨텍스트 등급은 포함되지 않습니다.                                                                                                                       |
| `discount`                                        | 실제 가격은 정가에 `discount`를 곱한 값입니다(`0.7`은 정가에서 30% 할인). 1이면 생략됩니다.                                                                                                                |
| `time_rules`                                      | 피크 시간 가격 배율과 조건, 현재 적용 여부입니다. 모델에 배율이 없으면 생략됩니다.                                                                                                                              |
| `capabilities`                                    | reasoning, tools 같은 자유 형식 라벨입니다. 참고용이며 계약이 아닙니다.                                                                                                                              |
| `description`                                     | 짧은 설명입니다.                                                                                                                                                                     |

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

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

### `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`에는 요청 속도 제한이 없습니다.
* 무료 모델은 별도의 한도가 있습니다. [무료 모델](/free-models)을 참고하세요.
* 한도에 도달하면 `retry_after_seconds`, `Retry-After` 헤더와 함께 `429 rate_limit_exceeded`가 반환됩니다. 그 시간만큼 기다린 뒤 재시도하세요.

## 오류

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

**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` 헤더가 있습니다.

| HTTP  | 코드                                   | 원인                                                                       |
| ----- | ------------------------------------ | ------------------------------------------------------------------------ |
| `401` | `missing_api_key`, `invalid_api_key` | 키가 없거나 잘못되었거나 만료·비활성화·소진되었습니다.                                           |
| `403` | `forbidden`                          | 계정이 무료 크레딧 상태인데 모델이 무료 목록에 없거나, 요청이 키의 IP 허용 목록 밖이거나, 모델이 키의 그룹 밖에 있습니다. |
| `404` | `not_found`                          | 이 키로 알 수 없거나 라우팅할 수 없는 모델입니다. `GET /v1/models`로 모델 목록을 확인하세요.            |
| `429` | `rate_limit_exceeded`                | 계정 또는 무료 모델 한도에 도달했습니다. `retry_after_seconds`만큼 기다리세요.                   |

```json
{
  "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`가 있다고 보장하지 않으니 상태와 코드를 사용하세요. [오류](/errors#text-endpoints)를 참고하세요.

```json
{
  "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                     | 계열                                              | 컨텍스트(토큰)  | 최대 출력(토큰) | 입력, 1M 토큰당 USD | 출력, 1M 토큰당 USD | 프로토콜                                               |
| ------------------------- | ----------------------------------------------- | --------- | --------- | -------------- | -------------- | -------------------------------------------------- |
| `gpt-6.1-terra`           | [GPT](/text-api/gpt/responses)                  | 1,050,000 | 128,000   | \$0.40         | \$2.00         | Chat Completions, Responses                        |
| `gpt-6.1-sol`             | [GPT](/text-api/gpt/responses)                  | 1,050,000 | 128,000   | \$0.80         | \$4.00         | Chat Completions, Responses                        |
| `gpt-6-astra`             | [GPT](/text-api/gpt/responses)                  | 1,000,000 | 128,000   | \$4.00         | \$20.00        | Chat Completions, Responses                        |
| `gpt-6-sol`               | [GPT](/text-api/gpt/responses)                  | 1,050,000 | 128,000   | \$0.80         | \$4.00         | Chat Completions, Responses                        |
| `gpt-6-luna`              | [GPT](/text-api/gpt/responses)                  | 1,050,000 | 128,000   | \$0.04         | \$0.20         | Chat Completions, Responses                        |
| `claude-opus-5-5`         | [Claude](/text-api/claude/messages)             | 1,000,000 | 128,000   | \$2.00         | \$10.00        | Messages                                           |
| `claude-sonnet-5-5`       | [Claude](/text-api/claude/messages)             | 1,000,000 | 128,000   | \$1.00         | \$5.00         | Messages                                           |
| `claude-haiku-5-5`        | [Claude](/text-api/claude/messages)             | 1,000,000 | 128,000   | \$0.05         | \$0.25         | Messages                                           |
| `claude-fable-5-2`        | [Claude](/text-api/claude/messages)             | 1,000,000 | 128,000   | \$4.00         | \$20.00        | Messages                                           |
| `claude-fable-5-1`        | [Claude](/text-api/claude/messages)             | 1,000,000 | 128,000   | \$5.00         | \$25.00        | Messages                                           |
| `gemini-4-argon`          | [Gemini](/text-api/gemini/chat-completions)     | —         | 1,000,000 | \$1.00         | \$5.00         | Chat Completions, Responses, Messages, Gemini 네이티브 |
| `gemini-4-carbon`         | [Gemini](/text-api/gemini/chat-completions)     | —         | 1,000,000 | \$1.00         | \$5.00         | Chat Completions, Responses, Messages, Gemini 네이티브 |
| `gemini-3.8-flash`        | [Gemini](/text-api/gemini/chat-completions)     | —         | —         | \$0.375        | \$1.875        | Chat Completions, Responses, Messages, Gemini 네이티브 |
| `gemini-3.1-pro-preview`  | [Gemini](/text-api/gemini/chat-completions)     | 1,048,576 | 65,536    | \$1.00         | \$6.00         | Chat Completions, Responses, Messages, Gemini 네이티브 |
| `grok-4.7`                | [Grok](/text-api/grok/chat-completions)         | 500,000   | —         | \$0.70         | \$2.10         | Chat Completions, Responses, Messages              |
| `deepseek-v4.1-flash`     | [DeepSeek](/text-api/deepseek/chat-completions) | —         | —         | \$0.075        | \$0.30         | Chat Completions, Responses, Messages              |
| `deepseek-v4-pro-0813`    | [DeepSeek](/text-api/deepseek/chat-completions) | 1,000,000 | 128,000   | \$0.33         | \$0.99         | Chat Completions, Responses, Messages              |
| `deepseek-v4.1-flash-hc`  | [DeepSeek](/text-api/deepseek/chat-completions) | —         | —         | \$0.105\*      | \$0.42\*       | Chat Completions, Responses, Messages              |
| `deepseek-v4-pro-0813-hc` | [DeepSeek](/text-api/deepseek/chat-completions) | 1,000,000 | 128,000   | \$0.462\*      | \$1.386\*      | Chat Completions, Responses, Messages              |
| `glm-5.3`                 | [GLM](/text-api/glm/chat-completions)           | 1,000,000 | 128,000   | \$0.56         | \$1.76         | Chat Completions, Responses, Messages              |
| `glm-5.3-flash`           | [GLM](/text-api/glm/chat-completions)           | 1,000,000 | 128,000   | \$0.06         | \$0.20         | Chat Completions, Responses, Messages              |
| `glm-5.3-flashx`          | [GLM](/text-api/glm/chat-completions)           | 1,000,000 | 128,000   | \$0.148        | \$0.50         | Chat Completions, Responses, Messages              |
| `qwen3.8-max`             | [Qwen](/text-api/qwen/chat-completions)         | 1,000,000 | 128,000   | \$0.80         | \$2.40         | Chat Completions, Responses, Messages              |
| `qwen3.8-flash`           | [Qwen](/text-api/qwen/chat-completions)         | —         | —         | \$0.06         | \$0.188        | Chat Completions, Responses, Messages              |
| `kimi-k3.1-pro`           | [Kimi](/text-api/kimi/chat-completions)         | 1,048,576 | —         | \$0.80         | \$4.00         | Chat Completions, Responses, Messages              |
| `kimi-k3`                 | [Kimi](/text-api/kimi/chat-completions)         | 1,048,576 | 128,000   | \$1.20         | \$6.00         | Chat Completions, Responses, Messages              |
| `MiniMax-M3`              | [MiniMax](/text-api/minimax/chat-completions)   | 1,048,576 | 128,000   | \$0.12         | \$0.48         | Chat Completions, Responses, Messages              |
| `MiniMax-M3.1-Flash`      | [MiniMax](/text-api/minimax/chat-completions)   | 1,000,000 | —         | \$0.06         | \$0.24         | Chat Completions, Responses, Messages              |
| `mimo-v2.6-flash`         | [MiMo](/text-api/mimo/chat-completions)         | 1,048,576 | 128,000   | \$0.056        | \$0.112        | Chat Completions, Responses, Messages              |
| `mimo-v2.5`               | [MiMo](/text-api/mimo/chat-completions)         | 1,048,576 | 128,000   | \$0.056        | \$0.112        | Chat Completions, Responses, Messages              |
| `hy4-preview`             | [Hunyuan](/text-api/hunyuan/chat-completions)   | —         | —         | \$0.3336       | \$1.0004       | Chat Completions, Responses, Messages              |
| `hy3`                     | [Hunyuan](/text-api/hunyuan/chat-completions)   | 256,000   | 64,000    | \$0.033\*      | \$0.132\*      | Chat Completions, Responses, Messages              |
| `muse-wonder`             | [Muse](/text-api/muse/chat-completions)         | 1,048,576 | 131,072   | \$4.00         | \$20.00        | Chat Completions, Responses, Messages              |

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

## 무료 모델

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

| 모델 ID                      | 계열       | 유료 버전                 | 가격 |
| -------------------------- | -------- | --------------------- | -- |
| `deepseek-v4.1-flash-free` | DeepSeek | `deepseek-v4.1-flash` | 무료 |
| `glm-5.3-flash-free`       | GLM      | `glm-5.3-flash`       | 무료 |
| `hy4-free`                 | Hunyuan  | `hy4-preview`         | 무료 |

## 레거시 모델

계속 동작하는 이전 모델 ID는 [레거시 모델](/text-api/legacy-models)에 전환할 현재 모델과 함께 나와 있습니다.