💸 Cloudflare AI Gateway「Spend Limits」を解剖する — AIの権限委任をドル建て予算で設計する

検証日: 2026-06-06 / 対象: Cloudflare AI Gateway の Spend Limits（ドル建て予算制御）と ID 連動ポリシー
ステータス: Spend Limits は 2026-06-05 発表の open beta（GA ではありません）。本記事はこの時点の一次情報に基づきます。

AIエージェントに仕事を任せるとは、突き詰めると「お金を使う権限を任せる」ことです。エージェントが自律的にモデルを呼び続ければ、その分だけ請求が積み上がります。ところが従来の制御は「トークン数の上限」や「1分あたりのリクエスト数」が中心で、これは 使用量 の制御であって 支出 の制御ではありませんでした。

Cloudflare が 2026-06-05 に AI Gateway へ追加した Spend Limits は、この軸を「ドル建ての累積コスト予算」へ移します。「このチームに $2,000/月」「このユーザーに $500/月」とゲートウェイ層で宣言し、予算に達したらリクエストを止めるか、安価なモデルへ逃がします。本記事では、この機能を実装エンジニアの視点で構造・データ・設定・運用まで解剖し、open beta ゆえの限界と OSS 代替まで含めて、コスト責任をどう委任設計するかを整理します。

概要

Spend Limits は、LLM リクエストの前段に立つ AI Gateway に「コストベースの予算ルール」を持たせる機能です。model / provider / custom metadata 単位で予算を宣言し、累積コストがしきい値に達した時点でブロック、またはより安価なモデルへフォールバックします。

ポイントは、これが単なる料金キャップではなく 権限委任の道具である点です。アプリ側でトークンを数える実装を持たなくても、ゲートウェイで「誰にいくらまで」を宣言できます。AIエージェントへの権限委任を、費用面の責任分界としてアプリの外側で受け止められます。

一方で限界も明確です。

• コスト判定は実請求ではなく estimation（推計） です。
• ユーザー/チームの識別は 自己申告の metadata に依存し、検証がありません。
• 検証済み ID 連動（Cloudflare Access）は closed beta です。
• Terraform 未対応で IaC 宣言管理ができません。

OSS の LiteLLM は同等の予算制御を GA かつ self-host で提供します。「マネージドを取るか自前を取るか」は依然として設計判断です。

特徴

トークンでなくドルで予算を切る

予算は USD 建ての累積コストで設定します（API パラメータ limitType = "cost"）。請求額そのものを制御する点が、トークン上限やレート制限との違いです。

超過時に「止める」か「逃がす」かを選べる

「予算超過 → 安価モデルへ自動迂回」を予算機能としてネイティブに持つ点が、他社に対して先行する特徴です。調査した範囲では、他社のフォールバックは主に障害時のルーティングか常時のコスト最適化が中心で、予算しきい値をトリガーにしたものは目立ちません。

コストはリアルタイムに推計する

ID 連動は専用機能でなく metadata の次元

per-user / per-team の予算は、専用の budget エンティティではなく cf-aig-metadata で送る custom metadata（例: user_id, team）を split / filter 軸にして実現します。

「チーム/ユーザー単位で統制する」という主張の中核を、open beta 段階では検証なしの metadata が担います。本番運用ではこの点を正面から評価する必要があります。

設定インターフェースと料金

• 設定は Dashboard と REST API。REST は gateway リソースのボディに spend_limits を含めます。
• Terraform は spend_limits 属性が未公開で、IaC 宣言管理ができません（#6720 open）。
• AI Gateway 本体も Spend Limits も 全プラン追加料金なしです。

構造

システムコンテキスト図

コンテナ図

コンポーネント図

データ

概念モデル

情報モデル

REST API（Create Gateway）の確定スキーマでは、window は秒数の number、metadata はキー名をキーにした map で各値が {mode:"partition"} または {mode:"filter", values:[...]}、model / provider は {mode:"filter", values:[...]} のオブジェクトです。features ドキュメント本文では概念名として「Split by value」「Filter by value」と呼びますが、API の mode 値は partition / filter です。

主要エンティティの属性を示します。

データ上の重要制約

構築方法

Gateway 作成

Dashboard では AI > AI Gateway > Create Gateway で名前を入力して作成します。REST API では次のように作成します。

curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai-gateway/gateways" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "prod-gateway",
    "cache_invalidate_on_update": false,
    "cache_ttl": 0,
    "collect_logs": true,
    "rate_limiting_interval": 0,
    "rate_limiting_limit": 0
  }'

Create Gateway の必須フィールドは id / cache_invalidate_on_update / cache_ttl / collect_logs / rate_limiting_interval / rate_limiting_limit です。spend_limits は optional です。

Spend Limit ルール設定

Spend Limits は gateway の作成・更新ボディに spend_limits オブジェクトを含めて設定します。window は秒数の number、metadata はキー名をキーにした map、model / provider はオブジェクトです。1 gateway あたり最大 20 ルールです。

ゲートウェイ全体に $10,000/day の上限（ブロック）を設定する例です。

