Cloudflare Workers AI の BYOK を設定してみた（Jev を使った例）

この記事でわかること

Cloudflare 経由で他社の AI モデルを使うとき、料金の払い方は2通りあります。

• Cloudflare のクレジットを買って払う（Unified Billing）
• 自分で契約した AI プロバイダーの API キーを Cloudflare に預ける（BYOK）

個人開発で TypeSafe 社のモデル「Jev」（typesafe/jev）を Cloudflare から使うことになり、BYOK を設定しました。この記事では、そのときに調べたことをまとめます。

• BYOK とはなにか
• クレジット払いとの違いと、BYOK のメリット・デメリット
• 設定手順（Cloudflare 側の API トークンも必要 なのがポイント）
• はまりどころ

情報は 2026年10月時点 の Cloudflare 公式ドキュメントにもとづいています。料金や画面の名前は変わることがあるので、最新の情報は公式ドキュメントで確認してください。

BYOK とは

BYOK は Bring Your Own Key（自分の鍵を持ち込む） の略です。

AI の文脈では、「OpenAI や Anthropic などの AI プロバイダーと 自分で契約して発行した API キー を、中継するサービス（今回は Cloudflare）に預けて使ってもらう」ことを指します。

【クレジット払い（Unified Billing）】
アプリ ──▶ Cloudflare ──▶ AI プロバイダー
              │  Cloudflare が契約しているキーで呼ぶ
              └─ 料金は Cloudflare のクレジットから引かれる

【BYOK】
アプリ ──▶ Cloudflare ──▶ AI プロバイダー
              │  あなたが預けたキーで呼ぶ
              └─ 料金は AI プロバイダーからあなたに直接請求される

どちらの場合も、アプリから見た呼び出し方は同じです。違うのは 「誰のキーで呼んで、誰に料金を払うか」 だけです。

別の意味の「BYOK」もあります。
クラウドのセキュリティの文脈では、BYOK は「データを暗号化する鍵を、利用者が自分で用意・管理する」ことを指します（Google Cloud の CMEK、AWS KMS の鍵のインポートなど）。この記事で扱うのは、AI の API キーのほうの BYOK です。

そもそも Cloudflare 経由で AI を呼ぶ価値

BYOK の話に入る前に、「AI プロバイダーを直接呼ばずに、Cloudflare を経由させる」こと自体の価値を整理しておきます。BYOK でもクレジット払いでも、ここは共通です。

【直接呼ぶ】
アプリ ──[OpenAI のキー]────▶ OpenAI
      ──[Anthropic のキー]─▶ Anthropic
      ──[TypeSafe のキー]──▶ TypeSafe

【Cloudflare 経由】
アプリ ──[Cloudflare のトークン]──▶ Cloudflare（AI Gateway）──▶ OpenAI / Anthropic / TypeSafe ...

• 呼び方が1つにそろう
  • どのプロバイダーのモデルも、Cloudflare の同じ API（/ai/run や OpenAI 互換の /ai/v1/chat/completions など）で、model の指定を変えるだけで呼べます
  • プロバイダーごとの SDK を入れる必要がなく、モデルを乗り換えるときのコードの変更も小さく済みます
• ログ・キャッシュ・使いすぎ対策が1か所にまとまる
  • AI Gateway のログ、キャッシュ、レート制限などが、どのプロバイダーにも同じように効きます
  • 「どのモデルにいくら使ったか」も Cloudflare のダッシュボードでまとめて見られます

そのうえで、BYOK にすると次の利点が加わります。

• アプリが持つ秘密情報は Cloudflare のトークン1つだけ
  • プロバイダーのキーは Cloudflare の Secrets Store に暗号化して預けるので、アプリの環境変数やソースコードに置かなくて済みます
  • キーを入れ替えるときも、Cloudflare のダッシュボードで差し替えるだけです。アプリの再デプロイは要りません

実際に個人開発で使ってみても、Cloudflare の API の呼び方さえわかれば、Claude Code が詰まることなく実装まで進めてくれました。本来はサービスごとに呼び出し方が違いますが、Cloudflare が 「入口と認証をそろえるアダプタ」 の役割をしてくれていたからだと思います。

Cloudflare がそろえてくれるもの	モデルごとに違うまま残るもの
呼び出し先・認証（Cloudflare のトークン1つ）・model での切り替え・ログやキャッシュ	input の中身・返ってくる結果の形

入力と出力の形まではそろわないので、そこは各モデルのドキュメントを見る必要があります。

つまり、価値の大部分は「Cloudflare を経由させること」にあり、BYOK はその上での 「お金と契約をどうするか」と「キーをどこに置くか」の選択肢 です。

クレジット払いと BYOK の違い

