Skip to content

AI Gateway

Set up AI Gateway, Authenticated Gateway and third-party models, and use session affinity and cached tokens.

Updated

Cloudflare AI Gateway is a proxy for AI requests. It gives you request logs, cost analytics, caching and rate limits in the Cloudflare dashboard. You create and configure the gateway in the dashboard; the package only sends requests to it. To compare the gateway route with the direct route, see Direct and gateway routes.

Route requests through a gateway

  1. Create a gateway

    In the Cloudflare dashboard, go to AI, then AI Gateway, then Create Gateway. Copy the gateway name; this is the slug the package needs.

  2. Add the slug to your .env file

    Add this line to your application’s .env file:

    CLOUDFLARE_AI_GATEWAY=my-gateway
  3. Read it in config/ai.php

    Add the gateway line to the provider entry. It reads the slug from .env, so don’t write the slug here.

    'workers-ai' => [
        'driver'     => 'workers-ai',
        'key'        => env('CLOUDFLARE_AI_API_TOKEN'),
        'account_id' => env('CLOUDFLARE_ACCOUNT_ID'),
        'gateway'    => env('CLOUDFLARE_AI_GATEWAY'),
    ],
  4. Send a request and open the logs

    Your calling code doesn’t change. To confirm the route works, open the gateway in the dashboard and go to Logs. Text and embedding calls show up under compat.

Text and embedding calls go to https://gateway.ai.cloudflare.com/v1/<account_id>/<gateway>/compat. Clef and Clairic calls go to api.cloudflare.com with a cf-aig-gateway-id header, and Cloudflare applies the gateway’s features to them.

Use only the slug. If you give a URL or a value with a slash, the package throws and points you to the url key.

Authenticated Gateway

Authenticated Gateway is a gateway setting that makes gateway.ai.cloudflare.com reject any request without a gateway token. To set it up:

  1. Open the gateway settings in the dashboard.
  2. Create an authentication token and copy it. This is the gateway token, and it has Run permission.
  3. Turn on Authenticated Gateway.
  4. Add the token to your application’s .env file:
CLOUDFLARE_AI_GATEWAY_TOKEN=your-gateway-token
  1. Read it in the provider entry in config/ai.php:
'workers-ai' => [
    // ...
    'gateway_token' => env('CLOUDFLARE_AI_GATEWAY_TOKEN'),
],

The package sends cf-aig-authorization: Bearer <gateway_token>, and your key still goes in Authorization. If gateway_token is empty, the package doesn’t send the header.

Calls that go to api.cloudflare.com, such as Clef and Clairic, don’t need the gateway token, because that API reads your API token from Authorization (tested on 2026-11-05). FLUX.2 image models are the exception and do need it. See Non-JSON models.

Without the header, or with a wrong token, an authenticated gateway returns HTTP 401 with {"code":2009,"message":"Unauthorized"}, and Laravel throws Illuminate\Http\Client\RequestException. The message doesn’t name the gateway or the header, so check gateway_token first.

Direct route with a gateway header

You can also get gateway features while staying on the direct route. Cloudflare’s REST API on api.cloudflare.com routes a request through a gateway when it carries the cf-aig-gateway-id header. This needs no gateway key, and no second token even on an authenticated gateway. The exceptions are FLUX.2, which still needs the token, and nova-3, which can’t use a gateway at all. See Non-JSON models.

Keep the slug in your application’s .env file as CLOUDFLARE_AI_GATEWAY, and read it in config/ai.php:

'workers-ai' => [
    'driver'     => 'workers-ai',
    'key'        => env('CLOUDFLARE_AI_API_TOKEN'),
    'account_id' => env('CLOUDFLARE_ACCOUNT_ID'),
    'headers'    => ['cf-aig-gateway-id' => env('CLOUDFLARE_AI_GATEWAY')],
],

Text, Clef, Clairic and embeddings all returned HTTP 200 this way on 2026-11-05, although Cloudflare’s gateway docs list only chat completions on this API, not embeddings. See the AI Gateway REST API.

Third-party models

Cloudflare’s REST API also serves other providers’ models, such as OpenAI’s, with your Cloudflare token. Use the direct route, and name the model in author/model form:

use function Laravel\Ai\agent;

agent()->prompt('Hello', provider: 'workers-ai', model: 'openai/gpt-5.5');
  • Cloudflare bills the call from your AI Gateway credits, or uses a provider key you stored under the default alias. See Unified Billing and bring your own keys (BYOK).
  • The call goes through your account’s default gateway. To pick another, add the cf-aig-gateway-id header as in the previous section.
  • The token needs Account, Workers AI, Read, the same as other calls (tested on 2026-11-05 with openai/gpt-4.1-mini).

Use another provider’s driver through a gateway

You can point another Laravel AI driver, such as openai, at your gateway to get its logs and caching. You need your own provider key for this, because Laravel AI’s drivers always send key as Authorization. Add the key to your application’s .env file as OPENAI_API_KEY, and build the URL in config/ai.php with BaseUrl::providerUrl():

