# Count tokens

> POST /messages/count_tokens のリファレンスです。リクエストフィールド、input_tokens レスポンス、クライアントが推定値を使うための 404、課金されない理由を説明します。

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

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

レスポンスを生成せずに、Messages リクエストの入力トークン数を数えます。ゲートウェイはリクエストを Messages リクエストと同じ方法で変換し、モデルサーバーのトークナイザーに問い合わせます。推論は実行されないため、このリクエストは課金されません。

## 認証

ゲートウェイが処理するエンドポイントの認証方法はすべて同じで、 [API リファレンス](https://kiln.bricksum.com/docs/ja/api-reference) ページで説明しています。

## リクエストボディ

| ステータス | 説明 |
| --- | --- |
| 対応 | ゲートウェイが処理するか、公開済みの実測で動作を確認した項目です。 |
| 転送のみ | モデルサーバーに転送されます。Kiln は動作を検証していません。 |
| 無視 | 200 で受け付けられますが、適用されません。レスポンスのその他の部分は通常どおりです。 |
| 非対応 | エラーで拒否されるか、説明に記載したモデルでは動作しません。 |

### 共通パラメータ

以下のパラメータの定義は [API リファレンス](https://kiln.bricksum.com/docs/ja/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/ja/api-reference) ページに一度だけ記載しています。

認証、クレジット、予算、レート制限（1 分あたりのリクエスト数、トークン数）のエラーは、Anthropic 形式への変換より前にゲートウェイが返します。ボディは Anthropic の形式ではありません。

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

すべてのステータスコードは [エラー](https://kiln.bricksum.com/docs/ja/errors) ページにあります。

## 制限

- 課金：課金されません。ゲートウェイはこのエンドポイントの usage イベントを発行せず、レスポンスに X-Neocloud-Generation-Id ヘッダーはありません。
- Claude Code では任意です。このエンドポイントが 404 で応答した場合、Claude Code は独自の推定値を使用し、/context には概算値が表示されます。

コンテキスト長、リクエストボディのサイズ、タイムアウト、組織ごとのレート制限もここに適用され、 [API リファレンス](https://kiln.bricksum.com/docs/ja/api-reference) ページに一度だけ記載しています。

429 のヘッダーと再試行の方法は [レート制限](https://kiln.bricksum.com/docs/ja/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"
  }
}
```