REST API

REST API を使うと、Cloudflare 上でも OpenAI、Anthropic、Google などの第三者プロバイダー上でも、任意のモデルを同じ Cloudflare API 経由で呼び出せます。ログ、キャッシュ、レート制限などの AI Gateway 機能は自動で適用されます。

プロバイダー SDK や API キーは不要です。認証と課金は Cloudflare アカウント経由です。第三者モデルは Unified Billing で課金されます。Workers AI モデルは、前払いの AI Gateway クレジットまたは Workers AI の課金を使えます。

エンドポイント

用途に応じて、次の 4 つのエンドポイントがあります。

エンドポイント	形式	用途	第三者モデル	Workers AI モデル（`@cf/`）
`POST /ai/run`	`model` と `input` のエンベロープ	すべてのモデルとモダリティ（LLM、画像、TTS、ASR）	✅ はい	✅ はい
`POST /ai/v1/chat/completions`	OpenAI chat completions	LLM — OpenAI SDK 互換	✅ はい	✅ はい
`POST /ai/v1/responses`	OpenAI Responses API	エージェントワークフロー — OpenAI SDK 互換	✅ はい	✅ モデルによる
`POST /ai/v1/messages`	Anthropic Messages API	LLM — Anthropic SDK 互換	✅ はい	❌ いいえ

認証

Account > Workers AI > Read 権限を持つ Cloudflare API トークンで認証します。Authorization ヘッダーに渡します。

