Workers Bindings

The AI binding (env.AI) lets you call AI models and access AI Gateway features directly from your Worker.

For a step-by-step setup guide, refer to Set up Workers AI with AI Gateway.

Configuration

Add an AI binding to your Wrangler configuration file:

wrangler.jsonc
wrangler.toml

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

[ai]
binding = "AI"

The binding is accessible in your Worker code as env.AI.

If you're using TypeScript, run wrangler types whenever you modify your Wrangler configuration file. This generates types for the env object based on your bindings, as well as runtime types.

`env.AI.run()`

Runs an inference request through AI Gateway. Accepts Workers AI models (@cf/ prefix) and third-party models ({author}/{model} format).

Workers AI model:

JavaScript
TypeScript

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

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

Third-party model:

JavaScript
TypeScript

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

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

Third-party models require an AI Gateway and use Unified Billing. Cloudflare manages the provider credentials and deducts credits from your account. You do not need to supply your own API keys.

Browse available models in the model catalog.

Gateway options

The third argument to env.AI.run() accepts a gateway object with the following parameters:

Parameter	Type	Default	Description
`id`	`string`	required	Name of your AI Gateway. Must be in the same account as your Worker.
`skipCache`	`boolean`	`false`	Skip the cache for this request.
`cacheTtl`	`number`	—	Cache TTL in seconds.
`cacheKey`	`string`	—	Custom cache key for this request.
`collectLog`	`boolean`	—	Whether to collect logs for this request.
`metadata`	`object`	—	Custom metadata to attach to the log entry.

`env.AI.aiGatewayLogId`

Returns the log ID from the most recent env.AI.run() request.

const myLogId = env.AI.aiGatewayLogId;

`env.AI.gateway()`

Returns a gateway instance for accessing AI Gateway methods directly.

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

The gateway instance exposes the following methods.

`patchLog()`

Sends feedback, score, and metadata for a specific log entry. All properties in the second argument are optional.

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

Returns: Promise<void>

`getLog()`

Retrieves details of a specific log entry. If the AiGatewayLog type is missing, run wrangler types.

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

Returns: Promise<AiGatewayLog>

`getUrl()`

Returns the base URL for your AI Gateway. Pass an optional provider name to get the provider-specific endpoint.

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

Parameters: Optional provider (string or AIGatewayProviders enum)

Returns: Promise<string>

SDK integration examples

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"),
});

`run()`

Executes a universal request to any supported provider. Accepts a single request object or an array.

const resp = await gateway.run({
  provider: "workers-ai",
  endpoint: "@cf/meta/llama-3.1-8b-instruct",
  headers: {
    authorization: "Bearer my-api-token",
  },
  query: {
    prompt: "tell me a joke",
  },
});

Returns: Promise<Response>