# Count tokens

> POST /messages/count_tokens 레퍼런스입니다. 요청 필드, input_tokens 응답, 클라이언트가 추정값을 쓰게 하는 404, 과금되지 않는 이유를 설명합니다.

Source: https://kiln.bricksum.com/docs/ko/api-reference/count-tokens

`POST https://api.bricksum.com/v1/messages/count_tokens`

응답을 생성하지 않고 Messages 요청의 입력 토큰 수를 셉니다. 게이트웨이는 요청을 Messages 요청과 같은 방식으로 변환한 뒤 모델 서버의 토크나이저에 질의합니다. 추론이 실행되지 않으므로 이 요청은 과금되지 않습니다.

## 인증

게이트웨이가 처리하는 엔드포인트의 인증 방식은 모두 같으며, [API 레퍼런스](https://kiln.bricksum.com/docs/ko/api-reference) 페이지에서 설명합니다.

## 요청 본문

| 상태 | 설명 |
| --- | --- |
| 지원 | 게이트웨이가 처리하거나, 공개된 실측에서 동작이 확인된 항목입니다. |
| 전달만 함 | 모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다. |
| 무시됨 | 200으로 수락되지만 적용되지 않습니다. 응답의 나머지는 정상입니다. |
| 미지원 | 에러로 거부되거나, 설명에 적힌 모델에서 동작하지 않습니다. |

### 공통 파라미터

아래 파라미터의 정의는 [API 레퍼런스](https://kiln.bricksum.com/docs/ko/api-reference) 페이지에 한 번만 정리했습니다. 여기에는 이 엔드포인트에서 다른 점만 적었습니다.

| 필드 | 타입 | 필수 | 기본값 | 상태 | 설명 |
| --- | --- | --- | --- | --- | --- |
| `model` | string |  |  | 지원 | 여기서는 선택 사항입니다. 이 필드가 비어 있거나 없으면 게이트웨이에 설정된 기본 모델을 사용합니다. 404는 not_found_error이며, 토크나이저가 토큰 수를 셀 수 없을 때도 같은 상태로 응답합니다. |
| `messages` | array | 필수 |  | 지원 | Messages 엔드포인트와 같은 형식이며 같은 규칙으로 변환되므로, thinking과 document처럼 제거되는 블록은 세지 않습니다. 배열이 비어 있거나 없으면 400(invalid_request_error)으로 거부됩니다. |
| `tools` | array |  |  | 무시됨 | 수락되지만 토크나이저로 보내지 않습니다. 토큰 수에 툴 정의는 포함되지 않습니다. |
| `tool_choice` | object |  |  | 무시됨 | 수락되지만 토크나이저로 보내지 않습니다. thinking, output_config, max_tokens, 샘플링 파라미터도 마찬가지입니다. |

### 이 엔드포인트에만 있는 파라미터

| 필드 | 타입 | 필수 | 기본값 | 상태 | 설명 |
| --- | --- | --- | --- | --- | --- |
| `system` | string \| array |  |  | 지원 | 시스템 프롬프트입니다. 문자열 또는 text 블록 배열로 보냅니다. 대화 맨 앞의 system 메시지로 계산됩니다. |

토크나이저에는 model과 변환된 messages만 전달됩니다. 그 밖의 필드는 제거되며 에러가 발생하지는 않습니다.

## 응답 본문

| 필드 | 타입 | 설명 |
| --- | --- | --- |
| `input_tokens` | integer | 변환된 messages의 토큰 수입니다. 모델 서버의 토크나이저가 chat 템플릿을 적용해 센 값입니다. 응답의 유일한 필드입니다. |

## 에러

인증을 통과한 뒤의 에러는 Anthropic 형식({"type": "error", "error": {"type", "message"}})으로 반환됩니다. 메시지 문구가 아니라 HTTP 상태와 error.type으로 분기하세요. error.type 칸이 비어 있는 행은 요청이 이 엔드포인트에 도달하기 전에 게이트웨이가 반환하는 에러이며, 표 아래에 있는 본문 형식을 사용합니다.

| 상태 | error.type | 원인 | 조치 |
| --- | --- | --- | --- |
| 400 | `invalid_request_error` | 본문이 올바른 JSON이 아니거나, messages가 비어 있거나 없거나, 메시지의 content가 문자열도 블록 배열도 아닙니다. | 요청 본문을 수정하세요. 그대로 재시도하지 마세요. |
| 404 | `not_found_error` | 모델 ID가 카탈로그에 없습니다. | GET /models로 ID를 확인하세요. |
| 404 | `not_found_error` | 이 모델에서는 토큰 수 계산을 사용할 수 없습니다. 모델 백엔드를 선택하지 못했거나, 토크나이저에 연결할 수 없거나 토크나이저가 요청을 거부했거나, 응답에 토큰 수가 없는 경우입니다. 이 엔드포인트는 이런 실패를 5xx가 아닌 404로 응답합니다. | 클라이언트에서 토큰 수를 추정하세요. Claude Code는 자체적으로 추정값을 사용합니다. |
| 405 | `invalid_request_error` | 메서드가 POST가 아닙니다. | POST로 요청하세요. |

401, 402, 403, 429는 요청이 이 엔드포인트에 도달하기 전에 게이트웨이가 반환합니다. 이 에러들은 [API 레퍼런스](https://kiln.bricksum.com/docs/ko/api-reference) 페이지에 한 번만 정리했습니다.

인증, 크레딧, 예산, 레이트 리밋(분당 요청 수, 분당 토큰 수) 에러는 Anthropic 형식으로 변환되기 전에 게이트웨이가 반환합니다. 본문은 Anthropic 형식이 아닙니다.

```json
{
  "error": {
    "message": "invalid API key",
    "type": "authorization"
  }
}
```

전체 상태 코드는 [에러](https://kiln.bricksum.com/docs/ko/errors) 페이지에 있습니다.

## 제한

- 과금: 과금되지 않습니다. 게이트웨이는 이 엔드포인트에 대해 usage 이벤트를 발행하지 않으며, 응답에 X-Neocloud-Generation-Id 헤더가 없습니다.
- Claude Code에서는 선택 사항입니다. 이 엔드포인트가 404로 응답하면 Claude Code는 자체 추정값을 사용하고 /context에는 근사치가 표시됩니다.

컨텍스트 길이, 요청 본문 크기, 타임아웃, 조직별 레이트 리밋도 여기에 그대로 적용되며, [API 레퍼런스](https://kiln.bricksum.com/docs/ko/api-reference) 페이지에 한 번만 정리했습니다.

429의 헤더와 재시도 방법은 [레이트 리밋](https://kiln.bricksum.com/docs/ko/rate-limits) 페이지에 있습니다.

## 예제

### 요청

**cURL**
```bash
curl https://api.bricksum.com/v1/messages/count_tokens \
  -H "x-api-key: $KILN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-32b",
    "system": "Answer briefly.",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'
```

**Python**
```python
import os
from anthropic import Anthropic

# base_url is the API origin without /v1: the SDK appends /v1/messages/count_tokens.
client = Anthropic(
    base_url="https://api.bricksum.com",
    api_key=os.environ["KILN_API_KEY"],
)

count = client.messages.count_tokens(
    model="qwen3-32b",
    system="Answer briefly.",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(count.input_tokens)
```

**TypeScript**
```typescript
import Anthropic from "@anthropic-ai/sdk";

// baseURL is the API origin without /v1: the SDK appends /v1/messages/count_tokens.
const client = new Anthropic({
  baseURL: "https://api.bricksum.com",
  apiKey: process.env.KILN_API_KEY,
});

const count = await client.messages.countTokens({
  model: "qwen3-32b",
  system: "Answer briefly.",
  messages: [{ role: "user", content: "Hello!" }],
});
console.log(count.input_tokens);
```

### 응답

**200 OK**
```json
{
  "input_tokens": 21
}
```

**404 Not Found**
```json
{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "token counting is not available for this model"
  }
}
```