# 使用量と課金

> usage オブジェクトと usage.cost、コストの計算方法、リクエスト ID ヘッダー、キーの確認、課金対象。

Source: https://kiln.bricksum.com/docs/ja/usage-billing

料金は事前にチャージした USD クレジットから差し引かれます。すべてのレスポンスで、そのリクエストの正確なコストを確認できます。usage オブジェクトにトークン数が入り、ゲートウェイが USD のコストを追加します。このページでは、usage オブジェクト、コストの計算方法、リクエスト ID ヘッダー、課金対象と対象外を説明します。

## usage オブジェクト

非ストリーミングのレスポンスは、本文に OpenAI 形式の usage を含みます。含まれるのは、prompt_tokens・completion_tokens・total_tokens、モデルサーバーがプロンプトの一部をプレフィックスキャッシュから提供した場合の prompt_tokens_details.cached_tokens（より低いキャッシュ入力単価で課金）、モデルが推論を報告する場合の completion_tokens_details.reasoning_tokens（completion_tokens に含まれ、出力として課金）です。これに加えて、cost フィールドが 1 つ追加されています。cost はこのリクエストでクレジットから差し引かれた USD 金額で、モデルではなくゲートウェイが追加します。

ストリームでは stream_options.include_usage を設定すると、同じオブジェクトが最終チャンクに含まれます。 [ストリーミング](https://kiln.bricksum.com/docs/ja/streaming) を参照してください。

**200 OK**
```json
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "qwen3-32b",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello! How can I help?" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21,
    "cost": 0.000001155
  }
}
```

この例のトークン数と cost は gpt-oss-120b で測定した例示の値で、qwen3-32b の値ではありません。

## コストの計算方法

コストは、リクエスト時点のモデルのトークン単価を使った 3 項の合計です。キャッシュされたプロンプトトークンは prompt_tokens の一部で、入力単価の代わりにキャッシュ入力単価が適用されます。

**USD**
```text
cost = (prompt_tokens - cached_tokens) x input price
     + cached_tokens                  x cached-input price
     + completion_tokens              x output price
```

各モデルの 100 万トークンあたりの単価は [モデルカタログ](https://kiln.bricksum.com/models) にあります。カタログ API は price_input_per_m、price_cached_input_per_m、price_output_per_m として返します。単価は USD で、VAT は含まれません。

## リクエスト ID ヘッダー

計測されたすべてのレスポンスには `X-Neocloud-Generation-Id` ヘッダーが含まれます。値はそのリクエストの使用量イベント ID です。リクエストのログと一緒に保存し、請求やエラーについて問い合わせるときにこの値を添えてください。

## キーの確認

キー自体で認証する GET /v1/key は、そのキーのプロジェクト、ステータス、支出上限、有効期限、これまでの支出額を返します。チームメンバーは、コンソールにアクセスしなくても自分のキーを確認できます。平文のキーは返されません。無効・停止・期限切れのキーはすべて 401 です。

**curl**
```bash
curl https://api.bricksum.com/v1/key \
  -H "Authorization: Bearer sk-bk-..."
```

**200 OK**
```json
{
  "id": "key_...",
  "org_id": "org_...",
  "project_id": "proj_...",
  "name": "prod-backend",
  "prefix": "sk-bk-",
  "last4": "a1b2",
  "status": "active",
  "spend_limit_usd": 50,
  "expires_at": null,
  "usage_usd": 12.34,
  "last_used_at": "2026-09-11T07:00:00Z",
  "created_at": "2026-08-01T00:00:00Z"
}
```

## 課金対象

- モデルサーバーに到達したリクエストごとに、使用量イベントが 1 件記録されます。課金はサーバーが報告した usage のトークン数に基づきます。
- モデルに到達する前にゲートウェイが拒否したリクエストは課金されません。ステータスコードと原因は [エラー](https://kiln.bricksum.com/docs/ja/errors) ページにまとめています。
- モデルサーバーがエラーを返すかストリーム途中で失敗した場合、イベントは 0 トークンとして記録され、何も請求されません。
- クライアントがストリーム途中で切断した場合、ゲートウェイは使用量を記録するためにストリームを最後まで読み取り、生成されたトークンは請求されます。

## リクエストが拒否される場合

組織のクレジット残高が 0 以下のとき、組織が月間予算に達したとき、またはキーが支出上限に達したとき、ゲートウェイはモデルを呼び出す前に `402 Payment Required` を返します。このように拒否されたリクエストは課金されません。残高・台帳・有効期限は [クレジットページ](https://kiln.bricksum.com/app/credits) で確認してください。予算、キーの上限、クレジットの有効期限は組織と予算のページで説明します。