diff --git a/src/content/changelog/ai-gateway/2026-08-07-workers-ai-unified-billing.mdx b/src/content/changelog/ai-gateway/2026-08-07-workers-ai-unified-billing.mdx new file mode 100644 index 00000000000..f8d2e77ac58 --- /dev/null +++ b/src/content/changelog/ai-gateway/2026-08-07-workers-ai-unified-billing.mdx @@ -0,0 +1,50 @@ +--- +title: Workers AI and AI Gateway unify model access and billing +description: Call Workers AI and third-party models through shared APIs, observability, and prepaid billing. +products: + - ai-gateway + - workers-ai +date: 2026-08-07 +--- + +import { TypeScriptExample } from "~/components"; + +Workers AI and AI Gateway now provide a unified path for accessing models and managing inference traffic. Use the same AI binding and REST API to call models hosted on Workers AI or by supported third-party providers, with AI Gateway providing observability, logging, caching, security, and billing controls. + +## Unified entrypoints and observability + +The [AI binding](/ai-gateway/usage/worker-binding-methods/) supports both Workers AI and third-party models through `env.AI.run()`. The [REST API](/ai-gateway/usage/rest-api/) provides shared `/ai/` endpoints with Cloudflare authentication across providers. + +Route a Workers AI request through AI Gateway by specifying a gateway ID. Use `default` to automatically create a gateway on the first authenticated request, or specify an existing gateway to separate applications and workloads: + + + +```ts +const response = await env.AI.run( + "@cf/zai-org/glm-5.2", + { + messages: [{ role: "user", content: "What is the capital of France?" }], + }, + { + gateway: { id: "default" }, + }, +); +``` + + + +Requests routed through AI Gateway can be logged and included in analytics for request volume, errors, latency, token usage, and costs. You can also configure controls such as caching, rate limiting, and request retries on the gateway. + +## Unified billing and higher rate limits + +You can now use prepaid [AI Gateway credits](/ai-gateway/features/unified-billing/) to pay for Workers AI inference. This provides one credit balance for Workers AI and supported third-party model providers. To use credits for Workers AI, set the gateway's [Workers AI billing setting](/ai-gateway/configuration/manage-gateway/#configure-workers-ai-billing) to **Unified billing**. Workers AI requests routed through that gateway deduct from your credit balance in real time. + +Prepaid credits also provide access to the following Workers AI frontier models without requiring the Workers Paid plan. Each frontier Workers AI model has a rate limit of 50 requests per minute per account, per model when billed with AI Gateway credits, compared to 20 requests per minute through standard Workers AI billing: + +- [`@cf/moonshotai/kimi-k2.6`](/workers-ai/models/kimi-k2.6/) +- [`@cf/moonshotai/kimi-k2.7-code`](/workers-ai/models/kimi-k2.7-code/) +- [`@cf/zai-org/glm-5.2`](/workers-ai/models/glm-5.2/) + +These limits are designed for typical agentic and coding workloads, where requests to frontier models can take longer to complete. + +For details, refer to [Workers AI limits](/workers-ai/platform/limits/), [Workers AI pricing](/workers-ai/platform/pricing/), [Unified Billing](/ai-gateway/features/unified-billing/), and the [AI Gateway model catalog](/ai/models/). diff --git a/src/content/docs/ai-gateway/configuration/manage-gateway.mdx b/src/content/docs/ai-gateway/configuration/manage-gateway.mdx index 2f122e4e19f..cde19b25e7b 100644 --- a/src/content/docs/ai-gateway/configuration/manage-gateway.mdx +++ b/src/content/docs/ai-gateway/configuration/manage-gateway.mdx @@ -24,12 +24,13 @@ The request that triggers auto-creation must be authenticated. When using the [R The auto-created default gateway uses the following settings: -| Setting | Default value | -| -------------- | -------------- | -| Authentication | On | -| Log collection | On | -| Caching | Off (TTL of 0) | -| Rate limiting | Off | +| Setting | Default value | +| ------------------ | ---------------- | +| Authentication | On | +| Log collection | On | +| Caching | Off (TTL of 0) | +| Rate limiting | Off | +| Workers AI billing | Standard billing | After creation, you can edit the default gateway settings like any other gateway. If you delete the default gateway, sending a new authenticated request to the `default` gateway ID auto-creates it again. @@ -51,6 +52,20 @@ For more details about what settings are available for editing, refer to [Config ::: +### Configure Workers AI billing + +By default, Workers AI requests use **Standard billing**, which charges your Cloudflare account at the end of each billing cycle. + +To use prepaid AI Gateway credits for Workers AI requests: + +1. [Load credits](/ai-gateway/features/unified-billing/#load-credits) into your Cloudflare account. +2. In the Cloudflare dashboard, go to **AI** > **AI Gateway** and select your gateway. +3. Go to **Settings** and find **Workers AI Billing**. +4. Select **Unified billing**. +5. Select **Save**. + +Workers AI requests routed through this gateway will deduct from your AI Gateway credit balance in real time. + ## Retry requests You can configure your gateway to automatically retry failed requests to upstream providers. This is useful when you do not control the client and cannot implement client-side retries or backoff logic. diff --git a/src/content/docs/ai-gateway/features/unified-billing.mdx b/src/content/docs/ai-gateway/features/unified-billing.mdx index 19d800feb78..d13ffb55d02 100644 --- a/src/content/docs/ai-gateway/features/unified-billing.mdx +++ b/src/content/docs/ai-gateway/features/unified-billing.mdx @@ -13,7 +13,7 @@ products: import { DashButton, Render, TabItem, Tabs } from "~/components"; -Unified Billing allows users to connect to various AI providers (such as OpenAI, Anthropic, and Google AI Studio) and receive a single Cloudflare bill. To use Unified Billing, you must purchase and load credits into your Cloudflare account in the Cloudflare dashboard, which you can then spend with AI Gateway. +Unified Billing allows users to call Workers AI and connect to various AI providers (such as OpenAI, Anthropic, and Google AI Studio) and receive a single Cloudflare bill. To use Unified Billing, you must purchase and load credits into your Cloudflare account in the Cloudflare dashboard, which you can then spend with AI Gateway. A 5% fee is applied to all credits purchased through Unified Billing. For example, a $100 credit purchase will result in a $105 charge. Inference pricing from providers is passed through with no markup — you pay the same per-token rates as you would directly with the provider. @@ -25,6 +25,7 @@ In rare instances, your credit balance may go negative. If this happens, Cloudfl - Ensure your Cloudflare account has [sufficient credits loaded](#load-credits). - Ensure you have [authenticated](/ai-gateway/configuration/authentication/) your AI Gateway. +- To use credits for Workers AI, set your gateway's **Workers AI Billing** setting to **Unified billing**. ## Load credits @@ -73,9 +74,7 @@ The `cf-aig-byok-alias` header selects a non-default alias only on [direct provi 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). -::: +To use credits for Workers AI, [configure the gateway's Workers AI billing setting](/ai-gateway/configuration/manage-gateway/#configure-workers-ai-billing) as **Unified billing**. Workers AI requests routed through that gateway deduct from your prepaid credit balance in real time. In the AI binding, include the gateway ID in the third argument to `env.AI.run()`. For REST API requests, include the `cf-aig-gateway-id` header. Prepaid credits provide access to Workers AI models that otherwise require the Workers Paid plan and provide [higher rate limits for frontier models](/workers-ai/platform/limits/#frontier-models). ### AI binding diff --git a/src/content/docs/ai-gateway/get-started.mdx b/src/content/docs/ai-gateway/get-started.mdx index 70a3cba708c..971fdd6f7f7 100644 --- a/src/content/docs/ai-gateway/get-started.mdx +++ b/src/content/docs/ai-gateway/get-started.mdx @@ -49,6 +49,8 @@ curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ }' ``` +The `cf-aig-gateway-id: default` header routes this Workers AI request through your account's default gateway. If the gateway does not exist, AI Gateway creates it on the first authenticated request. Routing through the gateway provides unified logging, analytics, caching, rate limiting, and security controls. The auto-created gateway uses **Standard billing** by default. To pay with prepaid AI Gateway credits, [set its Workers AI billing setting to **Unified billing**](/ai-gateway/configuration/manage-gateway/#configure-workers-ai-billing). + :::note For third-party models, you do not need to specify a gateway — AI Gateway uses `default` as the gateway ID and automatically creates it on the first authenticated request. Workers AI requests always require the `cf-aig-gateway-id` header. For more details, refer to [Default gateway](/ai-gateway/configuration/manage-gateway/#default-gateway). ::: @@ -65,7 +67,7 @@ You can also create gateways manually with a custom name and configuration throu Authenticate with your upstream AI provider using one of the following options: -- **Unified Billing:** Use the AI Gateway billing to pay for and authenticate your inference requests. Refer to [Unified Billing](/ai-gateway/features/unified-billing/). +- **Unified Billing:** Use prepaid AI Gateway credits for Workers AI and supported third-party model providers. Refer to [Unified Billing](/ai-gateway/features/unified-billing/). - **BYOK (Store Keys):** Store your own provider API Keys with Cloudflare, and AI Gateway will include them at runtime. Refer to [BYOK](/ai-gateway/configuration/bring-your-own-keys/). - **Request headers:** Include your provider API Key in the request headers as you normally would (for example, `Authorization: Bearer `). diff --git a/src/content/docs/ai-gateway/usage/providers/workersai.mdx b/src/content/docs/ai-gateway/usage/providers/workersai.mdx index 280f474725f..17dd5be9897 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 @@ products: import { TypeScriptExample } from "~/components"; -Use AI Gateway for analytics, caching, and security on requests to [Workers AI](/workers-ai/). +Use AI Gateway as a unified control layer for [Workers AI](/workers-ai/) requests, with analytics, logging, caching, security, and prepaid billing. To use prepaid [AI Gateway credits](/ai-gateway/features/unified-billing/), set the gateway's [Workers AI billing setting](/ai-gateway/configuration/manage-gateway/#configure-workers-ai-billing) to **Unified billing**. Requests to frontier models billed with prepaid credits receive [higher rate limits](/workers-ai/platform/limits/#frontier-models). ## REST API diff --git a/src/content/docs/ai-gateway/usage/rest-api.mdx b/src/content/docs/ai-gateway/usage/rest-api.mdx index 04b799040bd..3ae8eb44d00 100644 --- a/src/content/docs/ai-gateway/usage/rest-api.mdx +++ b/src/content/docs/ai-gateway/usage/rest-api.mdx @@ -12,7 +12,7 @@ products: The REST API lets you call any model — whether hosted on Cloudflare or by a third-party provider like OpenAI, Anthropic, or Google — through the same Cloudflare API, with all AI Gateway features — logging, caching, rate limiting, and more — applied automatically. -No provider SDKs or API keys are needed. Authentication and billing are handled through your Cloudflare account. Third-party models are billed via [Unified Billing](/ai-gateway/features/unified-billing/), while Workers AI models follow [Workers AI pricing](/workers-ai/platform/pricing/). +No provider SDKs or API keys are needed. Authentication and billing are handled through your Cloudflare account. Third-party models are billed via [Unified Billing](/ai-gateway/features/unified-billing/). Workers AI models can use prepaid AI Gateway credits or [Workers AI billing](/workers-ai/platform/pricing/). ## Endpoints @@ -34,7 +34,7 @@ The `/ai/v1/messages` endpoint strictly uses Anthropic's API schema and supports Authenticate with a [Cloudflare API token](/fundamentals/api/get-started/create-token/) that has `AI Gateway` permission. Pass it in the `Authorization` header. :::note -Ensure your Cloudflare account has [sufficient credits loaded](/ai-gateway/features/unified-billing/#load-credits) before calling third-party models. +Ensure your Cloudflare account has [sufficient credits loaded](/ai-gateway/features/unified-billing/#load-credits) before calling third-party models or using prepaid credits for Workers AI. ::: ## Model naming @@ -105,6 +105,7 @@ The existing Workers AI endpoint with the model ID in the URL path also continue # 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": [ @@ -116,6 +117,8 @@ curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ }' ``` +To use prepaid AI Gateway credits for Workers AI, use the model-in-path endpoint shown above, set the gateway's [Workers AI billing setting](/ai-gateway/configuration/manage-gateway/#configure-workers-ai-billing) to **Unified billing**, and include its ID in the `cf-aig-gateway-id` header. Requests to frontier models billed with prepaid credits receive [higher rate limits](/workers-ai/platform/limits/#frontier-models). + ## `/ai/v1/chat/completions` — OpenAI compatible Uses the standard OpenAI chat completions format. The `model` field uses the same `author/model` naming. This endpoint is compatible with the OpenAI SDK and other OpenAI-compatible clients. diff --git a/src/content/docs/ai-gateway/usage/worker-binding-methods.mdx b/src/content/docs/ai-gateway/usage/worker-binding-methods.mdx index a78487d87bf..d5b1a54e1b3 100644 --- a/src/content/docs/ai-gateway/usage/worker-binding-methods.mdx +++ b/src/content/docs/ai-gateway/usage/worker-binding-methods.mdx @@ -64,6 +64,8 @@ const resp = await env.AI.run( +To use prepaid [AI Gateway credits](/ai-gateway/features/unified-billing/), set the gateway's [Workers AI billing setting](/ai-gateway/configuration/manage-gateway/#configure-workers-ai-billing) to **Unified billing** and specify that gateway in the binding request. Prepaid credits provide access to Workers AI models that otherwise require the Workers Paid plan and provide [higher rate limits for frontier models](/workers-ai/platform/limits/#frontier-models). + **Third-party model:** @@ -96,14 +98,14 @@ Browse available models in the [model catalog](/ai/models/). The third argument to `env.AI.run()` accepts a `gateway` object with the following parameters: -| Parameter | Type | Default | Description | -| ------------ | --------- | ---------- | ------------------------------------------------------------------------------------------------ | +| 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. Use `"default"` to automatically create a gateway on the first authenticated request. Refer to [Default gateway](/ai-gateway/configuration/manage-gateway/#default-gateway) for details. | -| `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. | +| `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. | ## `env.AI.aiGatewayLogId` @@ -197,5 +199,3 @@ const anthropic = createAnthropic({ baseURL: await env.AI.gateway("my-gateway").getUrl("anthropic"), }); ``` - - diff --git a/src/content/docs/workers-ai/platform/ai-gateway.mdx b/src/content/docs/workers-ai/platform/ai-gateway.mdx index 785d3a25dce..9e9784b0af3 100644 --- a/src/content/docs/workers-ai/platform/ai-gateway.mdx +++ b/src/content/docs/workers-ai/platform/ai-gateway.mdx @@ -1,7 +1,7 @@ --- pcx_content_type: navigation title: AI Gateway -description: Use AI Gateway to manage, monitor, and cache your Workers AI requests. +description: Route Workers AI through a unified control layer for observability, billing, caching, security, and routing. external_link: /ai-gateway/ sidebar: order: 5 diff --git a/src/content/docs/workers-ai/platform/limits.mdx b/src/content/docs/workers-ai/platform/limits.mdx index b4eb338dfb1..f233daf703d 100644 --- a/src/content/docs/workers-ai/platform/limits.mdx +++ b/src/content/docs/workers-ai/platform/limits.mdx @@ -59,6 +59,18 @@ Rate limits are default per task type, with some per-model limits defined as fol - [@cf/qwen/qwen1.5-14b-chat-awq](/workers-ai/models/qwen1.5-14b-chat-awq/) is 150 requests per minute - [@cf/tinyllama/tinyllama-1.1b-chat-v1.0](/workers-ai/models/tinyllama-1.1b-chat-v1.0/) is 720 requests per minute +#### Frontier models + +The following limits apply per account, per model: + +| Model | Standard Workers AI billing | Prepaid AI Gateway credits | +| ------------------------------------------------------------------- | --------------------------- | -------------------------- | +| [@cf/moonshotai/kimi-k2.6](/workers-ai/models/kimi-k2.6/) | 20 requests per minute | 50 requests per minute | +| [@cf/moonshotai/kimi-k2.7-code](/workers-ai/models/kimi-k2.7-code/) | 20 requests per minute | 50 requests per minute | +| [@cf/zai-org/glm-5.2](/workers-ai/models/glm-5.2/) | 20 requests per minute | 50 requests per minute | + +To receive the elevated limit, load [prepaid AI Gateway credits](/ai-gateway/features/unified-billing/) and set the gateway's [Workers AI billing setting](/ai-gateway/configuration/manage-gateway/#configure-workers-ai-billing) to **Unified billing**. These limits are designed for typical agentic and coding workloads, where requests to frontier models can take longer to complete. + ### [Text-to-Image](/workers-ai/models/) - 720 requests per minute diff --git a/src/content/docs/workers-ai/platform/pricing.mdx b/src/content/docs/workers-ai/platform/pricing.mdx index d6121e85fc8..bfa0c8ccb61 100644 --- a/src/content/docs/workers-ai/platform/pricing.mdx +++ b/src/content/docs/workers-ai/platform/pricing.mdx @@ -26,9 +26,15 @@ All limits reset daily at 00:00 UTC. If you exceed any one of the above limits, | Workers Paid | 10,000 Neurons per day | $0.011 / 1,000 Neurons | :::note -Some models are not available on the Workers Free plan and require the [Workers Paid plan](/workers/platform/pricing/#workers). This applies to `@cf/moonshotai/kimi-k2.6`, `@cf/moonshotai/kimi-k2.7-code`, and `@cf/zai-org/glm-5.2`. +Some models require a paid billing method. This applies to `@cf/moonshotai/kimi-k2.6`, `@cf/moonshotai/kimi-k2.7-code`, and `@cf/zai-org/glm-5.2`. You can access these models with either the [Workers Paid plan](/workers/platform/pricing/#workers) or prepaid [AI Gateway credits](/ai-gateway/features/unified-billing/). ::: +## Pay with AI Gateway credits + +You can use prepaid [AI Gateway credits](/ai-gateway/features/unified-billing/) to pay for Workers AI inference. Set the gateway's [Workers AI billing setting](/ai-gateway/configuration/manage-gateway/#configure-workers-ai-billing) to **Unified billing**, then specify that gateway in the [AI binding](/ai-gateway/usage/worker-binding-methods/) or REST API request. + +Requests to frontier models that use prepaid credits receive [higher rate limits](/workers-ai/platform/limits/#frontier-models). + ## What are Neurons? Neurons are our way of measuring AI outputs across different models, representing the GPU compute needed to perform your request. Our serverless model allows you to pay only for what you use without having to worry about renting, managing, or scaling GPUs. diff --git a/src/content/partials/ai-gateway/create-gateway.mdx b/src/content/partials/ai-gateway/create-gateway.mdx index a18d30c4390..ecf6edbe4eb 100644 --- a/src/content/partials/ai-gateway/create-gateway.mdx +++ b/src/content/partials/ai-gateway/create-gateway.mdx @@ -13,7 +13,10 @@ import { TabItem, Tabs, DashButton } from "~/components"; 2. Go to **AI** > **AI Gateway**. 3. Select **Create Gateway**. 4. Enter your **Gateway name**. Note: Gateway name has a 64 character limit. -5. Select **Create**. +5. In **Workers AI Billing**, choose how Workers AI requests through this gateway are billed: + - **Standard billing** charges your Cloudflare account at the end of each billing cycle. + - **Unified billing** deducts from your prepaid AI Gateway credit balance in real time. +6. Select **Create**. diff --git a/src/content/partials/workers-ai/workers-paid-only-note.mdx b/src/content/partials/workers-ai/workers-paid-only-note.mdx index 9c9b0930b71..5da738c21a7 100644 --- a/src/content/partials/workers-ai/workers-paid-only-note.mdx +++ b/src/content/partials/workers-ai/workers-paid-only-note.mdx @@ -2,8 +2,8 @@ {} --- -:::caution[Requires Workers Paid] +:::caution[Paid access required] -This model is not available on the [Workers Free plan](/workers/platform/pricing/#workers). To use it, upgrade to the [Workers Paid plan](/workers/platform/pricing/#workers). +This model is not available through standard Workers Free billing. To use it, upgrade to the [Workers Paid plan](/workers/platform/pricing/#workers) or use prepaid [AI Gateway credits](/ai-gateway/features/unified-billing/). :::