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

# 무료 모델

> 토큰당 요금 없이 호출할 수 있는 텍스트 모델, 구분하는 방법, 호출할 수 있는 대상, 한도를 설명합니다.

# 무료 모델

`-free`로 끝나는 모델 ID는 무료이며 토큰당 가격이 없습니다. 모든 무료 모델은 유료 버전과 별개의 ID이므로 `-free`에 정확한 ID를 보내세요.

* 무료 텍스트 모델은 아래 세 가지입니다. 이미지, 영상, 의사 결정(JEV) 모델에는 무료 ID가 없으며, 무료 JEV ID는 2026-11-05에 종료되었습니다.
* 키의 그룹이 무료 그룹에 접근할 수 있다면 어떤 키로든 호출할 수 있습니다. 기본 `auto` 그룹도 포함되며, 잔액이 0이거나 아직 충전한 적이 없어도 됩니다.
* 계정마다 첫 충전 전에는 분당 성공 요청 1건, 충전 후에는 분당 최대 10건으로 제한됩니다.
* 무료 모델은 언제든지 속도가 제한되거나 제공이 중단될 수 있습니다. 무료 모델에 의존하는 프로덕션 경로를 만들지 마세요.

## 모델 ID

공개 카탈로그에 있는 목록입니다(`GET /v1/text/models`, 계열 `free`).

| 무료 모델 ID                                                          | 유료 버전                 | 계열 페이지                                          |
| ----------------------------------------------------------------- | --------------------- | ----------------------------------------------- |
| [`glm-5.3-flash-free`](/text-api/glm/chat-completions)            | `glm-5.3-flash`       | [GLM](/text-api/glm/chat-completions)           |
| [`deepseek-v4.1-flash-free`](/text-api/deepseek/chat-completions) | `deepseek-v4.1-flash` | [DeepSeek](/text-api/deepseek/chat-completions) |
| [`hy4-free`](/text-api/hunyuan/chat-completions)                  | `hy4-preview`         | [Hunyuan](/text-api/hunyuan/chat-completions)   |

유료 버전의 ID를 보내면 별도로 과금되는 요청이 됩니다.

## 호출할 수 있는 대상

* 그룹이 무료 그룹에 접근할 수 있는 유효한 키라면 누구나 호출할 수 있습니다. 기본 `auto` 그룹의 키도 가능합니다.
* 잔액이 0이어도, 한 번도 충전하지 않은 계정이어도 됩니다.
* 응답의 `model` 필드에는 `-free` 이름이 들어갑니다.

무료 크레딧 계정은 무료 등급 목록에 있는 모델만 호출할 수 있으며, 무료 ID는 이 목록에 포함되어 있습니다. `GET /v1/free-tier`는 키 없이 이 목록을 반환합니다. 충전하면 제한이 풀립니다.

## 한도

| 계정 상태  | 분당 성공 요청 수 |
| ------ | ---------- |
| 첫 충전 전 | 1          |
| 충전 후   | 최대 10      |

* 한도는 성공한 요청 수로 계산합니다. 실패한 요청이나 실패한 스트림은 자리를 반환합니다. 동시에 실행되는 호출 수가 아니라 호출 빈도를 제한합니다.
* 무료 호출은 유료 한도와 따로 계산되므로 유료 한도를 쓰지 않으며, 유료 호출도 무료 한도를 쓰지 않습니다.
* 해당 분의 계정 일반 한도를 모두 사용했다면 무료 모델도 거부될 수 있습니다.

한도에 도달하면 `Retry-After` 헤더, `retry_after_seconds`와 함께 `429 rate_limit_exceeded`가 반환됩니다. 그만큼 기다린 뒤 재시도하세요. 메시지에는 해당 한도가 표시됩니다. 한 번도 충전하지 않은 계정에서는 정확히 다음 문장이 반환됩니다.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded: this model allows at most 1 successful requests per minute per account. Retry after 60 seconds. Accounts that have topped up get a higher per-minute limit.",
    "retryable": true,
    "request_id": "req_abc123",
    "retry_after_seconds": 60
  }
}
```

충전 후에는 메시지가 `at most 10 successful requests per minute`로 바뀌고 마지막 문장이 빠집니다. 일반 계정 한도와 같은 코드이므로 메시지로 구분하세요. `Retry-After` / `retry_after_seconds`에 표시된 초만큼 기다린 뒤 재시도하세요. [오류](/errors#text-endpoints)를 참고하세요.

## 유료 모델과의 차이

* **컨텍스트나 출력 한도가 공개되어 있지 않습니다.** 카탈로그의 무료 항목에는 컨텍스트 윈도, 출력 한도, 가격이 없습니다. 유료 버전의 컨텍스트 윈도와 출력 한도가 무료 ID에도 보장되지는 않습니다.
* **추론이 보장되지 않습니다.** `thinking`, `reasoning_effort`처럼 유료 모델 전용 옵션은 유료 모델과 다르게 동작할 수 있습니다.
* **형식이 다를 수 있습니다.** 예를 들어 `glm-5.3-flash-free`는 `/v1/responses`를 지원하지 않습니다. Chat Completions 외의 형식을 쓰기 전에 계열 페이지를 확인하세요.
* **추론이 출력 예산을 사용할 수 있습니다.** `hy4-free`는 답하기 전에 추론하며, 추론은 `max_tokens`에 포함됩니다. 세 단어짜리 답변에 추론 토큰이 약 1,000개 쓰였고, `max_tokens`를 300으로 두었을 때는 빈 답변이 돌아왔습니다. `max_tokens`(Responses에서는 `max_output_tokens`)를 2000 이상으로 보내세요.
* **속도와 가용성이 다를 수 있습니다.** 무료 모델은 더 느리거나, 속도가 제한되거나, 예고 없이 중단될 수 있으며, 일일 사용량도 보장되지 않습니다.
* **캐시 입력 가격이 없습니다.** 무료 ID는 토큰 단위로 전혀 과금되지 않습니다.

## 사용해 보기

**`cURL`**

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

## 이미지와 영상

무료 이미지·영상 모델은 없습니다. 이 모델들은 작업 단위로 과금됩니다. [빠른 시작](/quick-guide)을 참고하세요.