{
  "spend_limits": {
    "enabled": true,
    "rules": [
      {
        "limit": 10000,
        "limitType": "cost",
        "window": 86400,
        "technique": "fixed"
      }
    ]
  }
}

ユーザーごとに $200/day を割り当てる例です。metadata の partition で値ごとに独立した予算バケットが生成されます。

{
  "spend_limits": {
    "enabled": true,
    "rules": [
      {
        "limit": 200,
        "limitType": "cost",
        "window": 86400,
        "technique": "fixed",
        "metadata": { "user_id": { "mode": "partition" } }
      }
    ]
  }
}

engineering チームのみ・特定モデル限定で $50/day を設定する例です。filter で対象を絞り込みます。

{
  "spend_limits": {
    "enabled": true,
    "rules": [
      {
        "limit": 50,
        "limitType": "cost",
        "window": 86400,
        "technique": "fixed",
        "provider": { "mode": "filter", "values": ["openai"] },
        "model": { "mode": "filter", "values": ["openai/gpt-4.1"] },
        "metadata": { "team": { "mode": "filter", "values": ["engineering"] } }
      }
    ]
  }
}

認証と Terraform 制約

Gateway 管理には AI Gateway 編集権限を持つ Cloudflare API トークンが必要です。LLM リクエストを Authenticated Gateway 経由で送る場合は、別途 Gateway 専用トークン（cf-aig-authorization）が必要です。

Terraform は cloudflare_ai_gateway リソースで Gateway 本体を作れますが、spend_limits 属性は 2026-06 時点で未公開です。予算ルールは REST API か Dashboard での別途設定になります。

resource "cloudflare_ai_gateway" "prod" {
  account_id             = var.cloudflare_account_id
  id                     = "prod-gateway"
  cache_ttl              = 0
  collect_logs           = true
  rate_limiting_interval = 0
  rate_limiting_limit    = 0
  # spend_limits は未対応のため REST API / Dashboard で設定する
}

利用方法

Gateway 経由で LLM を呼ぶ

provider-native エンドポイントの形式は次のとおりです。

https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/{provider}/...

OpenAI を直接呼ぶ例です。

curl -X POST "https://gateway.ai.cloudflare.com/v1/$CLOUDFLARE_ACCOUNT_ID/prod-gateway/openai/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

ヘッダの使い方

ユーザー/チームを識別する cf-aig-metadata を付与します。最大 5 エントリ、値は string / number / boolean です。

curl -X POST "https://gateway.ai.cloudflare.com/v1/$CLOUDFLARE_ACCOUNT_ID/prod-gateway/openai/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H 'cf-aig-metadata: {"user_id": "u_12345", "team": "engineering", "env": "prod"}' \
  -d '{"model": "gpt-4.1", "messages": [{"role": "user", "content": "What should I build today?"}]}'

OpenAI SDK（TypeScript）からは次のように渡します。

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: `https://gateway.ai.cloudflare.com/v1/${process.env.CLOUDFLARE_ACCOUNT_ID}/prod-gateway/openai`,
});

const response = await client.chat.completions.create(
  { model: "gpt-4.1", messages: [{ role: "user", content: "Hello!" }] },
  { headers: { "cf-aig-metadata": JSON.stringify({ user_id: "u_12345", team: "engineering" }) } }
);

交渉済みレートや内部配賦には cf-aig-custom-cost で単価を上書きします。

curl -X POST "https://gateway.ai.cloudflare.com/v1/$CLOUDFLARE_ACCOUNT_ID/prod-gateway/openai/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H 'cf-aig-custom-cost: {"per_token_in": 0.000001, "per_token_out": 0.000002}' \
  -d '{"model": "gpt-4.1-mini", "messages": [{"role": "user", "content": "Hello!"}]}'

キャッシュヒット時はコスト0扱いになるため、cf-aig-custom-cost はプロバイダへ実際に転送された場合のみ適用されます。

超過時の挙動

予算超過時のデフォルトは HTTP 429 でのブロックです。time window がリセットされるまで継続します。

HTTP/2 429
{ "success": false, "errors": [{"message": "Spend limit exceeded"}] }

コストはリクエスト完了後に計上されるため、同時バーストでは一時的に上限を超過することがあります。ハードキャップとして 100% 保証されるものではありません。

Budget Limit ノードで安価モデルへ逃がす

ブロックでなく安価モデルへ自動フォールバックさせる構成です。

1. Dynamic Route で primary モデル（高品質）と fallback モデル（安価）を定義します。
2. primary モデルに Spend Limit を設定します。
3. 予算超過時、AI Gateway が自動で fallback モデルへルーティングします。

[リクエスト]
    ↓
[Budget Limit チェック]
    ├── 予算内  → Primary 高品質モデル
    └── 予算超過 → Fallback 安価モデル

Dynamic Routing 自体の設定 schema（Rate / Budget Limit 要素など）は docs に掲載がありますが、これは Spend Limits の gateway ルールとは別系統です。両者を組み合わせる構成は Dashboard 経由が確実です。

ID 連動ポリシー

closed beta のセットアップ手順・metadata キー名は 2026-06 時点で公開 docs に未記載です（要再検証）。

運用

予算設計パターン

