Workers バインディング

AI バインディング（env.AI）を使うと、Worker から直接 AI モデルを呼び出し、AI Gateway の機能にアクセスできます。

手順ごとのセットアップガイドは、Workers AI を AI Gateway と一緒にセットアップする を参照してください。

Wrangler 設定ファイル に AI バインディングを追加します。

{
	"ai": {
		"binding": "AI",
	},
}

[ai]
binding = "AI"

バインディングは Worker コード内で env.AI としてアクセスできます。

TypeScript を使う場合は、Wrangler 設定ファイルを変更するたびに wrangler types を実行します。バインディングに基づく env オブジェクトの型と、ランタイム型 が生成されます。

AI Gateway 経由で推論リクエストを実行します。Workers AI モデル（@cf/ プレフィックス）とサードパーティモデル（{author}/{model} 形式）を受け付けます。

Workers AI モデル:

const resp = await env.AI.run(
	"@cf/moonshotai/kimi-k2.5",
	{
		prompt: "tell me a joke",
	},
	{
		gateway: {
			id: "default", // or use a specific gateway name
		},
	},
);

const resp = await env.AI.run(
	"@cf/moonshotai/kimi-k2.5",
	{
		prompt: "tell me a joke",
	},
	{
		gateway: {
			id: "default", // or use a specific gateway name
		},
	},
);

前払いの AI Gateway クレジット を使うには、ゲートウェイの Workers AI billing 設定 を Unified billing にし、バインディングリクエストでそのゲートウェイを指定します。前払いクレジットを使うと、本来 Workers Paid プランが必要な Workers AI モデルにアクセスでき、フロンティアモデルのレート制限が上がります。

サードパーティモデル:

const resp = await env.AI.run(
	"openai/gpt-4.1-mini",
	{
		messages: [{ role: "user", content: "tell me a joke" }],
	},
	{
		gateway: {
			id: "default", // or use a specific gateway name
		},
	},
);

const resp = await env.AI.run(
	"openai/gpt-4.1-mini",
	{
		messages: [{ role: "user", content: "tell me a joke" }],
	},
	{
		gateway: {
			id: "default", // or use a specific gateway name
		},
	},
);

サードパーティモデルには AI Gateway が必要で、Unified Billing を使います。Cloudflare がプロバイダーの資格情報を管理し、アカウントからクレジットを差し引きます。独自の API キーを渡す必要はありません。

利用できるモデルは モデルカタログ で確認できます。

env.AI.run() の第 3 引数は、次のパラメーターを持つ gateway オブジェクトを受け付けます。

直近の env.AI.run() リクエストのログ ID を返します。

const myLogId = env.AI.aiGatewayLogId;

AI Gateway メソッドに直接アクセスするためのゲートウェイインスタンスを返します。

const gateway = env.AI.gateway("my-gateway");

ゲートウェイインスタンスは次のメソッドを公開します。

特定のログエントリにフィードバック、スコア、メタデータを送ります。第 2 引数のプロパティはすべて任意です。

await gateway.patchLog("my-log-id", {
	feedback: 1,
	score: 100,
	metadata: {
		user: "123",
	},
});

戻り値: Promise<void>

特定のログエントリの詳細を取得します。AiGatewayLog 型がない場合は wrangler types を実行します。

const log = await gateway.getLog("my-log-id");

戻り値: Promise<AiGatewayLog>

AI Gateway のベース URL を返します。任意のプロバイダー名を渡すと、プロバイダー固有のエンドポイントを取得できます。

const baseUrl = await gateway.getUrl();
// https://gateway.ai.cloudflare.com/v1/my-account-id/my-gateway/

const openaiUrl = await gateway.getUrl("openai");
// https://gateway.ai.cloudflare.com/v1/my-account-id/my-gateway/openai

パラメーター: 任意の provider（string または AIGatewayProviders enum）

戻り値: Promise<string>

OpenAI SDK:

import OpenAI from "openai";

const openai = new OpenAI({
	apiKey: "my api key", // defaults to process.env["OPENAI_API_KEY"]
	baseURL: await env.AI.gateway("my-gateway").getUrl("openai"),
});

Vercel AI SDK with OpenAI:

import { createOpenAI } from "@ai-sdk/openai";

const openai = createOpenAI({
	baseURL: await env.AI.gateway("my-gateway").getUrl("openai"),
});

Vercel AI SDK with Anthropic:

import { createAnthropic } from "@ai-sdk/anthropic";

const anthropic = createAnthropic({
	baseURL: await env.AI.gateway("my-gateway").getUrl("anthropic"),
});