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

# コストの最適化

> BeatAPI の利用額がどこで発生するかと、効果の大きい順にコストを抑える方法を説明します。

# コストの最適化

「安いモデルを使う」が最適な方法とは限りません。このページでは、通常、請求額への効果が大きい方法から順に説明します。

## 1. 出力に上限を設ける

ほぼすべてのモデルで、出力トークンの単価は入力トークンの数倍です。上限を指定しない限り、出力の長さはモデルが決めます。

```json
{ "model": "claude-sonnet-5", "max_tokens": 800, "messages": [...] }
```

短い回答が目的の抽出、分類、ルーティングでは、出力上限だけでほとんど負担なくコストを抑えられます。出力が切れた場合は気付きやすい一方、上限がない場合は、気付かないまま料金が増えます。

## 2. 処理ごとにモデルを使い分ける

多くのパイプラインでは、最高性能のモデルが本当に必要な処理は一部だけです。ルーティング、意図の検出、タグ付け、書式の変更は、低価格帯のモデルでも十分に処理できます。

```python
def model_for(step):
    if step in ("route", "classify", "extract"):
        return "glm-5.3-flash"
    if step == "draft":
        return "claude-sonnet-5"
    return "claude-fable-5-1"
```

低価格帯で処理できる工程は実行頻度も高いため、通常、単にモデルを 1 つ置き換えるより、この分割のほうが大きく料金を減らせます。

## 3. 共通の先頭部分を再利用してキャッシュを活用する

キャッシュ済み入力の料金は新しい入力より大幅に低く設定されています。システムプロンプトや文書の共通部分をリクエストの**先頭**に配置し、呼び出し間でバイト単位まで同一に保つと、キャッシュを利用できます。

先頭部分にタイムスタンプ、リクエスト ID、順番の変わるリストを入れると、キャッシュが効きません。変わる情報は末尾に置いてください。

## 4. 料金が変わるモデルを把握する

見落としやすい条件で料金が高くなるシリーズがあります。

* **ピーク時間帯。** 2 つの DeepSeek HC（高キャッシュ）モデルは、平日の北京時間 09:00–12:00 と 14:00–18:00 に料金が 2 倍になります。通常の有料 DeepSeek モデルは時間帯を問わず同じ料金です。Hunyuan `hy3` には毎日の独自の時間帯があります。夜間なら安いバッチも、火曜日の 10:00 に実行すると同じ料金では済みません。
* **コンテキストの段階料金。** GPT-5.6 と Grok の各シリーズでは、所定のコンテキスト長を超えると単価が上がります。長いエージェントセッションでは、クライアントに通知されないまま境界を超える場合があります。

正確な時間帯と境界値は[料金ページ](https://beatapi.io/pricing)の注記に記載しています。各レスポンスの利用記録で、適用された料金を確認できます。ピーク時間帯を避けるバッチ実行は、cron 式を 1 つ変更するだけで対応できます。

## 5. 送信するコンテキストを減らす

会話のコンテキストには、最初の 1 回だけでなく、各ターンで課金されます。特に重要な習慣は 2 つです。

* **履歴を削減します。** 40 ターン目に会話全体を送ると、1 ターン目の内容に 40 回分の料金を払うことになります。要約するか、直近の範囲に限定してください。
* **ファイル全体ではなく選択範囲を送ります。** コーディングツールでは特に効果があります。[Cursor](/integrations/cursor) と [Cline](/integrations/cline) は、設定次第で開いているバッファーを送信します。

## 6. ストリーミングで途中停止を可能にする

`stream: true` は、最後まで生成した場合の料金を変えません。ただし、意図と違う応答を数百トークンの時点で止められるため、全出力分を払わずに済みます。応答も速く感じられるので、コストに関係なく取り入れる価値があります。

## 7. 最適化の前に計測する

アプリケーション、ツール、環境ごとに専用の API キーを割り当てます。`GET /v1/usage` の `by_api_key` で独自の計測実装なしに利用額を区別でき、`by_model` で実際に料金が発生しているモデルを確認できます。

```bash
curl https://api.beatapi.io/v1/usage \
  -H "Authorization: Bearer $BEATAPI_API_KEY"
```

どの連携に費用がかかっているかは、推測だけでは判断しにくいものです。小さな呼び出しを何千回も行うブラウザーの翻訳拡張と、非常に大きい呼び出しを数回行うエージェントでは、請求の内訳がまったく違います。

## 8. 返金を照合する

失敗したタスクは返金されます。仮確保だけを記録し、返金を取り込まないと、内部の利用額を過大に計上し、実態と違う数値に基づいて最適化することになります。このため `GET /v1/usage` は `credits_settled` と `credits_refunded` を別々に返します。

## 効果のない方法

* **過剰な再試行。** `400` を再試行しても、同じ不正なリクエストを同じ料金で送るだけです。再試行は `429` と `5xx` に限定してください。[開発ガイド](/development)を参照してください。
* **ポーリング間隔を短くする。** ポーリングは残高ではなくリクエスト数の上限に計上されます。頻繁にタスクを確認しても、処理は速くならず `429` が増えるだけです。
* **モデルの性能を落として再実行が必要になる。** 安いモデルの出力を再実行したり、高価なモデルで修正したりすると、最初から適切に処理するより高くなる場合があります。単価ではなく、パイプライン全体を計測してください。