copy

Author: ethulia

src/content/changelog/ai-gateway/2026-03-25-run-api-beta.mdx

@@ -1,14 +1,14 @@
 ---
-title: Run API now available in beta
-description: AI Gateway introduces the Run API, a new endpoint for running AI models with a simplified request/response pattern.
+title: New Run API for AI Gateway now available in beta
+description: AI Gateway introduces the /run api and support for running third party models in Workers AI bindings 
 products:
   - ai-gateway
 date: 2026-03-25
 ---
 
 AI Gateway now offers a new `/run` endpoint for running AI models. The Run API uses its own request envelope, separate from the OpenAI-compatible `/chat/completions` format, and is designed to support a broader range of model types over time.
 
-During the beta, the Run API supports one model — `google/nano-banana` for image generation. Authenticate with [Unified Billing](/ai-gateway/features/unified-billing/) or [BYOK (Gateway Key Store)](/ai-gateway/configuration/bring-your-own-keys/).
+Today, the Run API supports one model — `google/nano-banana` for image generation. Authenticate with [Unified Billing](/ai-gateway/features/unified-billing/) or [BYOK (Gateway Key Store)](/ai-gateway/configuration/bring-your-own-keys/).
 
 ```bash
 curl -X POST "https://gateway.ai.cloudflare.com/v1/$CLOUDFLARE_ACCOUNT_ID/default/run" \
@@ -22,4 +22,14 @@ curl -X POST "https://gateway.ai.cloudflare.com/v1/$CLOUDFLARE_ACCOUNT_ID/defaul
   }'
 ```
 
+With this release, the Workers AI binding (`env.AI.run()`) now supports running third-party models proxied through AI Gateway. You can call models like `google/nano-banana` directly from a Cloudflare Worker without managing provider credentials in your code:
+
+```ts
+const response = await env.AI.run(
+  "google/nano-banana",
+  { prompt: "a cat riding a burrito" },
+  { gateway: { id: "my-gateway" } },
+);
+```
+
 Additional models and features will be added in future updates. For more information, refer to the [Run API](/ai-gateway/usage/run-api/) documentation.

src/content/docs/ai-gateway/usage/run-api.mdx

@@ -36,6 +36,32 @@ The Run API supports the following authentication methods for upstream provider
 Passing provider API keys directly in request headers is not supported with the Run API. You must use Unified Billing or BYOK (Gateway Key Store) to authenticate with upstream providers.
 :::
 
+## Request
+
+```txt
+POST /v1/{account_id}/{gateway_id}/run
+```
+
+### Request body
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `model` | `string` | Yes | The model to run. Refer to [Supported models](#supported-models) for available values. |
+| `input` | `object` | Yes | Model-specific input parameters. The accepted fields depend on the model. |
+| `provider` | `string` | No | Pin the request to a specific provider instead of using the default. |
+| `background` | `boolean` | No | When `true`, the request returns immediately with a `runId` that you can poll for results. |
+| `webhookUrl` | `string` | No | A URL to receive a callback when the run completes. Only valid when `background` is `true`. |
+
+### Input fields for `google/nano-banana`
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `prompt` | `string` | Yes | The text prompt describing the image to generate. |
+| `image_input` | `string[]` | No | Up to 3 base64-encoded images to use as input for image-to-image generation. |
+| `aspect_ratio` | `string` | No | Aspect ratio of the output image. One of: `1:1`, `3:2`, `2:3`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`. |
+| `output_format` | `string` | No | Output image format. One of: `jpg`, `png`, `webp`. |
+| `image_size` | `string` | No | Output image resolution. One of: `1K`, `2K`, `4K`. |
+
 ## Supported models
 
 The Run API currently supports a single model:
@@ -46,7 +72,9 @@ The Run API currently supports a single model:
 
 More models will be added in future updates.
 
-## Example
+## Examples
+
+### Basic request
 
 <Tabs>
 <TabItem label="curl">
@@ -108,7 +136,66 @@ export default {
 </TabItem>
 </Tabs>
 
-### Response
+### With input options
+
+```bash
+curl -X POST "https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/run" \
+  --header "cf-aig-authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+  --header "Content-Type: application/json" \
+  --data '{
+    "model": "google/nano-banana",
+    "input": {
+      "prompt": "a cat riding a burrito",
+      "aspect_ratio": "16:9",
+      "output_format": "png",
+      "image_size": "2K"
+    }
+  }'
+```
+
+### Background run
+
+Set `background` to `true` to run the request asynchronously. The API returns a `runId` immediately, which you can poll for results.
+
+```bash
+curl -X POST "https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/run" \
+  --header "cf-aig-authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+  --header "Content-Type: application/json" \
+  --data '{
+    "model": "google/nano-banana",
+    "input": {
+      "prompt": "a cat riding a burrito"
+    },
+    "background": true
+  }'
+```
+
+Poll for the result using the returned `runId`:
+
+```bash
+curl "https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/run/{run_id}" \
+  --header "cf-aig-authorization: Bearer $CLOUDFLARE_API_TOKEN"
+```
+
+You can also provide a `webhookUrl` to receive a callback when the run completes instead of polling:
+
+```bash
+curl -X POST "https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/run" \
+  --header "cf-aig-authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+  --header "Content-Type: application/json" \
+  --data '{
+    "model": "google/nano-banana",
+    "input": {
+      "prompt": "a cat riding a burrito"
+    },
+    "background": true,
+    "webhookUrl": "https://example.com/webhook"
+  }'
+```
+
+## Response
+
+### Success
 
 A successful request returns a response with the following envelope:
 
@@ -132,7 +219,7 @@ A successful request returns a response with the following envelope:
 | `provider` | The provider that served the request. |
 | `model` | The model that was used. |
 
-### Error response
+### Error
 
 ```json
 {
@@ -150,11 +237,9 @@ A successful request returns a response with the following envelope:
 The Run API is in beta. The following limitations apply:
 
 - **One model** — Only `google/nano-banana` is supported. Additional models will be added over time.
-- **Image generation only** — Chat and text generation models are not yet available through the Run API.
 - **No caching** — [Caching](/ai-gateway/features/caching/) is not supported for Run API requests.
 - **No rate limiting** — [Rate limiting](/ai-gateway/features/rate-limiting/) rules do not apply to Run API requests.
-- **No guardrails** — [Guardrails](/ai-gateway/guardrails/) are not available for the Run API.
-- **No DLP** — Data loss prevention features are not supported.
+- **No guardrails or DLP** — [Guardrails](/ai-gateway/guardrails/) and data loss prevention features are not available for the Run API.
 - **No dynamic routing** — [Dynamic routing](/ai-gateway/features/dynamic-routing/) (fallbacks, A/B testing, conditional logic) is not available.
 - **No streaming** — Streaming responses are not supported.
 - **No TypeScript types** — TypeScript type definitions for the Run API are not yet available in `@cloudflare/workers-types`.