use Meirdick\WorkersAi\Cloudflare\BaseUrl;

'openai' => [
    'driver'  => 'openai',
    'key'     => env('OPENAI_API_KEY'),
    'url'     => BaseUrl::providerUrl(env('CLOUDFLARE_ACCOUNT_ID'), env('CLOUDFLARE_AI_GATEWAY'), 'openai'),
    // Remove this line unless the gateway is authenticated.
    'headers' => ['cf-aig-authorization' => 'Bearer '.env('CLOUDFLARE_AI_GATEWAY_TOKEN')],
],

For another provider, replace 'openai' with 'anthropic' or that provider’s slug. Don’t call config() here, because config/ai.php is still loading. If you’d rather use a key stored on the gateway, see third-party models.

Use the provider path

To use <gateway>/workers-ai/v1 instead of /compat, set gateway_path:

'gateway_path' => 'workers-ai/v1',

/compat stays the default. See The gateway provider path.

Use a custom URL

Set url when you need a full URL the package doesn’t build, such as a proxy. Add it to your application’s .env file as CLOUDFLARE_AI_URL and read it in config/ai.php. Don’t set account_id alongside it, because the package throws if both are set.

'workers-ai' => [
    'driver' => 'workers-ai',
    'key'    => env('CLOUDFLARE_AI_API_TOKEN'),
    'url'    => env('CLOUDFLARE_AI_URL'),
],

If the URL ends in /compat, the package adds the workers-ai/ model prefix, and Clef and Clairic calls throw. For any other URL, it sends the bare model name. See Where each call goes.

Session affinity

Set session_affinity to send the x-session-affinity header on every request:

'workers-ai' => [
    // ...
    'session_affinity' => 'my-app-session',
],

Requests with the same value then reach the same cache shard, which gives the model’s prompt cache a better chance of a hit. See the next section.

Cached tokens

Some models cache the start of a prompt, and a cache hit costs fewer neurons. Cloudflare reports how many tokens came from the cache in usage.prompt_tokens_details.cached_tokens.

The package supports two laravel/ai release lines, 0.9 to 0.11 and 1.x, and they count cached tokens differently:

  • laravel/ai 0.9 to 0.11. Usage::$promptTokens is the uncached count. Usage::$cacheReadInputTokens is the cached count. The two add up to the prompt_tokens that Cloudflare reports.
  • laravel/ai 1.x. The package returns TextUsage. inputTokens is the prompt_tokens that Cloudflare reports, with cached tokens included. cacheReadInputTokens is the cached part of it. It is null when the response has no cache field. outputTokens is the completion count.

WorkersAiUsageReported::$promptTokens is the uncached count on both lines.

// laravel/ai 0.9 to 0.11
$uncached = $response->usage->promptTokens;
$cached   = $response->usage->cacheReadInputTokens;

// laravel/ai 1.x
$total    = $response->usage->inputTokens;
$cached   = $response->usage->cacheReadInputTokens ?? 0;
$uncached = $total - $cached;

Here are two identical calls on @cf/zai-org/glm-5.3-flash with the same x-session-affinity value, measured on 2026-09-16. The second call hit the cache and cost less than half:

Call Wire prompt_tokens Wire cached_tokens 0.x promptTokens 1.x inputTokens cacheReadInputTokens Neurons
1 1221 0 1221 1221 0 17.8
2 1221 1216 5 1221 1216 8.3

Whether this works depends on the model. In tests, @cf/zai-org/glm-5.3-flash and @cf/moonshotai/kimi-k2.6 hit the cache, while @cf/meta/llama-3.3-70b-instruct-fp8-fast, @cf/meta/llama-4-scout-17b-16e-instruct and @cf/openai/gpt-oss-120b did not.

#[CacheInstructions] from Laravel AI has no effect on this provider.

Custom headers

The package sends the headers array from the provider config on chat, streaming and embeddings calls. If one of your headers has the same name as a header the package sets, yours wins. Names match without regard to case.

'workers-ai' => [
    // ...
    'headers' => ['X-Trace-Id' => env('TRACE_ID')],
],

On laravel/ai 1.x, Provider::withHeaders() writes to the same array, so per-call headers reach Workers AI too. Before version 1.0.0, the package dropped both the headers key and per-call headers.

Logging

AI Gateway logs are in the Cloudflare dashboard. The package doesn’t write request logs. The only thing it writes to the Laravel log is a warning when it raises the token cap for a thinking request.

Gateway retries

An AI Gateway with retry_max_attempts set retries inside your single HTTP request, and the package retries too. A late error can then make the request several times longer, long enough for your own timeout to cut it off. Use one retry layer: if you want the gateway’s retry, set retry to false in the package config. See Errors and retries.

Type to search…

↑↓ navigate↵ selectEsc close