From dc529099e0ea7e6d0fc2271b0fb44d41a7ba423e Mon Sep 17 00:00:00 2001 From: Ming Lu Date: Tue, 14 Apr 2026 13:36:24 -0700 Subject: [PATCH 01/14] [AI Gateway] Add docs for third-party models via Workers AI binding Add a new page documenting how to call OpenAI, Anthropic, Google, and other third-party models through env.AI.run() with AI Gateway features. Update worker-binding-methods and Workers AI provider pages with cross-references to the new page. --- .../aig-workers-ai-binding-third-party.mdx | 269 ++++++++++++++++++ .../integrations/worker-binding-methods.mdx | 18 ++ .../ai-gateway/usage/providers/workersai.mdx | 4 + 3 files changed, 291 insertions(+) create mode 100644 src/content/docs/ai-gateway/integrations/aig-workers-ai-binding-third-party.mdx diff --git a/src/content/docs/ai-gateway/integrations/aig-workers-ai-binding-third-party.mdx b/src/content/docs/ai-gateway/integrations/aig-workers-ai-binding-third-party.mdx new file mode 100644 index 00000000000..1aadd4cffa4 --- /dev/null +++ b/src/content/docs/ai-gateway/integrations/aig-workers-ai-binding-third-party.mdx @@ -0,0 +1,269 @@ +--- +title: Third-party models via Workers AI binding +pcx_content_type: configuration +tags: + - AI + - Bindings +sidebar: + order: 2 +description: >- + Call models from OpenAI, Anthropic, Google, and other providers directly through + the Workers AI binding (env.AI.run()) with AI Gateway features like caching, + rate limiting, and observability. +--- + +import { WranglerConfig, TypeScriptExample, Details } from "~/components"; + +The Workers AI binding (`env.AI`) can call models from third-party providers -- OpenAI, Anthropic, Google, and many more -- directly from your Worker. Requests are routed through AI Gateway so you get caching, rate limiting, logging, and observability without any extra setup. + +This means you can call models like `openai/gpt-5`, `anthropic/claude-sonnet-4`, or `google/gemini-3-flash` with the same `env.AI.run()` API you already use for Workers AI models, and every request flows through your AI Gateway. + +## Prerequisites + +- A Cloudflare Worker with an [AI binding](/workers-ai/configuration/bindings/) configured. +- An [AI Gateway](/ai-gateway/get-started/) created in the same account. +- [Unified Billing](/ai-gateway/features/unified-billing/) credits loaded on your account. + +## Setup + +Add an AI binding to your Worker's [Wrangler configuration file](/workers/wrangler/configuration/): + + + +```jsonc +{ + "ai": { + "binding": "AI" + } +} +``` + + + +## Authentication and billing + +Third-party models called through the Workers AI binding use [Unified Billing](/ai-gateway/features/unified-billing/). Cloudflare manages the provider credentials and deducts credits from your account for each request. You do not need to supply your own API keys. + +:::note +[BYOK (Bring Your Own Keys)](/ai-gateway/configuration/bring-your-own-keys/) is not supported for third-party models called through the Workers AI binding. The binding does not provide a way to pass provider API keys at request time. If you need to use your own provider keys, call the provider through the [provider-native REST endpoints](/ai-gateway/usage/providers/) or the [gateway binding `run` method](/ai-gateway/integrations/worker-binding-methods/#34-run-universal-requests) instead. +::: + +## Basic usage + +Call a third-party model with `env.AI.run()` by passing the model ID in `{provider}/{model}` format and a `gateway` option with your gateway ID: + + + +```ts +export default { + async fetch(request: Request, env: Env): Promise { + const response = await env.AI.run( + "openai/gpt-4.1-mini", + { + messages: [ + { + role: "user", + content: "What is Cloudflare?", + }, + ], + }, + { + gateway: { + id: "my-gateway", + }, + }, + ); + return Response.json(response); + }, +} satisfies ExportedHandler; +``` + + + +The `gateway` option accepts the following parameters: + +| Parameter | Type | Default | Description | +| --- | --- | --- | --- | +| `id` | `string` | *required* | Name of your [AI Gateway](/ai-gateway/get-started/). Must be in the same account as your Worker. | +| `skipCache` | `boolean` | `false` | Skip the [cache](/ai-gateway/features/caching/) for this request. | +| `cacheTtl` | `number` | — | [Cache TTL](/ai-gateway/features/caching/) in seconds. | +| `cacheKey` | `string` | — | Custom [cache key](/ai-gateway/features/caching/) for this request. | +| `collectLog` | `boolean` | — | Whether to [collect logs](/ai-gateway/observability/logging/) for this request. | +| `metadata` | `object` | — | [Custom metadata](/ai-gateway/observability/custom-metadata/) to attach to the log entry. | + +## Examples + +### Text generation + +#### OpenAI + +```typescript title="src/index.ts" +const response = await env.AI.run( + "openai/gpt-5", + { + messages: [ + { role: "system", content: "You are a helpful assistant." }, + { role: "user", content: "Explain how DNS works in two sentences." }, + ], + }, + { + gateway: { id: "my-gateway" }, + }, +); +``` + +#### Anthropic + +Anthropic models use the [Anthropic Messages format](https://docs.anthropic.com/en/api/messages). Note that `max_tokens` is required and `system` is a top-level field. + +```typescript title="src/index.ts" +const response = await env.AI.run( + "anthropic/claude-sonnet-4", + { + system: "You are a helpful assistant.", + messages: [ + { role: "user", content: "Explain how DNS works in two sentences." }, + ], + max_tokens: 1024, + }, + { + gateway: { id: "my-gateway" }, + }, +); +``` + +#### Google Gemini + +```typescript title="src/index.ts" +const response = await env.AI.run( + "google/gemini-3-flash", + { + messages: [ + { role: "user", content: "Explain how DNS works in two sentences." }, + ], + }, + { + gateway: { id: "my-gateway" }, + }, +); +``` + +### Streaming + +Pass `stream: true` in the input to receive a streaming response: + +```typescript title="src/index.ts" +const response = await env.AI.run( + "openai/gpt-4.1-mini", + { + messages: [ + { role: "user", content: "Write a short poem about the Internet." }, + ], + stream: true, + }, + { + gateway: { id: "my-gateway" }, + }, +); + +return new Response(response, { + headers: { "Content-Type": "text/event-stream" }, +}); +``` + +### Image generation + +```typescript title="src/index.ts" +const response = await env.AI.run( + "cloudflare/image", + { + prompt: "A futuristic city skyline at sunset, digital art", + }, + { + gateway: { id: "my-gateway" }, + }, +); +``` + +### Text-to-speech + +```typescript title="src/index.ts" +const response = await env.AI.run( + "openai/tts-1", + { + text: "Hello! Welcome to Cloudflare AI Gateway.", + voice: "nova", + }, + { + gateway: { id: "my-gateway" }, + }, +); +``` + +### Speech-to-text + +```typescript title="src/index.ts" +const response = await env.AI.run( + "cloudflare/stt", + { + audio: audioArrayBuffer, + }, + { + gateway: { id: "my-gateway" }, + }, +); +``` + +### Video generation + +```typescript title="src/index.ts" +const response = await env.AI.run( + "cloudflare/video", + { + prompt: "A golden retriever playing fetch on a sandy beach at sunset", + }, + { + gateway: { id: "my-gateway" }, + }, +); +``` + +## Supported models + +Model IDs use the `{provider}/{model}` format -- for example, `openai/gpt-5` or `anthropic/claude-sonnet-4`. The provider prefix refers to the model author, not the infrastructure hosting it. + +Browse the full list of available models, including supported tasks and input schemas, in the [model catalog](https://developers.cloudflare.com/ai/models/). + +Cloudflare also provides task-level aliases that automatically route to the best available model: + +- `cloudflare/image` -- Text-to-Image +- `cloudflare/image-edit` -- Image-to-Image +- `cloudflare/video` -- Text-to-Video +- `cloudflare/i2v` -- Image-to-Video +- `cloudflare/stt` -- Speech-to-Text +- `cloudflare/tts` -- Text-to-Speech + +:::note +Workers AI models (prefixed with `@cf/` or `@hf/`) are also supported through `env.AI.run()` and route through AI Gateway when you pass the `gateway` option. Refer to [Workers AI provider](/ai-gateway/usage/providers/workersai/) for details. +::: + +## Accessing the log ID + +After making a request, you can retrieve the AI Gateway log ID for observability: + +```typescript title="src/index.ts" +const response = await env.AI.run("openai/gpt-4.1-mini", input, { + gateway: { id: "my-gateway" }, +}); + +const logId = env.AI.aiGatewayLogId; +``` + +Use the log ID with the [gateway binding methods](/ai-gateway/integrations/worker-binding-methods/) to send feedback, retrieve log details, or update metadata. + +## Related resources + +- [Workers AI binding tutorial](/ai-gateway/integrations/aig-workers-ai-binding/) -- Step-by-step guide to setting up Workers AI with AI Gateway. +- [AI Gateway binding methods](/ai-gateway/integrations/worker-binding-methods/) -- `patchLog`, `getLog`, `getUrl`, and `run` methods. +- [Unified Billing](/ai-gateway/features/unified-billing/) -- Pay for third-party inference with Cloudflare credits. +- [Caching](/ai-gateway/features/caching/) -- Cache responses to reduce latency and cost. diff --git a/src/content/docs/ai-gateway/integrations/worker-binding-methods.mdx b/src/content/docs/ai-gateway/integrations/worker-binding-methods.mdx index d9103998b4c..65152fbbc4f 100644 --- a/src/content/docs/ai-gateway/integrations/worker-binding-methods.mdx +++ b/src/content/docs/ai-gateway/integrations/worker-binding-methods.mdx @@ -52,6 +52,24 @@ const resp = await env.AI.run( ); ``` +You can also call third-party models from providers like OpenAI, Anthropic, and Google using the same `env.AI.run()` method. Use the `{provider}/{model}` format for the model ID: + +```typescript title="src/index.ts" +const resp = await env.AI.run( + "openai/gpt-4.1-mini", + { + messages: [{ role: "user", content: "tell me a joke" }], + }, + { + gateway: { + id: "my-gateway", + }, + }, +); +``` + +For the full list of supported third-party models, refer to [Third-party models via Workers AI binding](/ai-gateway/integrations/aig-workers-ai-binding-third-party/). + Additionally, you can access the latest request log ID with: ```typescript diff --git a/src/content/docs/ai-gateway/usage/providers/workersai.mdx b/src/content/docs/ai-gateway/usage/providers/workersai.mdx index e286aa77cdb..90bf93d85a6 100644 --- a/src/content/docs/ai-gateway/usage/providers/workersai.mdx +++ b/src/content/docs/ai-gateway/usage/providers/workersai.mdx @@ -11,6 +11,10 @@ import { Render, TypeScriptExample } from "~/components"; Use AI Gateway for analytics, caching, and security on requests to [Workers AI](/workers-ai/). Workers AI integrates seamlessly with AI Gateway, allowing you to execute AI inference via API requests or through an environment binding for Workers scripts. The binding simplifies the process by routing requests through your AI Gateway with minimal setup. +:::note +The Workers AI binding can also call models from third-party providers like OpenAI, Anthropic, and Google directly through AI Gateway. Refer to [Third-party models via Workers AI binding](/ai-gateway/integrations/aig-workers-ai-binding-third-party/) for details. +::: + ## Prerequisites When making requests to Workers AI, ensure you have the following: From 0b2bb409a532bd442e5268b6e6dfd14de939b8db Mon Sep 17 00:00:00 2001 From: Ming Lu Date: Tue, 14 Apr 2026 13:38:02 -0700 Subject: [PATCH 02/14] [AI Gateway] Expand Unified Billing supported providers list Add Google Vertex AI, Cerebras, and Workers AI to the provider-native endpoints list. Add a new Workers AI binding subsection listing all providers available through env.AI.run() (Anthropic, OpenAI, Google, ByteDance, Recraft, MiniMax, Inworld, AssemblyAI, RunwayML, Moonshot AI). --- .../ai-gateway/features/unified-billing.mdx | 9 +- .../aig-workers-ai-binding-third-party.mdx | 269 ------------------ .../integrations/aig-workers-ai-binding.mdx | 4 + .../integrations/worker-binding-methods.mdx | 55 ++-- .../ai-gateway/usage/providers/workersai.mdx | 2 +- 5 files changed, 47 insertions(+), 292 deletions(-) delete mode 100644 src/content/docs/ai-gateway/integrations/aig-workers-ai-binding-third-party.mdx diff --git a/src/content/docs/ai-gateway/features/unified-billing.mdx b/src/content/docs/ai-gateway/features/unified-billing.mdx index c1e4778c536..12f3379320a 100644 --- a/src/content/docs/ai-gateway/features/unified-billing.mdx +++ b/src/content/docs/ai-gateway/features/unified-billing.mdx @@ -132,10 +132,17 @@ curl -X POST https://gateway.ai.cloudflare.com/v1/$CLOUDFLARE_ACCOUNT_ID/{gatewa ### Supported providers -Unified Billing supports the following AI providers: +#### Provider-native endpoints + +Unified Billing supports the following providers through their [provider-native endpoints](/ai-gateway/usage/providers/): - [OpenAI](/ai-gateway/usage/providers/openai/) - [Anthropic](/ai-gateway/usage/providers/anthropic/) - [Google AI Studio](/ai-gateway/usage/providers/google-ai-studio/) +- [Google Vertex AI](/ai-gateway/usage/providers/vertex/) - [xAI](/ai-gateway/usage/providers/grok/) - [Groq](/ai-gateway/usage/providers/groq/) + +#### Workers AI binding + +When calling models through the [Workers AI binding](/ai-gateway/integrations/worker-binding-methods/#call-third-party-models) (`env.AI.run()`), Unified Billing is supported for all available third-party models. Browse the full list in the [model catalog](https://developers.cloudflare.com/ai/models/). diff --git a/src/content/docs/ai-gateway/integrations/aig-workers-ai-binding-third-party.mdx b/src/content/docs/ai-gateway/integrations/aig-workers-ai-binding-third-party.mdx deleted file mode 100644 index 1aadd4cffa4..00000000000 --- a/src/content/docs/ai-gateway/integrations/aig-workers-ai-binding-third-party.mdx +++ /dev/null @@ -1,269 +0,0 @@ ---- -title: Third-party models via Workers AI binding -pcx_content_type: configuration -tags: - - AI - - Bindings -sidebar: - order: 2 -description: >- - Call models from OpenAI, Anthropic, Google, and other providers directly through - the Workers AI binding (env.AI.run()) with AI Gateway features like caching, - rate limiting, and observability. ---- - -import { WranglerConfig, TypeScriptExample, Details } from "~/components"; - -The Workers AI binding (`env.AI`) can call models from third-party providers -- OpenAI, Anthropic, Google, and many more -- directly from your Worker. Requests are routed through AI Gateway so you get caching, rate limiting, logging, and observability without any extra setup. - -This means you can call models like `openai/gpt-5`, `anthropic/claude-sonnet-4`, or `google/gemini-3-flash` with the same `env.AI.run()` API you already use for Workers AI models, and every request flows through your AI Gateway. - -## Prerequisites - -- A Cloudflare Worker with an [AI binding](/workers-ai/configuration/bindings/) configured. -- An [AI Gateway](/ai-gateway/get-started/) created in the same account. -- [Unified Billing](/ai-gateway/features/unified-billing/) credits loaded on your account. - -## Setup - -Add an AI binding to your Worker's [Wrangler configuration file](/workers/wrangler/configuration/): - - - -```jsonc -{ - "ai": { - "binding": "AI" - } -} -``` - - - -## Authentication and billing - -Third-party models called through the Workers AI binding use [Unified Billing](/ai-gateway/features/unified-billing/). Cloudflare manages the provider credentials and deducts credits from your account for each request. You do not need to supply your own API keys. - -:::note -[BYOK (Bring Your Own Keys)](/ai-gateway/configuration/bring-your-own-keys/) is not supported for third-party models called through the Workers AI binding. The binding does not provide a way to pass provider API keys at request time. If you need to use your own provider keys, call the provider through the [provider-native REST endpoints](/ai-gateway/usage/providers/) or the [gateway binding `run` method](/ai-gateway/integrations/worker-binding-methods/#34-run-universal-requests) instead. -::: - -## Basic usage - -Call a third-party model with `env.AI.run()` by passing the model ID in `{provider}/{model}` format and a `gateway` option with your gateway ID: - - - -```ts -export default { - async fetch(request: Request, env: Env): Promise { - const response = await env.AI.run( - "openai/gpt-4.1-mini", - { - messages: [ - { - role: "user", - content: "What is Cloudflare?", - }, - ], - }, - { - gateway: { - id: "my-gateway", - }, - }, - ); - return Response.json(response); - }, -} satisfies ExportedHandler; -``` - - - -The `gateway` option accepts the following parameters: - -| Parameter | Type | Default | Description | -| --- | --- | --- | --- | -| `id` | `string` | *required* | Name of your [AI Gateway](/ai-gateway/get-started/). Must be in the same account as your Worker. | -| `skipCache` | `boolean` | `false` | Skip the [cache](/ai-gateway/features/caching/) for this request. | -| `cacheTtl` | `number` | — | [Cache TTL](/ai-gateway/features/caching/) in seconds. | -| `cacheKey` | `string` | — | Custom [cache key](/ai-gateway/features/caching/) for this request. | -| `collectLog` | `boolean` | — | Whether to [collect logs](/ai-gateway/observability/logging/) for this request. | -| `metadata` | `object` | — | [Custom metadata](/ai-gateway/observability/custom-metadata/) to attach to the log entry. | - -## Examples - -### Text generation - -#### OpenAI - -```typescript title="src/index.ts" -const response = await env.AI.run( - "openai/gpt-5", - { - messages: [ - { role: "system", content: "You are a helpful assistant." }, - { role: "user", content: "Explain how DNS works in two sentences." }, - ], - }, - { - gateway: { id: "my-gateway" }, - }, -); -``` - -#### Anthropic - -Anthropic models use the [Anthropic Messages format](https://docs.anthropic.com/en/api/messages). Note that `max_tokens` is required and `system` is a top-level field. - -```typescript title="src/index.ts" -const response = await env.AI.run( - "anthropic/claude-sonnet-4", - { - system: "You are a helpful assistant.", - messages: [ - { role: "user", content: "Explain how DNS works in two sentences." }, - ], - max_tokens: 1024, - }, - { - gateway: { id: "my-gateway" }, - }, -); -``` - -#### Google Gemini - -```typescript title="src/index.ts" -const response = await env.AI.run( - "google/gemini-3-flash", - { - messages: [ - { role: "user", content: "Explain how DNS works in two sentences." }, - ], - }, - { - gateway: { id: "my-gateway" }, - }, -); -``` - -### Streaming - -Pass `stream: true` in the input to receive a streaming response: - -```typescript title="src/index.ts" -const response = await env.AI.run( - "openai/gpt-4.1-mini", - { - messages: [ - { role: "user", content: "Write a short poem about the Internet." }, - ], - stream: true, - }, - { - gateway: { id: "my-gateway" }, - }, -); - -return new Response(response, { - headers: { "Content-Type": "text/event-stream" }, -}); -``` - -### Image generation - -```typescript title="src/index.ts" -const response = await env.AI.run( - "cloudflare/image", - { - prompt: "A futuristic city skyline at sunset, digital art", - }, - { - gateway: { id: "my-gateway" }, - }, -); -``` - -### Text-to-speech - -```typescript title="src/index.ts" -const response = await env.AI.run( - "openai/tts-1", - { - text: "Hello! Welcome to Cloudflare AI Gateway.", - voice: "nova", - }, - { - gateway: { id: "my-gateway" }, - }, -); -``` - -### Speech-to-text - -```typescript title="src/index.ts" -const response = await env.AI.run( - "cloudflare/stt", - { - audio: audioArrayBuffer, - }, - { - gateway: { id: "my-gateway" }, - }, -); -``` - -### Video generation - -```typescript title="src/index.ts" -const response = await env.AI.run( - "cloudflare/video", - { - prompt: "A golden retriever playing fetch on a sandy beach at sunset", - }, - { - gateway: { id: "my-gateway" }, - }, -); -``` - -## Supported models - -Model IDs use the `{provider}/{model}` format -- for example, `openai/gpt-5` or `anthropic/claude-sonnet-4`. The provider prefix refers to the model author, not the infrastructure hosting it. - -Browse the full list of available models, including supported tasks and input schemas, in the [model catalog](https://developers.cloudflare.com/ai/models/). - -Cloudflare also provides task-level aliases that automatically route to the best available model: - -- `cloudflare/image` -- Text-to-Image -- `cloudflare/image-edit` -- Image-to-Image -- `cloudflare/video` -- Text-to-Video -- `cloudflare/i2v` -- Image-to-Video -- `cloudflare/stt` -- Speech-to-Text -- `cloudflare/tts` -- Text-to-Speech - -:::note -Workers AI models (prefixed with `@cf/` or `@hf/`) are also supported through `env.AI.run()` and route through AI Gateway when you pass the `gateway` option. Refer to [Workers AI provider](/ai-gateway/usage/providers/workersai/) for details. -::: - -## Accessing the log ID - -After making a request, you can retrieve the AI Gateway log ID for observability: - -```typescript title="src/index.ts" -const response = await env.AI.run("openai/gpt-4.1-mini", input, { - gateway: { id: "my-gateway" }, -}); - -const logId = env.AI.aiGatewayLogId; -``` - -Use the log ID with the [gateway binding methods](/ai-gateway/integrations/worker-binding-methods/) to send feedback, retrieve log details, or update metadata. - -## Related resources - -- [Workers AI binding tutorial](/ai-gateway/integrations/aig-workers-ai-binding/) -- Step-by-step guide to setting up Workers AI with AI Gateway. -- [AI Gateway binding methods](/ai-gateway/integrations/worker-binding-methods/) -- `patchLog`, `getLog`, `getUrl`, and `run` methods. -- [Unified Billing](/ai-gateway/features/unified-billing/) -- Pay for third-party inference with Cloudflare credits. -- [Caching](/ai-gateway/features/caching/) -- Cache responses to reduce latency and cost. diff --git a/src/content/docs/ai-gateway/integrations/aig-workers-ai-binding.mdx b/src/content/docs/ai-gateway/integrations/aig-workers-ai-binding.mdx index 262971fdd76..4e25bedca42 100644 --- a/src/content/docs/ai-gateway/integrations/aig-workers-ai-binding.mdx +++ b/src/content/docs/ai-gateway/integrations/aig-workers-ai-binding.mdx @@ -154,3 +154,7 @@ https://hello-ai..workers.dev Your Worker will be deployed to your custom [`workers.dev`](/workers/configuration/routing/workers-dev/) subdomain. You can now visit the URL to run your AI Worker. By completing this tutorial, you have created a Worker, connected it to Workers AI through an AI Gateway binding, and successfully ran an inference task using the Llama 3.1 model. + +## Next steps + +- [Workers AI binding reference](/ai-gateway/integrations/worker-binding-methods/) -- Call third-party models, access gateway methods, and integrate with AI SDKs. diff --git a/src/content/docs/ai-gateway/integrations/worker-binding-methods.mdx b/src/content/docs/ai-gateway/integrations/worker-binding-methods.mdx index 65152fbbc4f..8df60d20f28 100644 --- a/src/content/docs/ai-gateway/integrations/worker-binding-methods.mdx +++ b/src/content/docs/ai-gateway/integrations/worker-binding-methods.mdx @@ -1,30 +1,35 @@ --- -title: AI Gateway Binding Methods -pcx_content_type: tutorial +title: Workers AI binding +pcx_content_type: reference tags: + - AI - Bindings reviewed: 2025-04-01 description: >- - This guide provides an overview of how to use the latest Cloudflare Workers AI Gateway binding methods. You will learn how to set up an AI Gateway binding, access new methods, and integrate them into your Workers. + Reference for the Workers AI binding with AI Gateway. Call Workers AI and + third-party models with env.AI.run(), access log IDs, and use gateway methods + for feedback, logging, URLs, and universal requests. --- import { Render, PackageManagers } from "~/components"; -This guide provides an overview of how to use the latest Cloudflare Workers AI Gateway binding methods. You will learn how to set up an AI Gateway binding, access new methods, and integrate them into your Workers. +import { WranglerConfig } from "~/components"; + +The Workers AI binding (`env.AI`) lets you call AI models and access AI Gateway features directly from your Worker. This page covers everything you can do with the binding. + +For a step-by-step tutorial on setting up a Worker with AI Gateway, refer to [Get started with Workers AI](/ai-gateway/integrations/aig-workers-ai-binding/). ## 1. Add an AI Binding to your Worker To connect your Worker to Workers AI, add the following to your [Wrangler configuration file](/workers/wrangler/configuration/): -import { WranglerConfig } from "~/components"; - ```jsonc { "ai": { - "binding": "AI" - } + "binding": "AI", + }, } ``` @@ -52,7 +57,7 @@ const resp = await env.AI.run( ); ``` -You can also call third-party models from providers like OpenAI, Anthropic, and Google using the same `env.AI.run()` method. Use the `{provider}/{model}` format for the model ID: +You can also call third-party models using the same `env.AI.run()` method. Use the `{author}/{model}` format for the model ID: ```typescript title="src/index.ts" const resp = await env.AI.run( @@ -68,7 +73,26 @@ const resp = await env.AI.run( ); ``` -For the full list of supported third-party models, refer to [Third-party models via Workers AI binding](/ai-gateway/integrations/aig-workers-ai-binding-third-party/). +Third-party models use [Unified Billing](/ai-gateway/features/unified-billing/). Cloudflare manages the provider credentials and deducts credits from your account for each request. You do not need to supply your own API keys. + +:::note +[BYOK (Bring Your Own Keys)](/ai-gateway/configuration/bring-your-own-keys/) is not supported for third-party models called through the Workers AI binding. If you need to use your own provider keys, use the [AI Gateway REST API](/ai-gateway/usage/providers/) or the [chat completions endpoint](/ai-gateway/usage/chat-completion/) instead. +::: + +Browse the full list of available models in the [model catalog](https://developers.cloudflare.com/ai/models/). + +### Gateway options + +The `gateway` option accepts the following parameters: + +| Parameter | Type | Default | Description | +| ------------ | --------- | ---------- | ------------------------------------------------------------------------------------------------ | +| `id` | `string` | _required_ | Name of your [AI Gateway](/ai-gateway/get-started/). Must be in the same account as your Worker. | +| `skipCache` | `boolean` | `false` | Skip the [cache](/ai-gateway/features/caching/) for this request. | +| `cacheTtl` | `number` | — | [Cache TTL](/ai-gateway/features/caching/) in seconds. | +| `cacheKey` | `string` | — | Custom [cache key](/ai-gateway/features/caching/) for this request. | +| `collectLog` | `boolean` | — | Whether to [collect logs](/ai-gateway/observability/logging/) for this request. | +| `metadata` | `object` | — | [Custom metadata](/ai-gateway/observability/custom-metadata/) to attach to the log entry. | Additionally, you can access the latest request log ID with: @@ -188,14 +212,3 @@ const resp = await gateway.run({ - **Returns**: `Promise` - **Example Use Case**: Perform a [universal request](/ai-gateway/usage/universal/) to any supported provider. - -## Conclusion - -With these AI Gateway binding methods, you can now: - -- Send feedback and update metadata with `patchLog`. -- Retrieve detailed log information using `getLog`. -- Get gateway URLs for direct API access with `getUrl`, making it easy to integrate with popular AI SDKs. -- Execute universal requests to any AI Gateway provider with `run`. - -These methods offer greater flexibility and control over your AI integrations, empowering you to build more sophisticated applications on the Cloudflare Workers platform. diff --git a/src/content/docs/ai-gateway/usage/providers/workersai.mdx b/src/content/docs/ai-gateway/usage/providers/workersai.mdx index 90bf93d85a6..fbcfcb70df0 100644 --- a/src/content/docs/ai-gateway/usage/providers/workersai.mdx +++ b/src/content/docs/ai-gateway/usage/providers/workersai.mdx @@ -12,7 +12,7 @@ import { Render, TypeScriptExample } from "~/components"; Use AI Gateway for analytics, caching, and security on requests to [Workers AI](/workers-ai/). Workers AI integrates seamlessly with AI Gateway, allowing you to execute AI inference via API requests or through an environment binding for Workers scripts. The binding simplifies the process by routing requests through your AI Gateway with minimal setup. :::note -The Workers AI binding can also call models from third-party providers like OpenAI, Anthropic, and Google directly through AI Gateway. Refer to [Third-party models via Workers AI binding](/ai-gateway/integrations/aig-workers-ai-binding-third-party/) for details. +You can also access third-party models through AI Gateway using the Workers AI binding. Refer to [Call third-party models](/ai-gateway/integrations/worker-binding-methods/#call-third-party-models) for details. ::: ## Prerequisites From 8e0cdd40236243f418412cd94d02fecd51e4b74e Mon Sep 17 00:00:00 2001 From: Ming Lu Date: Tue, 14 Apr 2026 14:59:15 -0700 Subject: [PATCH 03/14] [AI Gateway] Restructure Workers AI binding page as reference --- .../add-human-feedback-bindings.mdx | 2 +- .../ai-gateway/features/unified-billing.mdx | 2 +- .../integrations/worker-binding-methods.mdx | 87 +++++++++---------- .../ai-gateway/usage/providers/workersai.mdx | 2 +- 4 files changed, 43 insertions(+), 50 deletions(-) diff --git a/src/content/docs/ai-gateway/evaluations/add-human-feedback-bindings.mdx b/src/content/docs/ai-gateway/evaluations/add-human-feedback-bindings.mdx index 022ef24530b..c1688929247 100644 --- a/src/content/docs/ai-gateway/evaluations/add-human-feedback-bindings.mdx +++ b/src/content/docs/ai-gateway/evaluations/add-human-feedback-bindings.mdx @@ -32,7 +32,7 @@ Let the user interact with or evaluate the AI response. This interaction will in ## 2. Send Human Feedback -Use the [`patchLog()`](/ai-gateway/integrations/worker-binding-methods/#31-patchlog-send-feedback) method to provide feedback for the AI evaluation. +Use the [`patchLog()`](/ai-gateway/integrations/worker-binding-methods/#patchlog) method to provide feedback for the AI evaluation. ```javascript await env.AI.gateway("my-gateway").patchLog(myLogId, { diff --git a/src/content/docs/ai-gateway/features/unified-billing.mdx b/src/content/docs/ai-gateway/features/unified-billing.mdx index 12f3379320a..67f5d8141e0 100644 --- a/src/content/docs/ai-gateway/features/unified-billing.mdx +++ b/src/content/docs/ai-gateway/features/unified-billing.mdx @@ -145,4 +145,4 @@ Unified Billing supports the following providers through their [provider-native #### Workers AI binding -When calling models through the [Workers AI binding](/ai-gateway/integrations/worker-binding-methods/#call-third-party-models) (`env.AI.run()`), Unified Billing is supported for all available third-party models. Browse the full list in the [model catalog](https://developers.cloudflare.com/ai/models/). +When calling models through the [Workers AI binding](/ai-gateway/integrations/worker-binding-methods/#envairun) (`env.AI.run()`), Unified Billing is supported for all available third-party models. Browse the full list in the [model catalog](https://developers.cloudflare.com/ai/models/). diff --git a/src/content/docs/ai-gateway/integrations/worker-binding-methods.mdx b/src/content/docs/ai-gateway/integrations/worker-binding-methods.mdx index 8df60d20f28..a640514569d 100644 --- a/src/content/docs/ai-gateway/integrations/worker-binding-methods.mdx +++ b/src/content/docs/ai-gateway/integrations/worker-binding-methods.mdx @@ -11,17 +11,15 @@ description: >- for feedback, logging, URLs, and universal requests. --- -import { Render, PackageManagers } from "~/components"; +import { Render, WranglerConfig } from "~/components"; -import { WranglerConfig } from "~/components"; +The Workers AI binding (`env.AI`) lets you call AI models and access AI Gateway features directly from your Worker. -The Workers AI binding (`env.AI`) lets you call AI models and access AI Gateway features directly from your Worker. This page covers everything you can do with the binding. +For a step-by-step setup guide, refer to [Get started with Workers AI](/ai-gateway/integrations/aig-workers-ai-binding/). -For a step-by-step tutorial on setting up a Worker with AI Gateway, refer to [Get started with Workers AI](/ai-gateway/integrations/aig-workers-ai-binding/). +## Configuration -## 1. Add an AI Binding to your Worker - -To connect your Worker to Workers AI, add the following to your [Wrangler configuration file](/workers/wrangler/configuration/): +Add an AI binding to your [Wrangler configuration file](/workers/wrangler/configuration/): @@ -35,15 +33,17 @@ To connect your Worker to Workers AI, add the following to your [Wrangler config -This configuration sets up the AI binding accessible in your Worker code as `env.AI`. +The binding is accessible in your Worker code as `env.AI`. -## 2. Basic Usage with Workers AI + Gateway +## `env.AI.run()` + +Runs an inference request through AI Gateway. Accepts Workers AI models (`@cf/` prefix) and third-party models (`{author}/{model}` format). -To perform an inference task using Workers AI and an AI Gateway, you can use the following code: +**Workers AI model:** -```typescript title="src/index.ts" +```typescript const resp = await env.AI.run( "@cf/meta/llama-3.1-8b-instruct", { @@ -57,9 +57,9 @@ const resp = await env.AI.run( ); ``` -You can also call third-party models using the same `env.AI.run()` method. Use the `{author}/{model}` format for the model ID: +**Third-party model:** -```typescript title="src/index.ts" +```typescript const resp = await env.AI.run( "openai/gpt-4.1-mini", { @@ -73,17 +73,17 @@ const resp = await env.AI.run( ); ``` -Third-party models use [Unified Billing](/ai-gateway/features/unified-billing/). Cloudflare manages the provider credentials and deducts credits from your account for each request. You do not need to supply your own API keys. +Third-party models require an AI Gateway and use [Unified Billing](/ai-gateway/features/unified-billing/). Cloudflare manages the provider credentials and deducts credits from your account. You do not need to supply your own API keys. :::note -[BYOK (Bring Your Own Keys)](/ai-gateway/configuration/bring-your-own-keys/) is not supported for third-party models called through the Workers AI binding. If you need to use your own provider keys, use the [AI Gateway REST API](/ai-gateway/usage/providers/) or the [chat completions endpoint](/ai-gateway/usage/chat-completion/) instead. +[BYOK (Bring Your Own Keys)](/ai-gateway/configuration/bring-your-own-keys/) is not supported for third-party models called through the Workers AI binding. To use your own provider keys, use the [AI Gateway REST API](/ai-gateway/usage/providers/) or the [chat completions endpoint](/ai-gateway/usage/chat-completion/) instead. ::: -Browse the full list of available models in the [model catalog](https://developers.cloudflare.com/ai/models/). +Browse available models in the [model catalog](https://developers.cloudflare.com/ai/models/). ### Gateway options -The `gateway` option accepts the following parameters: +The third argument to `env.AI.run()` accepts a `gateway` object with the following parameters: | Parameter | Type | Default | Description | | ------------ | --------- | ---------- | ------------------------------------------------------------------------------------------------ | @@ -94,28 +94,30 @@ The `gateway` option accepts the following parameters: | `collectLog` | `boolean` | — | Whether to [collect logs](/ai-gateway/observability/logging/) for this request. | | `metadata` | `object` | — | [Custom metadata](/ai-gateway/observability/custom-metadata/) to attach to the log entry. | -Additionally, you can access the latest request log ID with: +## `env.AI.aiGatewayLogId` + +Returns the log ID from the most recent `env.AI.run()` request. ```typescript const myLogId = env.AI.aiGatewayLogId; ``` -## 3. Access the Gateway Binding +## `env.AI.gateway()` -You can access your AI Gateway binding using the following code: +Returns a gateway instance for accessing AI Gateway methods directly. ```typescript const gateway = env.AI.gateway("my-gateway"); ``` -Once you have the gateway instance, you can use the following methods: +The gateway instance exposes the following methods. -### 3.1. `patchLog`: Send Feedback +### `patchLog()` -The `patchLog` method allows you to send feedback, score, and metadata for a specific log ID. All object properties are optional, so you can include any combination of the parameters: +Sends feedback, score, and metadata for a specific log entry. All properties in the second argument are optional. ```typescript -gateway.patchLog("my-log-id", { +await gateway.patchLog("my-log-id", { feedback: 1, score: 100, metadata: { @@ -124,41 +126,35 @@ gateway.patchLog("my-log-id", { }); ``` -- **Returns**: `Promise` (Make sure to `await` the request.) -- **Example Use Case**: Update a log entry with user feedback or additional metadata. +**Returns:** `Promise` -### 3.2. `getLog`: Read Log Details +### `getLog()` -The `getLog` method retrieves details of a specific log ID. It returns an object of type `Promise`. If this type is missing, ensure you have run [`wrangler types`](/workers/languages/typescript/#generate-types). +Retrieves details of a specific log entry. If the `AiGatewayLog` type is missing, run [`wrangler types`](/workers/languages/typescript/#generate-types). ```typescript const log = await gateway.getLog("my-log-id"); ``` -- **Returns**: `Promise` -- **Example Use Case**: Retrieve log information for debugging or analytics. +**Returns:** `Promise` -### 3.3. `getUrl`: Get Gateway URLs +### `getUrl()` -The `getUrl` method allows you to retrieve the base URL for your AI Gateway, optionally specifying a provider to get the provider-specific endpoint. +Returns the base URL for your AI Gateway. Pass an optional provider name to get the provider-specific endpoint. ```typescript -// Get the base gateway URL const baseUrl = await gateway.getUrl(); -// Output: https://gateway.ai.cloudflare.com/v1/my-account-id/my-gateway/ +// https://gateway.ai.cloudflare.com/v1/my-account-id/my-gateway/ -// Get a provider-specific URL const openaiUrl = await gateway.getUrl("openai"); -// Output: https://gateway.ai.cloudflare.com/v1/my-account-id/my-gateway/openai +// https://gateway.ai.cloudflare.com/v1/my-account-id/my-gateway/openai ``` -- **Parameters**: Optional `provider` (string or `AIGatewayProviders` enum) -- **Returns**: `Promise` -- **Example Use Case**: Dynamically construct URLs for direct API calls or debugging configurations. +**Parameters:** Optional `provider` (string or `AIGatewayProviders` enum) -#### SDK Integration Examples +**Returns:** `Promise` -The `getUrl` method is particularly useful for integrating with popular AI SDKs: +#### SDK integration examples **OpenAI SDK:** @@ -191,11 +187,9 @@ const anthropic = createAnthropic({ }); ``` -### 3.4. `run`: Universal Requests - -The `run` method allows you to execute universal requests. Users can pass either a single universal request object or an array of them. This method supports all AI Gateway providers. +### `run()` -Refer to the [Universal endpoint documentation](/ai-gateway/usage/universal/) for details about the available inputs. +Executes a [universal request](/ai-gateway/usage/universal/) to any supported provider. Accepts a single request object or an array. ```typescript const resp = await gateway.run({ @@ -210,5 +204,4 @@ const resp = await gateway.run({ }); ``` -- **Returns**: `Promise` -- **Example Use Case**: Perform a [universal request](/ai-gateway/usage/universal/) to any supported provider. +**Returns:** `Promise` diff --git a/src/content/docs/ai-gateway/usage/providers/workersai.mdx b/src/content/docs/ai-gateway/usage/providers/workersai.mdx index fbcfcb70df0..f459f6423ca 100644 --- a/src/content/docs/ai-gateway/usage/providers/workersai.mdx +++ b/src/content/docs/ai-gateway/usage/providers/workersai.mdx @@ -12,7 +12,7 @@ import { Render, TypeScriptExample } from "~/components"; Use AI Gateway for analytics, caching, and security on requests to [Workers AI](/workers-ai/). Workers AI integrates seamlessly with AI Gateway, allowing you to execute AI inference via API requests or through an environment binding for Workers scripts. The binding simplifies the process by routing requests through your AI Gateway with minimal setup. :::note -You can also access third-party models through AI Gateway using the Workers AI binding. Refer to [Call third-party models](/ai-gateway/integrations/worker-binding-methods/#call-third-party-models) for details. +You can also access third-party models through AI Gateway using the Workers AI binding. Refer to the [Workers AI binding reference](/ai-gateway/integrations/worker-binding-methods/#envairun) for details. ::: ## Prerequisites From 1e2c79999192619bd373ed3adf8e05c34cf12227 Mon Sep 17 00:00:00 2001 From: Ming Lu Date: Tue, 14 Apr 2026 15:29:02 -0700 Subject: [PATCH 04/14] [AI Gateway] Rename integration pages for clarity --- .../integrations/aig-workers-ai-binding.mdx | 12 ++++++------ .../integrations/worker-binding-methods.mdx | 4 ++-- .../docs/ai-gateway/usage/providers/workersai.mdx | 2 +- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/src/content/docs/ai-gateway/integrations/aig-workers-ai-binding.mdx b/src/content/docs/ai-gateway/integrations/aig-workers-ai-binding.mdx index 4e25bedca42..de27285e976 100644 --- a/src/content/docs/ai-gateway/integrations/aig-workers-ai-binding.mdx +++ b/src/content/docs/ai-gateway/integrations/aig-workers-ai-binding.mdx @@ -1,5 +1,5 @@ --- -title: Workers AI +title: Set up Workers AI with AI Gateway pcx_content_type: tutorial reviewed: 2024-10-17 description: >- @@ -56,8 +56,8 @@ To bind Workers AI to your Worker, add the following to the end of your [Wrangle ```jsonc { "ai": { - "binding": "AI" - } + "binding": "AI", + }, } ``` @@ -118,7 +118,7 @@ npx wrangler dev You will be prompted to log in after you run `wrangler dev`. When you run `npx wrangler dev`, Wrangler will give you a URL (most likely `localhost:8787`) to review your Worker. After you go to the URL Wrangler provides, you will see a message that resembles the following example: -```json +````json { "response": "A fascinating question!\n\nThe phrase \"Hello, World!\" originates from a simple computer program written in the early days of programming. It is often attributed to Brian Kernighan, a Canadian computer scientist and a pioneer in the field of computer programming.\n\nIn the early 1970s, Kernighan, along with his colleague Dennis Ritchie, were working on the C programming language. They wanted to create a simple program that would output a message to the screen to demonstrate the basic structure of a program. They chose the phrase \"Hello, World!\" because it was a simple and recognizable message that would illustrate how a program could print text to the screen.\n\nThe exact code was written in the 5th edition of Kernighan and Ritchie's book \"The C Programming Language,\" published in 1988. The code, literally known as \"Hello, World!\" is as follows:\n\n``` main() @@ -127,7 +127,7 @@ main() } ```\n\nThis code is still often used as a starting point for learning programming languages, as it demonstrates how to output a simple message to the console.\n\nThe phrase \"Hello, World!\" has since become a catch-all phrase to indicate the start of a new program or a small test program, and is widely used in computer science and programming education.\n\nSincerely, I'm glad I could help clarify the origin of this iconic phrase for you!" } -``` +```` ## 5. Deploy your AI Worker @@ -157,4 +157,4 @@ By completing this tutorial, you have created a Worker, connected it to Workers ## Next steps -- [Workers AI binding reference](/ai-gateway/integrations/worker-binding-methods/) -- Call third-party models, access gateway methods, and integrate with AI SDKs. +- [Binding reference](/ai-gateway/integrations/worker-binding-methods/) — Call third-party models, access gateway methods, and integrate with AI SDKs. diff --git a/src/content/docs/ai-gateway/integrations/worker-binding-methods.mdx b/src/content/docs/ai-gateway/integrations/worker-binding-methods.mdx index a640514569d..81d8574daa9 100644 --- a/src/content/docs/ai-gateway/integrations/worker-binding-methods.mdx +++ b/src/content/docs/ai-gateway/integrations/worker-binding-methods.mdx @@ -1,5 +1,5 @@ --- -title: Workers AI binding +title: Binding reference pcx_content_type: reference tags: - AI @@ -15,7 +15,7 @@ import { Render, WranglerConfig } from "~/components"; The Workers 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 [Get started with Workers AI](/ai-gateway/integrations/aig-workers-ai-binding/). +For a step-by-step setup guide, refer to [Set up Workers AI with AI Gateway](/ai-gateway/integrations/aig-workers-ai-binding/). ## Configuration diff --git a/src/content/docs/ai-gateway/usage/providers/workersai.mdx b/src/content/docs/ai-gateway/usage/providers/workersai.mdx index f459f6423ca..f30333cb51f 100644 --- a/src/content/docs/ai-gateway/usage/providers/workersai.mdx +++ b/src/content/docs/ai-gateway/usage/providers/workersai.mdx @@ -12,7 +12,7 @@ import { Render, TypeScriptExample } from "~/components"; Use AI Gateway for analytics, caching, and security on requests to [Workers AI](/workers-ai/). Workers AI integrates seamlessly with AI Gateway, allowing you to execute AI inference via API requests or through an environment binding for Workers scripts. The binding simplifies the process by routing requests through your AI Gateway with minimal setup. :::note -You can also access third-party models through AI Gateway using the Workers AI binding. Refer to the [Workers AI binding reference](/ai-gateway/integrations/worker-binding-methods/#envairun) for details. +You can also access third-party models through AI Gateway using the Workers AI binding. Refer to the [binding reference](/ai-gateway/integrations/worker-binding-methods/#envairun) for details. ::: ## Prerequisites From c49f402cce0448462d4b5544b81882ec101ff82c Mon Sep 17 00:00:00 2001 From: Ming Lu Date: Tue, 14 Apr 2026 15:34:38 -0700 Subject: [PATCH 05/14] [AI Gateway] Restructure Unified Billing to present Workers AI binding and HTTP API as equal paths --- .../ai-gateway/features/unified-billing.mdx | 50 ++++++++++++------- 1 file changed, 31 insertions(+), 19 deletions(-) diff --git a/src/content/docs/ai-gateway/features/unified-billing.mdx b/src/content/docs/ai-gateway/features/unified-billing.mdx index 67f5d8141e0..4f82b9b916e 100644 --- a/src/content/docs/ai-gateway/features/unified-billing.mdx +++ b/src/content/docs/ai-gateway/features/unified-billing.mdx @@ -49,9 +49,29 @@ When your balance falls below the set threshold, AI Gateway will automatically a ## Use Unified Billing -Call any supported provider without passing an API Key. The request will automatically use Cloudflare's key and deduct credits from your account. +Unified Billing works in two ways: through the Workers AI binding or through the HTTP API. Both deduct credits from your account automatically without requiring provider API keys. + +### Workers AI binding + +Call any model listed in the [model catalog](https://developers.cloudflare.com/ai/models/) using `env.AI.run()`. This includes both Workers AI models and third-party models from providers like OpenAI, Anthropic, and Google. + +```typescript +const resp = await env.AI.run( + "openai/gpt-4.1-mini", + { + messages: [{ role: "user", content: "What is Cloudflare?" }], + }, + { + gateway: { id: "my-gateway" }, + }, +); +``` + +Refer to the [binding reference](/ai-gateway/integrations/worker-binding-methods/) for the full API surface. + +### HTTP API -For example, you can use the Unified API: +Call a supported provider through the AI Gateway REST API without passing a provider API key. Use the `cf-aig-authorization` header to authenticate with your Cloudflare API token. ```bash curl -X POST https://gateway.ai.cloudflare.com/v1/$CLOUDFLARE_ACCOUNT_ID/default/compat/chat/completions \ @@ -70,6 +90,15 @@ curl -X POST https://gateway.ai.cloudflare.com/v1/$CLOUDFLARE_ACCOUNT_ID/default The `default` gateway is created automatically on your first request. Replace `default` with a specific gateway ID if you have already created one. +The HTTP API supports the following providers through their [provider-native endpoints](/ai-gateway/usage/providers/): + +- [OpenAI](/ai-gateway/usage/providers/openai/) +- [Anthropic](/ai-gateway/usage/providers/anthropic/) +- [Google AI Studio](/ai-gateway/usage/providers/google-ai-studio/) +- [Google Vertex AI](/ai-gateway/usage/providers/vertex/) +- [xAI](/ai-gateway/usage/providers/grok/) +- [Groq](/ai-gateway/usage/providers/groq/) + ### Spend limits Set spend limits to prevent unexpected charges on your loaded credits. You can define daily, weekly, or monthly limits. When a limit is reached, the AI Gateway automatically stops processing requests until the period resets or you increase the limit. @@ -129,20 +158,3 @@ curl -X POST https://gateway.ai.cloudflare.com/v1/$CLOUDFLARE_ACCOUNT_ID/{gatewa ] }' ``` - -### Supported providers - -#### Provider-native endpoints - -Unified Billing supports the following providers through their [provider-native endpoints](/ai-gateway/usage/providers/): - -- [OpenAI](/ai-gateway/usage/providers/openai/) -- [Anthropic](/ai-gateway/usage/providers/anthropic/) -- [Google AI Studio](/ai-gateway/usage/providers/google-ai-studio/) -- [Google Vertex AI](/ai-gateway/usage/providers/vertex/) -- [xAI](/ai-gateway/usage/providers/grok/) -- [Groq](/ai-gateway/usage/providers/groq/) - -#### Workers AI binding - -When calling models through the [Workers AI binding](/ai-gateway/integrations/worker-binding-methods/#envairun) (`env.AI.run()`), Unified Billing is supported for all available third-party models. Browse the full list in the [model catalog](https://developers.cloudflare.com/ai/models/). From 890d111b9772d4dad1589a50f06ddbc954767e93 Mon Sep 17 00:00:00 2001 From: Ming Lu Date: Tue, 14 Apr 2026 15:38:44 -0700 Subject: [PATCH 06/14] [AI Gateway] Mention Unified API alongside provider-native endpoints for HTTP API billing --- src/content/docs/ai-gateway/features/unified-billing.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/ai-gateway/features/unified-billing.mdx b/src/content/docs/ai-gateway/features/unified-billing.mdx index 4f82b9b916e..88dfe74cf7a 100644 --- a/src/content/docs/ai-gateway/features/unified-billing.mdx +++ b/src/content/docs/ai-gateway/features/unified-billing.mdx @@ -90,7 +90,7 @@ curl -X POST https://gateway.ai.cloudflare.com/v1/$CLOUDFLARE_ACCOUNT_ID/default The `default` gateway is created automatically on your first request. Replace `default` with a specific gateway ID if you have already created one. -The HTTP API supports the following providers through their [provider-native endpoints](/ai-gateway/usage/providers/): +The HTTP API supports the following providers through [provider-native endpoints](/ai-gateway/usage/providers/) and the [Unified API (chat completions)](/ai-gateway/usage/chat-completion/): - [OpenAI](/ai-gateway/usage/providers/openai/) - [Anthropic](/ai-gateway/usage/providers/anthropic/) From 3d4950e6f2a74136b6de00adbc88f1a3bc0f4add Mon Sep 17 00:00:00 2001 From: Ming Lu Date: Tue, 14 Apr 2026 21:00:36 -0700 Subject: [PATCH 07/14] [AI Gateway] Rename binding reference page and reorder integrations sidebar --- .../docs/ai-gateway/integrations/agents.mdx | 3 +-- .../integrations/aig-workers-ai-binding.mdx | 5 +++-- .../ai-gateway/integrations/vercel-ai-sdk.mdx | 17 +++++------------ .../integrations/worker-binding-methods.mdx | 5 +++-- 4 files changed, 12 insertions(+), 18 deletions(-) diff --git a/src/content/docs/ai-gateway/integrations/agents.mdx b/src/content/docs/ai-gateway/integrations/agents.mdx index 235f6ea5ebf..d31218d28d6 100644 --- a/src/content/docs/ai-gateway/integrations/agents.mdx +++ b/src/content/docs/ai-gateway/integrations/agents.mdx @@ -3,8 +3,7 @@ pcx_content_type: navigation title: Agents external_link: /agents/ sidebar: - order: 10 + order: 3 head: [] description: Build AI-powered Agents on Cloudflare --- - diff --git a/src/content/docs/ai-gateway/integrations/aig-workers-ai-binding.mdx b/src/content/docs/ai-gateway/integrations/aig-workers-ai-binding.mdx index de27285e976..c3a72b9b7f8 100644 --- a/src/content/docs/ai-gateway/integrations/aig-workers-ai-binding.mdx +++ b/src/content/docs/ai-gateway/integrations/aig-workers-ai-binding.mdx @@ -1,7 +1,8 @@ --- title: Set up Workers AI with AI Gateway pcx_content_type: tutorial -reviewed: 2024-10-17 +sidebar: + order: 4 description: >- This guide will walk you through setting up and deploying a Workers AI project. You will use Workers, an AI Gateway binding, and a large language model (LLM) to deploy your first AI-powered application on the Cloudflare global network. --- @@ -157,4 +158,4 @@ By completing this tutorial, you have created a Worker, connected it to Workers ## Next steps -- [Binding reference](/ai-gateway/integrations/worker-binding-methods/) — Call third-party models, access gateway methods, and integrate with AI SDKs. +- [Workers bindings](/ai-gateway/integrations/worker-binding-methods/) — Call third-party models, access gateway methods, and integrate with AI SDKs. diff --git a/src/content/docs/ai-gateway/integrations/vercel-ai-sdk.mdx b/src/content/docs/ai-gateway/integrations/vercel-ai-sdk.mdx index 54f35ecb57d..299e2e80ca7 100644 --- a/src/content/docs/ai-gateway/integrations/vercel-ai-sdk.mdx +++ b/src/content/docs/ai-gateway/integrations/vercel-ai-sdk.mdx @@ -2,14 +2,10 @@ title: Vercel AI SDK pcx_content_type: configuration sidebar: - order: 3 + order: 2 --- -import { - Details, - Tabs, - TabItem -} from "~/components"; +import { Details, Tabs, TabItem } from "~/components"; import CodeSnippets from "~/components/ai-gateway/code-examples.astro"; The [Vercel AI SDK](https://sdk.vercel.ai/) is a TypeScript library for building AI applications. The SDK supports many different AI providers, tools for streaming completions, and more. @@ -21,7 +17,7 @@ To use Cloudflare AI Gateway with Vercel AI SDK, you will need to use the `ai-ga npm install ai-gateway-provider ``` -## Examples +## Examples @@ -31,10 +27,7 @@ To specify model or provider fallbacks to handle request failures and ensure rel ```js title="" const { text } = await generateText({ - model: aigateway([ - openai.chat("gpt-5.1"), anthropic("claude-sonnet-4-5") - ]), - prompt: 'Write a vegetarian lasagna recipe for 4 people.', + model: aigateway([openai.chat("gpt-5.1"), anthropic("claude-sonnet-4-5")]), + prompt: "Write a vegetarian lasagna recipe for 4 people.", }); ``` - diff --git a/src/content/docs/ai-gateway/integrations/worker-binding-methods.mdx b/src/content/docs/ai-gateway/integrations/worker-binding-methods.mdx index 81d8574daa9..8d73c67b366 100644 --- a/src/content/docs/ai-gateway/integrations/worker-binding-methods.mdx +++ b/src/content/docs/ai-gateway/integrations/worker-binding-methods.mdx @@ -1,10 +1,11 @@ --- -title: Binding reference +title: Workers Bindings pcx_content_type: reference +sidebar: + order: 1 tags: - AI - Bindings -reviewed: 2025-04-01 description: >- Reference for the Workers AI binding with AI Gateway. Call Workers AI and third-party models with env.AI.run(), access log IDs, and use gateway methods From d3980d766881c045d3b46c2f629fb9ceb5b994ac Mon Sep 17 00:00:00 2001 From: Ming Lu Date: Tue, 14 Apr 2026 21:03:09 -0700 Subject: [PATCH 08/14] [AI Gateway] Add workers-ai-provider example for calling third-party models via gateway --- .../ai-gateway/integrations/vercel-ai-sdk.mdx | 29 ++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/src/content/docs/ai-gateway/integrations/vercel-ai-sdk.mdx b/src/content/docs/ai-gateway/integrations/vercel-ai-sdk.mdx index 299e2e80ca7..390d9281714 100644 --- a/src/content/docs/ai-gateway/integrations/vercel-ai-sdk.mdx +++ b/src/content/docs/ai-gateway/integrations/vercel-ai-sdk.mdx @@ -21,7 +21,34 @@ npm install ai-gateway-provider -### Fallback Providers +### Workers AI binding with third-party models + +If you are already using the [`workers-ai-provider`](https://www.npmjs.com/package/workers-ai-provider) package, you can route requests through AI Gateway to call third-party models without needing separate provider SDKs. Pass a `gateway` option with your gateway ID to `createWorkersAI`: + +```ts +import { createWorkersAI } from "workers-ai-provider"; +import { streamText } from "ai"; + +export default { + async fetch(request, env) { + const workersai = createWorkersAI({ + binding: env.AI, + gateway: { id: "my-gateway" }, + }); + + const result = streamText({ + model: workersai("openai/gpt-4o"), + messages: [{ role: "user", content: "Write a short story" }], + }); + + return result.toTextStreamResponse(); + }, +} satisfies ExportedHandler; +``` + +This works with any [supported provider and model](/ai-gateway/providers/) available through AI Gateway. + +### Fallback providers To specify model or provider fallbacks to handle request failures and ensure reliability, you can pass an array of models to the `model` option. From 27df89c4bc597bdfa52f1b6f67a238f6339c64da Mon Sep 17 00:00:00 2001 From: Ming Lu Date: Tue, 14 Apr 2026 21:07:13 -0700 Subject: [PATCH 09/14] [AI Gateway] Revert unintentional formatting changes in Vercel AI SDK page --- .../ai-gateway/integrations/vercel-ai-sdk.mdx | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/src/content/docs/ai-gateway/integrations/vercel-ai-sdk.mdx b/src/content/docs/ai-gateway/integrations/vercel-ai-sdk.mdx index 390d9281714..50d4758f939 100644 --- a/src/content/docs/ai-gateway/integrations/vercel-ai-sdk.mdx +++ b/src/content/docs/ai-gateway/integrations/vercel-ai-sdk.mdx @@ -5,7 +5,11 @@ sidebar: order: 2 --- -import { Details, Tabs, TabItem } from "~/components"; +import { + Details, + Tabs, + TabItem +} from "~/components"; import CodeSnippets from "~/components/ai-gateway/code-examples.astro"; The [Vercel AI SDK](https://sdk.vercel.ai/) is a TypeScript library for building AI applications. The SDK supports many different AI providers, tools for streaming completions, and more. @@ -17,7 +21,7 @@ To use Cloudflare AI Gateway with Vercel AI SDK, you will need to use the `ai-ga npm install ai-gateway-provider ``` -## Examples +## Examples @@ -48,13 +52,16 @@ export default { This works with any [supported provider and model](/ai-gateway/providers/) available through AI Gateway. -### Fallback providers +### Fallback Providers To specify model or provider fallbacks to handle request failures and ensure reliability, you can pass an array of models to the `model` option. ```js title="" const { text } = await generateText({ - model: aigateway([openai.chat("gpt-5.1"), anthropic("claude-sonnet-4-5")]), - prompt: "Write a vegetarian lasagna recipe for 4 people.", + model: aigateway([ + openai.chat("gpt-5.1"), anthropic("claude-sonnet-4-5") + ]), + prompt: 'Write a vegetarian lasagna recipe for 4 people.', }); ``` + From bbabcc3bf1bcb1fe7c7962a436cbaa6367765c68 Mon Sep 17 00:00:00 2001 From: Ming Lu Date: Wed, 15 Apr 2026 09:32:11 -0700 Subject: [PATCH 10/14] [AI Gateway] Rename Workers AI binding to AI binding per review feedback --- .../ai-gateway/features/unified-billing.mdx | 4 ++-- .../ai-gateway/integrations/vercel-ai-sdk.mdx | 19 ++++++------------- .../integrations/worker-binding-methods.mdx | 6 +++--- .../ai-gateway/usage/providers/workersai.mdx | 2 +- 4 files changed, 12 insertions(+), 19 deletions(-) diff --git a/src/content/docs/ai-gateway/features/unified-billing.mdx b/src/content/docs/ai-gateway/features/unified-billing.mdx index 88dfe74cf7a..30afade6500 100644 --- a/src/content/docs/ai-gateway/features/unified-billing.mdx +++ b/src/content/docs/ai-gateway/features/unified-billing.mdx @@ -49,9 +49,9 @@ When your balance falls below the set threshold, AI Gateway will automatically a ## Use Unified Billing -Unified Billing works in two ways: through the Workers AI binding or through the HTTP API. Both deduct credits from your account automatically without requiring provider API keys. +Unified Billing works in two ways: through the AI binding or through the HTTP API. Both deduct credits from your account automatically without requiring provider API keys. -### Workers AI binding +### AI binding Call any model listed in the [model catalog](https://developers.cloudflare.com/ai/models/) using `env.AI.run()`. This includes both Workers AI models and third-party models from providers like OpenAI, Anthropic, and Google. diff --git a/src/content/docs/ai-gateway/integrations/vercel-ai-sdk.mdx b/src/content/docs/ai-gateway/integrations/vercel-ai-sdk.mdx index 50d4758f939..546ba97fc64 100644 --- a/src/content/docs/ai-gateway/integrations/vercel-ai-sdk.mdx +++ b/src/content/docs/ai-gateway/integrations/vercel-ai-sdk.mdx @@ -5,11 +5,7 @@ sidebar: order: 2 --- -import { - Details, - Tabs, - TabItem -} from "~/components"; +import { Details, Tabs, TabItem } from "~/components"; import CodeSnippets from "~/components/ai-gateway/code-examples.astro"; The [Vercel AI SDK](https://sdk.vercel.ai/) is a TypeScript library for building AI applications. The SDK supports many different AI providers, tools for streaming completions, and more. @@ -21,11 +17,11 @@ To use Cloudflare AI Gateway with Vercel AI SDK, you will need to use the `ai-ga npm install ai-gateway-provider ``` -## Examples +## Examples -### Workers AI binding with third-party models +### AI binding with third-party models If you are already using the [`workers-ai-provider`](https://www.npmjs.com/package/workers-ai-provider) package, you can route requests through AI Gateway to call third-party models without needing separate provider SDKs. Pass a `gateway` option with your gateway ID to `createWorkersAI`: @@ -50,7 +46,7 @@ export default { } satisfies ExportedHandler; ``` -This works with any [supported provider and model](/ai-gateway/providers/) available through AI Gateway. +This works with any [supported provider and model](/ai-gateway/usage/providers/) available through AI Gateway. ### Fallback Providers @@ -58,10 +54,7 @@ To specify model or provider fallbacks to handle request failures and ensure rel ```js title="" const { text } = await generateText({ - model: aigateway([ - openai.chat("gpt-5.1"), anthropic("claude-sonnet-4-5") - ]), - prompt: 'Write a vegetarian lasagna recipe for 4 people.', + model: aigateway([openai.chat("gpt-5.1"), anthropic("claude-sonnet-4-5")]), + prompt: "Write a vegetarian lasagna recipe for 4 people.", }); ``` - diff --git a/src/content/docs/ai-gateway/integrations/worker-binding-methods.mdx b/src/content/docs/ai-gateway/integrations/worker-binding-methods.mdx index 8d73c67b366..9573d4aa44b 100644 --- a/src/content/docs/ai-gateway/integrations/worker-binding-methods.mdx +++ b/src/content/docs/ai-gateway/integrations/worker-binding-methods.mdx @@ -7,14 +7,14 @@ tags: - AI - Bindings description: >- - Reference for the Workers AI binding with AI Gateway. Call Workers AI and + Reference for the AI binding with AI Gateway. Call Workers AI and third-party models with env.AI.run(), access log IDs, and use gateway methods for feedback, logging, URLs, and universal requests. --- import { Render, WranglerConfig } from "~/components"; -The Workers AI binding (`env.AI`) lets you call AI models and access AI Gateway features directly from your Worker. +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](/ai-gateway/integrations/aig-workers-ai-binding/). @@ -77,7 +77,7 @@ const resp = await env.AI.run( Third-party models require an AI Gateway and use [Unified Billing](/ai-gateway/features/unified-billing/). Cloudflare manages the provider credentials and deducts credits from your account. You do not need to supply your own API keys. :::note -[BYOK (Bring Your Own Keys)](/ai-gateway/configuration/bring-your-own-keys/) is not supported for third-party models called through the Workers AI binding. To use your own provider keys, use the [AI Gateway REST API](/ai-gateway/usage/providers/) or the [chat completions endpoint](/ai-gateway/usage/chat-completion/) instead. +[BYOK (Bring Your Own Keys)](/ai-gateway/configuration/bring-your-own-keys/) is not supported for third-party models called through the AI binding. To use your own provider keys, use the [AI Gateway REST API](/ai-gateway/usage/providers/) or the [chat completions endpoint](/ai-gateway/usage/chat-completion/) instead. ::: Browse available models in the [model catalog](https://developers.cloudflare.com/ai/models/). diff --git a/src/content/docs/ai-gateway/usage/providers/workersai.mdx b/src/content/docs/ai-gateway/usage/providers/workersai.mdx index f30333cb51f..4adb342131b 100644 --- a/src/content/docs/ai-gateway/usage/providers/workersai.mdx +++ b/src/content/docs/ai-gateway/usage/providers/workersai.mdx @@ -12,7 +12,7 @@ import { Render, TypeScriptExample } from "~/components"; Use AI Gateway for analytics, caching, and security on requests to [Workers AI](/workers-ai/). Workers AI integrates seamlessly with AI Gateway, allowing you to execute AI inference via API requests or through an environment binding for Workers scripts. The binding simplifies the process by routing requests through your AI Gateway with minimal setup. :::note -You can also access third-party models through AI Gateway using the Workers AI binding. Refer to the [binding reference](/ai-gateway/integrations/worker-binding-methods/#envairun) for details. +You can also access third-party models through AI Gateway using the AI binding. Refer to the [binding reference](/ai-gateway/integrations/worker-binding-methods/#envairun) for details. ::: ## Prerequisites From 0f9af8dcbdc7a6ef6680402d34eec9bb7fa9c4d5 Mon Sep 17 00:00:00 2001 From: MC Date: Wed, 15 Apr 2026 14:31:18 -0400 Subject: [PATCH 11/14] Update src/content/docs/ai-gateway/integrations/worker-binding-methods.mdx Co-authored-by: ask-bonk[bot] <249159057+ask-bonk[bot]@users.noreply.github.com> --- .../docs/ai-gateway/integrations/worker-binding-methods.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/ai-gateway/integrations/worker-binding-methods.mdx b/src/content/docs/ai-gateway/integrations/worker-binding-methods.mdx index 9573d4aa44b..a4be8fa3d7f 100644 --- a/src/content/docs/ai-gateway/integrations/worker-binding-methods.mdx +++ b/src/content/docs/ai-gateway/integrations/worker-binding-methods.mdx @@ -46,7 +46,7 @@ Runs an inference request through AI Gateway. Accepts Workers AI models (`@cf/` ```typescript const resp = await env.AI.run( - "@cf/meta/llama-3.1-8b-instruct", + "@cf/moonshotai/kimi-k2.5", { prompt: "tell me a joke", }, From 15c28665dd89c4ef87ebf7a939c83b3de2470c90 Mon Sep 17 00:00:00 2001 From: "ask-bonk[bot]" Date: Wed, 15 Apr 2026 22:18:18 +0000 Subject: [PATCH 12/14] Fixed MDX code block backticks. Co-authored-by: mchenco --- .../integrations/aig-workers-ai-binding.mdx | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/src/content/docs/ai-gateway/integrations/aig-workers-ai-binding.mdx b/src/content/docs/ai-gateway/integrations/aig-workers-ai-binding.mdx index c3a72b9b7f8..9ddb832ab64 100644 --- a/src/content/docs/ai-gateway/integrations/aig-workers-ai-binding.mdx +++ b/src/content/docs/ai-gateway/integrations/aig-workers-ai-binding.mdx @@ -119,16 +119,11 @@ npx wrangler dev You will be prompted to log in after you run `wrangler dev`. When you run `npx wrangler dev`, Wrangler will give you a URL (most likely `localhost:8787`) to review your Worker. After you go to the URL Wrangler provides, you will see a message that resembles the following example: -````json +```json { - "response": "A fascinating question!\n\nThe phrase \"Hello, World!\" originates from a simple computer program written in the early days of programming. It is often attributed to Brian Kernighan, a Canadian computer scientist and a pioneer in the field of computer programming.\n\nIn the early 1970s, Kernighan, along with his colleague Dennis Ritchie, were working on the C programming language. They wanted to create a simple program that would output a message to the screen to demonstrate the basic structure of a program. They chose the phrase \"Hello, World!\" because it was a simple and recognizable message that would illustrate how a program could print text to the screen.\n\nThe exact code was written in the 5th edition of Kernighan and Ritchie's book \"The C Programming Language,\" published in 1988. The code, literally known as \"Hello, World!\" is as follows:\n\n``` -main() -{ - printf(\"Hello, World!\"); -} -```\n\nThis code is still often used as a starting point for learning programming languages, as it demonstrates how to output a simple message to the console.\n\nThe phrase \"Hello, World!\" has since become a catch-all phrase to indicate the start of a new program or a small test program, and is widely used in computer science and programming education.\n\nSincerely, I'm glad I could help clarify the origin of this iconic phrase for you!" + "response": "A fascinating question!\n\nThe phrase \"Hello, World!\" originates from a simple computer program written in the early days of programming. It is often attributed to Brian Kernighan, a Canadian computer scientist and a pioneer in the field of computer programming.\n\nIn the early 1970s, Kernighan, along with his colleague Dennis Ritchie, were working on the C programming language. They wanted to create a simple program that would output a message to the screen to demonstrate the basic structure of a program. They chose the phrase \"Hello, World!\" because it was a simple and recognizable message that would illustrate how a program could print text to the screen.\n\nThe exact code was written in the 5th edition of Kernighan and Ritchie's book \"The C Programming Language,\" published in 1988. The code, literally known as \"Hello, World!\" is as follows:\n\n main()\n {\n printf(\"Hello, World!\");\n }\n\nThis code is still often used as a starting point for learning programming languages, as it demonstrates how to output a simple message to the console.\n\nThe phrase \"Hello, World!\" has since become a catch-all phrase to indicate the start of a new program or a small test program, and is widely used in computer science and programming education.\n\nSincerely, I'm glad I could help clarify the origin of this iconic phrase for you!" } -```` +``` ## 5. Deploy your AI Worker From b2923f83d340b4ffb490cb7fa2295a9b1623d89c Mon Sep 17 00:00:00 2001 From: Ming Lu Date: Wed, 15 Apr 2026 17:19:14 -0700 Subject: [PATCH 13/14] chore: trigger CI From 18d1ae39d4ef3e7f2f02e41de56fc70ad355419b Mon Sep 17 00:00:00 2001 From: Ming Lu Date: Wed, 15 Apr 2026 18:51:32 -0700 Subject: [PATCH 14/14] [AI Gateway] Clarify that Workers AI models are not charged via Unified Billing --- src/content/docs/ai-gateway/features/unified-billing.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/content/docs/ai-gateway/features/unified-billing.mdx b/src/content/docs/ai-gateway/features/unified-billing.mdx index 30afade6500..eb308f481ea 100644 --- a/src/content/docs/ai-gateway/features/unified-billing.mdx +++ b/src/content/docs/ai-gateway/features/unified-billing.mdx @@ -51,6 +51,10 @@ When your balance falls below the set threshold, AI Gateway will automatically a Unified Billing works in two ways: through the AI binding or through the HTTP API. Both deduct credits from your account automatically without requiring provider API keys. +:::note +Workers AI models (models prefixed with `@cf/`) routed through AI Gateway are not charged via Unified Billing. These models are billed through [Workers AI pricing](/workers-ai/platform/pricing/) instead. Unified Billing only applies to third-party provider models (such as OpenAI, Anthropic, and Google AI Studio). +::: + ### AI binding Call any model listed in the [model catalog](https://developers.cloudflare.com/ai/models/) using `env.AI.run()`. This includes both Workers AI models and third-party models from providers like OpenAI, Anthropic, and Google.