Cloudflare の公式ドキュメントをもとに比べると、次のようになります。

	クレジット払い（Unified Billing）	BYOK
AI プロバイダーとの契約	不要	自分で契約して API キーを発行する
料金の請求元	Cloudflare（1本にまとまる）	AI プロバイダーから直接
手数料	クレジット購入額に5%（$100 分買うと $105）	Cloudflare の手数料は掛からない
モデルの単価	プロバイダーの価格そのまま（上乗せなし）	プロバイダーとの契約どおり
支払い方	クレジットを前もって購入。自動チャージも可	プロバイダーの請求方法による
使いすぎ対策	Cloudflare 側で Gateway ごとに上限を設定できる	プロバイダー側の上限設定を使う
レート制限・利用規約	Cloudflare の契約に従う	自分のプロバイダー契約に従う
キーの管理	不要	必要（発行・保管・入れ替え）

BYOK のメリット

• 5% の手数料が掛からない
  • 利用額が大きくなるほど差が出ます
• AI プロバイダーと直接の関係を保てる
  • 利用枠（レート制限・クォータ）やデータの扱いの規約が、自分の契約どおりになります
  • すでにプロバイダーと契約しているなら、その契約をそのまま活かせます
• キーの入れ替えが1か所で済む
  • キーは Cloudflare の Secrets Store に暗号化して保存されます
  • キーを入れ替えるときは、Cloudflare のダッシュボードで差し替えるだけです。アプリのコードを変える必要も、止める必要もありません
• Cloudflare の機能はそのまま使える
  • AI Gateway のログ・キャッシュ・レート制限などは、BYOK でも使えます

BYOK のデメリット

• AI プロバイダーと個別に契約が必要
  • 使うプロバイダーが増えるほど、契約・請求・キーの管理も増えます
• 請求がバラバラになる
  • クレジット払いなら Cloudflare の請求1本にまとまりますが、BYOK ではプロバイダーごとに届きます
• キーが見つからないと、黙ってクレジット払いに切り替わる
  • 後述の「はまりどころ」で詳しく書きます

結局どっちがいい？

こんな場合	おすすめ
とりあえず試したい・利用額が小さい	クレジット払い（契約不要ですぐ始められる）
複数のプロバイダーを少しずつ使う	クレジット払い（請求が1本にまとまる）
利用額が大きい・本番で長く使う	BYOK（5% の手数料が効いてくる）
すでにプロバイダーと契約している	BYOK（契約・利用枠をそのまま使える）
支払いや契約の都合で、Cloudflare にクレジットを前払いしにくい	BYOK

私の場合は、クレジットを前払いして管理するより、使ったぶんを TypeSafe と直接やり取りするほうが都合がよかったので BYOK にしました。

「メリットがあるか」の結論としては、「手数料の5%と、契約・支払いの都合が気になるなら BYOK、手軽さを取るならクレジット払い」 です。機能面の差はほとんどありません。

正直なところ、BYOK ならではのメリットはお金と契約まわりが中心です。ただ、前の章で書いたとおり、Cloudflare を経由させて API をまとめること には大きな価値があります。BYOK は「その仕組みを、自分のプロバイダー契約のまま使うための方法」と考えるとわかりやすいです。

BYOK の設定手順

大きく3ステップです。

1. AI プロバイダーの API キーを発行する
2. Cloudflare に AI プロバイダーのキーを預ける
3. Cloudflare の API トークンを発行する

ここで勘違いしやすいのが3です。BYOK は「AI プロバイダーのキーを預ける」仕組みなので、アプリから Cloudflare を呼ぶための Cloudflare 自身の API トークンも別に必要 です。

アプリ ──[Cloudflare の API トークン]──▶ Cloudflare ──[預けた AI プロバイダーのキー]──▶ AI プロバイダー

1. AI プロバイダーの API キーを発行する

使いたい AI プロバイダー（今回は TypeSafe）の管理画面で API キーを発行します。

2. Cloudflare に AI プロバイダーのキーを預ける

前提として、次の2つが必要です。

• AI Gateway が 認証付き（Authenticated） になっていること
• Secrets Store でシークレットを作成・デプロイできる権限があること

Cloudflare のダッシュボードで、次のように操作します。

1. AI → AI Gateway を開く
2. 使う Gateway を選ぶ（なければ作る）
3. Provider Keys → Add API Key
4. プロバイダーを選び、1で発行したキーを貼り付けて保存
   • TypeSafe の場合は、一覧に TypeSafe AI が出てきます
5. Configured の一覧にプロバイダーが表示されれば完了です（キーは末尾の数文字以外が伏せて表示されます）