スコープ次元は model / provider / custom metadata の 3 軸です。専用のチーム予算エンティティは存在せず、cf-aig-metadata の key-value を split / filter 軸にして表現します。

1 gateway 最大 20 ルール、cf-aig-metadata は 1 リクエスト最大 5 エントリの制約があります。環境分離が必要なら gateway 自体を複数作成します（Free: 10 / Paid: 20 per account）。まず 1 gateway + metadata split で試し、アクセス境界が必要になってから gateway 分割を検討する順序が現実的です。

block と fallback の使い分け

fallback は AI Gateway 自体がダウンした場合には機能しません。Budget Limit ノードは Gateway 内の機能であり、Gateway 障害時は両方とも止まる単一障害点です。

監視

cost は estimation のため、プロバイダ dashboard と併用します。AI Gateway はネイティブのアラート機能を持たないため、Logpush → Datadog/Grafana で「予算 80% 到達通知」を作るか、Analytics API のポーリングで代替します。

account-wide と per-gateway の2層管理

Layer 1: Account-wide Unified Billing クレジット
  └─ 全 gateway 横断の総支出キャップ

Layer 2: Per-gateway Spend Limit Rules
  ├─ Gateway production: $20,000 / month
  ├─ Gateway staging:    $1,000 / month
  └─ Gateway development: $500 / month
       └─ metadata.team=alpha: $200 / day

BYOK では account-wide の Unified Billing クレジットが存在しないため、per-gateway ルールのみで管理します。BYOK でも known pricing モデルならコスト計算は行われ、Spend Limits は機能します。

ベストプラクティス

estimation 誤差を見越したバッファ設定

「$500 に設定すれば請求も正確に $500 で止まる」と考えると外します。公式 Costs docs が "cost metric is an estimation" と自認し、ストリーミングで計上漏れの事例（#470 open）があります。

予算上限は実際に使わせたい金額の 70〜80% に設定し、20〜30% のバッファを持ちます。確定請求はプロバイダ dashboard で毎日確認します。ストリーミング多用ならプロバイダ側のトークンカウントを正とします。

ストリーミング多用時の上限突き抜け対策

ストリーミングのコストは応答完了後にしか確定せず、最終チャンクの usage を読めないと加算されません。長時間ストリーミングの並行で、上限を超えた後続リクエストが通る余地があります。

Spend Limits を最終防衛線でなく補助防衛線とし、プロバイダ側に daily token quota を併設します。OpenAI 系では stream_options: {include_usage: true} を明示して usage 返却を促します。

なりすまし対策

cf-aig-metadata: {"user_id":"alice"} を送れば Alice のクォータで制限できると考えると危険です。metadata はクライアントの自己申告で検証の記述がありません。未信頼のクライアントが直接 cf-aig-metadata を指定できる構成では、user_id を詐称して他人の予算消費や自分の上限回避を行える余地があります（CVE ではなく仕様設計からの論理的リスク）。

止めない統制の設計

Phase 1 通常時: 高品質モデル / 予算 $10,000/月
  └─ Phase 2 超過 fallback: 安価モデル コストを 1/5 程度に圧縮
       └─ Phase 3 全体ハードキャップ到達: HTTP 429 でブロック

Dynamic Route の Budget Limit ノードで Phase 1→2 を実装し、account-wide 上限で Phase 3 を受け止めます。

自前 LiteLLM とマネージド Cloudflare の選択指針

素早く始めたい・インフラ管理を避けたい・fallback の段階制御が欲しいなら Cloudflare が向きます。厳密な ID 検証・細粒度のキー単位予算・IaC 完全再現性・self-host が必要なら LiteLLM が向きます。高スケールで TCO を最小化したい場合も LiteLLM self-host が有利です。

トラブルシューティング

コストが実請求とズレる

予算が効かない / 突き抜ける

429 が返る / fallback が動かない

まとめ

Cloudflare AI Gateway の Spend Limits は、AI のコスト制御を「トークン/レート」から「ドル建て予算」へ移し、超過時に止めるか安価モデルへ逃がすかを選べる機能です。AIエージェントやチームへの権限委任を、コスト責任の委任としてゲートウェイ層で受け止められます。ただし 2026-06 時点では open beta で、コストは推計・ID は自己申告・Terraform 未対応という限界があり、本番では LiteLLM 等の自前運用との比較を含めた設計判断が必要です。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります！

参考リンク

• 公式ドキュメント
  • Spend Limits
  • Spend Limits changelog (2026-06-05)
  • AI Gateway 概要
  • Dynamic Routing
  • Authenticated Gateway
  • Custom Metadata
  • Custom Costs
  • Unified Billing
  • Costs
  • Analytics
  • Limits
  • REST API Create Gateway
• 発表・背景
  • Cloudflare Blog: Introducing Spend Limits for AI Gateway
• GitHub
  • cloudflare/ai#470 ストリーミングコスト未記録
  • cloudflare-docs#20536 Anthropic usage パース失敗
  • terraform-provider-cloudflare#6720 spend_limits 未対応
• 代替
  • LiteLLM: Budgets & Rate Limits
  • LiteLLM: Budget Manager