すべての /accounts/{account_id}/ai/* エンドポイントには Workers AI 権限が必要です。第三者モデルと Workers AI（@cf/）モデルの両方に適用されます。AI Gateway 権限だけのトークンは、エラーコード 10000 の 401 を返します。

AI Gateway 権限は、ゲートウェイ設定、ログ、ルートを管理する /accounts/{account_id}/ai-gateway/* エンドポイントに適用されます。

モデル名

第三者モデルは author/model 形式です。

openai/gpt-4.1 — OpenAI
anthropic/claude-sonnet-4 — Anthropic
google/gemini-3-flash — Google
xai/grok-3 — xAI

Workers AI モデルは @cf/author/model 形式です（例: @cf/moonshotai/kimi-k2.6）。Workers AI リクエストには cf-aig-gateway-id ヘッダーも必要です。詳細は Workers AI モデルを呼ぶを参照してください。

利用可能なモデルはモデルカタログで確認します。

`/ai/run` — 汎用エンドポイント

モデルごとのスキーマで、任意のモデルを受け付けます。モデル固有のパラメーターは input に入れます。

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/run" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "openai/gpt-4.1",
    "input": {
      "messages": [
        {
          "role": "user",
          "content": "What is Cloudflare?"
        }
      ],
      "max_tokens": 512
    }
  }'

Workers AI モデルを呼ぶ

Workers AI モデルを呼ぶには、モデル名に @cf/ プレフィックスを使い、ルーティング先のゲートウェイを指定する cf-aig-gateway-id ヘッダーを含めます。

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/run" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "cf-aig-gateway-id: default" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "@cf/moonshotai/kimi-k2.6",
    "input": {
      "messages": [
        {
          "role": "user",
          "content": "What is Cloudflare?"
        }
      ]
    }
  }'

URL パスにモデル ID を含む既存の Workers AI エンドポイントも、引き続き使えます。

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/run/@cf/moonshotai/kimi-k2.6" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "cf-aig-gateway-id: default" \
  --header "Content-Type: application/json" \
  --data '{
    "messages": [
      {
        "role": "user",
        "content": "What is Cloudflare?"
      }
    ]
  }'

Workers AI に前払い AI Gateway クレジットを使うには、上のモデル ID をパスに含むエンドポイントを使い、ゲートウェイの Workers AI 課金設定を Unified billing にし、その ID を cf-aig-gateway-id ヘッダーに含めます。前払いクレジットで課金されるフロンティアモデルへのリクエストは、より高いレート制限を受けます。

バックグラウンドリクエストと webhook

デフォルトでは、/ai/run リクエストは同期です。モデルが終わるまで接続は開いたまま、結果が応答で返ります。画像、動画、音声生成などの長時間モデルや、接続を開いたままにしたくない場合は、リクエストをバックグラウンドで実行し、完了時に AI Gateway が webhook に通知するようにします。

background を true にし、webhookUrl を指定します。どちらも /ai/run 本体の options オブジェクトのフィールドで、model と input と並びます。

webhookUrl は、background が true のときだけ指定できます。background: true なしで webhookUrl を指定すると 400 エラーが返ります。

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/run" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "google/nano-banana",
    "input": {
      "prompt": "A cozy coffee shop interior with warm lighting, plants hanging from the ceiling, and a cat sleeping on a velvet armchair by the window",
      "aspect_ratio": "16:9"
    },
    "options": {
      "background": true,
      "webhookUrl": "https://example.com/my-webhook"
    }
  }'

バックグラウンドリクエストはすぐに戻り、モデルは裏側で動きます。実行が完了すると、結果が webhook に届きます。

Webhook ペイロード

実行が完了すると、AI Gateway は webhookUrl へ実行結果を含む POST リクエストを 1 回送ります。

{
	"id": "<run-id>",
	"state": "<run-state>",
	"result": {},
	"error": null,
	"provider": "google",
	"model": "google/nano-banana",
	"usage": {}
}

Webhook 配信はベストエフォートで、再試行されません。宛先は、プライベートネットワークアドレスに解決しない HTTPS URL である必要があります。

Webhook 形式

options オブジェクトの任意の webhookFormat フィールドで、webhook 本体の形を制御します。デフォルトは raw です。webhookFormat は webhookUrl があるときだけ指定できます。それ以外ではリクエストは 400 エラーを返します。

形式	説明
`raw`	ペイロードをそのまま送ります（デフォルト）。
`chat`	ペイロードを `{ "text": "<prettified JSON>" }` で包み、Google Chat と Slack が受け付ける受信 webhook 本体に合わせます。

`/ai/v1/chat/completions` — OpenAI 互換

標準の OpenAI chat completions 形式を使います。model フィールドは同じ author/model 命名です。このエンドポイントは OpenAI SDK およびほかの OpenAI 互換クライアントと互換があります。

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "openai/gpt-4.1",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "What is Cloudflare?"
      }
    ],
    "max_tokens": 512,
    "temperature": 0.7,
    "stream": true
  }'

OpenAI SDK

OpenAI SDK の baseURL を Cloudflare API に向けます。

import OpenAI from "openai";

const openai = new OpenAI({
	apiKey: CLOUDFLARE_API_TOKEN,
	baseURL: `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/ai/v1`,
});

const response = await openai.chat.completions.create({
	model: "openai/gpt-4.1",
	messages: [{ role: "user", content: "What is Cloudflare?" }],
});

`/ai/v1/responses` — OpenAI Responses API

エージェントワークフロー向けの OpenAI Responses API 形式を使います。OpenAI SDK と互換があります。

import OpenAI from "openai";

const openai = new OpenAI({
	apiKey: CLOUDFLARE_API_TOKEN,
	baseURL: `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/ai/v1`,
});

const response = await openai.responses.create({
	model: "openai/gpt-4.1",
	input: "What is Cloudflare?",
});

`/ai/v1/messages` — Anthropic 互換

Anthropic Messages API 形式を使います。Anthropic SDK と互換があります。

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/messages" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "anthropic/claude-sonnet-4-5",
    "max_tokens": 512,
    "messages": [
      {
        "role": "user",
        "content": "What is Cloudflare?"
      }
    ]
  }'

Anthropic SDK の baseURL を Cloudflare API に向けます。

import Anthropic from "@anthropic-ai/sdk";

const anthropic = new Anthropic({
	apiKey: CLOUDFLARE_API_TOKEN,
	baseURL: `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/ai/v1`,
});

const message = await anthropic.messages.create({
	model: "anthropic/claude-sonnet-4-5",
	max_tokens: 512,
	messages: [{ role: "user", content: "What is Cloudflare?" }],
});

プロバイダーツールと Web 検索

一部のプロバイダーは、これらのエンドポイント経由でネイティブツール（サーバー側 Web 検索を含む）を公開します。プロバイダーごとの対応モデルと、それぞれが使うリクエスト形は Web Search を参照してください。正規のモデル ID はモデルカタログで確認します。

ゲートウェイを指定する

デフォルトでは、第三者モデルのリクエストはアカウントのデフォルト AI Gateway 経由でルーティングされます。特定のゲートウェイを使うには、cf-aig-gateway-id ヘッダーを含めます。Workers AI リクエストでは、このヘッダーは常に必要です。

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "cf-aig-gateway-id: default" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "anthropic/claude-sonnet-4",
    "messages": [
      {
        "role": "user",
        "content": "Hello"
      }
    ]
  }'

OpenAI SDK では、defaultHeaders 経由でヘッダーを設定します。

const openai = new OpenAI({
	apiKey: CLOUDFLARE_API_TOKEN,
	baseURL: `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/ai/v1`,
	defaultHeaders: {
		"cf-aig-gateway-id": "default",
	},
});

そのゲートウェイに設定したすべての AI Gateway 機能（キャッシュ、レート制限、ガードレール、ログ）がリクエストに適用されます。

リクエスト単位の設定

cf-aig-* ヘッダーを使い、リクエスト単位で AI Gateway の動作を制御します。

ヘッダー	型	説明
`cf-aig-skip-cache`	boolean	このリクエストのキャッシュをスキップします。
`cf-aig-cache-ttl`	number	キャッシュ TTL（秒）。
`cf-aig-cache-key`	string	カスタムキャッシュキー。
`cf-aig-collect-log`	boolean	このリクエストのログをオンまたはオフにします。
`cf-aig-request-timeout`	number	リクエストタイムアウト（ミリ秒）。
`cf-aig-max-attempts`	number	再試行回数（最大 5）。
`cf-aig-retry-delay`	number	再試行遅延（ミリ秒、最大 60000）。
`cf-aig-backoff`	string	バックオフ方法: `constant`、`linear`、または `exponential`。
`cf-aig-metadata`	JSON string	ログエントリに付けるカスタムメタデータ。

これらのオプションの詳細は、リクエスト処理とキャッシュを参照してください。