キーの名前（エイリアス）は default のままにしておきます。
/ai/run のような Cloudflare の REST API や Workers の env.AI.run() から呼ぶ場合、参照されるのは default という名前で保存したキーだけです。別の名前で保存すると、BYOK として使われません。

3. Cloudflare の API トークンを発行する

1. Cloudflare のダッシュボードで、アカウントの API トークン（または、右上のプロフィールの API トークン）を開く
2. トークンを作成 → カスタムトークンを作る
3. 権限に Account → Workers AI → Read を付ける
4. 作成して、表示されたトークンを控える（一度しか表示されません）

/accounts/{account_id}/ai/* の API は、呼び出すのが Cloudflare のモデルでも他社のモデルでも、Workers AI の権限 が必要です。AI Gateway の権限だけでは呼べません。

4. 呼び出す

あとは、Cloudflare の API を呼ぶだけです。リクエストに AI プロバイダーのキーは含めません。Cloudflare が預かったキーを使ってくれます。

curl https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/run \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "typesafe/jev",
    "input": { ...モデルごとの入力... }
  }'

input の中身はモデルによって違うので、Cloudflare のモデルカタログで各モデルのページを見てください。

はまりどころ

キーが見つからないと、黙ってクレジット払いになる

いちばん注意したい点です。Cloudflare は、リクエストを受けると次の順番でキーを探します。

1. リクエストに AI プロバイダーのキーが付いていれば、それを使う
2. なければ、Gateway に default という名前で預けたキーを使う（BYOK）
3. それもなければ、Cloudflare のクレジットで払う（Unified Billing）

つまり、キーの名前を間違えたり、キーを消してしまったりすると、エラーにならずにクレジット払いで動いてしまいます。クレジットの残高があると、気づかないまま手数料込みで課金されることになります。

これを防ぐには、Gateway の Settings で Require provider credentials をオンにします。オンにすると、他社モデルへのリクエストでキーが見つからないときは、クレジット払いに切り替わらずに HTTP 400 エラーになります。BYOK で運用するなら、オンにしておくのがおすすめです。

API トークンを貼り付けたときの改行で「Authentication error」

Cloudflare の API トークンを環境変数や設定画面に貼り付けたとき、末尾に改行や空白が紛れ込むことがあります。この状態で呼ぶと、Cloudflare は 「Authentication error」 を返します。トークン自体は正しいので、原因に気づきにくいです。

コード側で、読み込んだ値の前後の空白を取り除いておくと安全です。

const token = (process.env.CLOUDFLARE_API_TOKEN ?? "").trim();

トークンの確認先が2種類ある

API トークンが有効かどうかは、次の API で確認できます（推論は行わないので料金は掛かりません）。ただし、トークンをどこで作ったかによって確認先が違います。

トークンを作った場所	確認先
プロフィールの API トークン（ユーザーのトークン）	GET /client/v4/user/tokens/verify
アカウントの API トークン	GET /client/v4/accounts/{account_id}/tokens/verify

curl https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/tokens/verify \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

違うほうで確認すると「無効」と返ってくるので、トークンが壊れていると勘違いしがちです。

AI Gateway のログに、送った内容が残る

AI Gateway のログを有効にしていると、モデルに送った本文や返ってきた結果が Cloudflare に保存されます。社外秘の情報や個人情報を送る場合は、ログをオフにするか、メタデータだけを残す設定にしておきましょう。

まとめ

• Cloudflare 経由にすると、どのプロバイダーのモデルも同じ API で呼べて、ログやキャッシュも1か所にまとまる。価値の大部分はここ
• BYOK は「自分の AI プロバイダーの API キーを Cloudflare に預ける」仕組み。違いは 誰のキーで呼び、誰に払うか。アプリにプロバイダーのキーを置かなくて済むのも利点
• クレジット払いは購入額に 5% の手数料 が掛かる。BYOK なら掛からない
• 機能面の差はほとんどなく、手数料・契約・支払いの都合 で選べばいい
• 設定には、AI プロバイダーのキーに加えて Cloudflare の API トークン（Workers AI の Read 権限） が必要
• キーが見つからないと黙ってクレジット払いになるので、Require provider credentials をオンにしておく

参考リンク

• BYOK (Store Keys) · Cloudflare AI Gateway docs
• Unified Billing · Cloudflare AI Gateway docs
• REST API · Cloudflare AI Gateway docs
• AI Gateway の料金
• Create API token（ユーザーのトークンの確認方法）· Cloudflare docs
• Verify Token（アカウントのトークン）· Cloudflare API
• Account API tokens · Cloudflare docs
• Jev (typesafe) · Cloudflare AI docs
• Customer-managed encryption keys (CMEK) · Google Cloud