Skip to content

Direct and gateway routes

The ways the package reaches Cloudflare, what each setup needs, and which features work on each.

Updated

The package reaches Cloudflare in one of four ways. Your config picks the route, your calling code is the same on all of them, and you can change route at any time by changing config.

Choose a route

You want Use
The shortest setup, and no gateway features Direct route
AI Gateway logs, caching and rate limits Gateway route
Gateway features with one token, on api.cloudflare.com Direct route with a gateway header
OpenAI, Anthropic or another provider’s models, billed by Cloudflare Direct route. See third-party models.
A proxy, or a URL that the package does not build Custom url

What each route needs

Every route needs a Cloudflare API token with the Account, Workers AI, Read permission.

Route Provider config Second token
Direct key, account_id No
Gateway key, account_id, gateway gateway_token, only if Authenticated Gateway is on
Direct with a gateway header key, account_id, headers gateway_token, only on an authenticated gateway, and only for FLUX.2
Custom key, url Depends on the URL

The values go in your application’s .env file, and config/ai.php reads them with env().

Add to .env:

CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_AI_API_TOKEN=your-api-token

Add to the providers array in config/ai.php:

'workers-ai' => [
    'driver'     => 'workers-ai',
    'key'        => env('CLOUDFLARE_AI_API_TOKEN'),
    'account_id' => env('CLOUDFLARE_ACCOUNT_ID'),
],

Add to .env. Leave the gateway token empty unless Authenticated Gateway is on:

CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_AI_API_TOKEN=your-api-token
CLOUDFLARE_AI_GATEWAY=your-gateway-slug
CLOUDFLARE_AI_GATEWAY_TOKEN=

Add to the providers array in config/ai.php:

'workers-ai' => [
    'driver'        => 'workers-ai',
    'key'           => env('CLOUDFLARE_AI_API_TOKEN'),
    'account_id'    => env('CLOUDFLARE_ACCOUNT_ID'),
    'gateway'       => env('CLOUDFLARE_AI_GATEWAY'),
    'gateway_token' => env('CLOUDFLARE_AI_GATEWAY_TOKEN'), // optional: only if Authenticated Gateway is on
],

Add to .env:

CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_AI_API_TOKEN=your-api-token
CLOUDFLARE_AI_GATEWAY=your-gateway-slug

Add to the providers array 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')],
],

Add to .env:

CLOUDFLARE_AI_API_TOKEN=your-api-token
CLOUDFLARE_AI_URL=https://your-proxy.example.com/ai/v1

Add to the providers array in config/ai.php:

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

To change route, change .env and the provider entry. Your calling code stays the same.

The package checks the config before it sends anything. It throws if you set both url and account_id, or if you pass a URL as account_id or gateway.

An empty gateway or gateway_token is ignored, so the Gateway entry above also works where you have no gateway, such as local development. Just leave those two variables out of that environment’s .env.

Where each call goes

Route Text and embeddings Run API calls
Direct api.cloudflare.com/client/v4/accounts/{account}/ai/v1 api.cloudflare.com/client/v4/accounts/{account}/ai/run/{model}
Gateway gateway.ai.cloudflare.com/v1/{account}/{gateway}/compat The direct run URL, plus the cf-aig-gateway-id header
Direct with a gateway header The direct URL, plus the header The direct run URL, plus the header
url ending in /ai/v1 That URL The /ai/v1 suffix becomes /ai/run/{model}
url ending in /compat That URL Throws. Set account_id instead.
Any other url That URL {url}/run/{model}

Run API calls are Clef, Clairic, reranking, images, speech and transcription. They go to Cloudflare’s /ai/run/{model} endpoint, because /compat and /ai/v1 don’t serve those models. You don’t need a second provider entry for them: one workers-ai entry handles every call, and they all go through your gateway when you set gateway.

Three calls don’t follow this table:

  • Non-JSON models with a gateway use gateway.ai.cloudflare.com/v1/{account}/{gateway}/workers-ai/{model}.
  • Markdown::of() calls /ai/tomarkdown on api.cloudflare.com, or on your url if it ends in /ai/v1. It does not use gateway.
  • CloudflareWebSearch calls /ai/websearch/ on the same host, and names its own gateway.

What works on each route

Feature Direct Gateway Direct with a gateway header
Text, tools, streaming, structured output Yes Yes Yes
Embeddings Yes Yes Yes. Tested on 2026-11-05. Cloudflare’s gateway docs do not list this endpoint.
Clef and Clairic Yes Yes Yes
Reranking, images, speech, transcription Yes Yes, except nova-3 Yes, except nova-3
Neuron event Yes Yes Yes
Gateway logs, analytics, caching, rate limits No Yes Yes
Authenticated Gateway Not applicable Needs gateway_token key is enough, except for FLUX.2
Third-party model with model: Yes No. See below. Yes

You set gateway features such as caching and rate limits in the Cloudflare dashboard. The package doesn’t set them.

Tokens on the gateway route

An authenticated gateway is one with Authenticated Gateway turned on in its settings. On gateway.ai.cloudflare.com, it needs two credentials on text and embeddings calls:

  • key goes in the Authorization header and pays for the Workers AI call.
  • gateway_token goes in the cf-aig-authorization header and lets the request into the gateway. It’s an AI Gateway token with Run permission.

Without gateway_token, or with a wrong one, these calls return HTTP 401.

Run API calls with a JSON body go to api.cloudflare.com, which reads the API token from Authorization, so they don’t need gateway_token. In tests on 2026-11-05 on an authenticated gateway, Clef, Clairic, reranking, speech, Whisper models and JSON image models all returned 200 this way. If you do set the token, the package still sends the header, and the calls still work.

Non-JSON models

Cloudflare’s REST API rejects a request body that isn’t JSON when it goes through a gateway. So these three kinds of model behave differently once you set a gateway (tested on 2026-11-05):

Model Body With a gateway
@cf/black-forest-labs/flux-2-klein-4b, flux-2-klein-9b, flux-2-dev Multipart Uses gateway.ai.cloudflare.com/v1/{account}/{gateway}/workers-ai/{model}. On an authenticated gateway, needs gateway_token on both routes.
@cf/openai/whisper, @cf/openai/whisper-tiny-en Raw audio Sends a JSON byte array instead. key is enough. JSON is about 4 times the size of the audio.
@cf/deepgram/nova-3 Raw audio Throws InvalidArgumentException. Cloudflare has no form of this request that works through a gateway.

To use nova-3 in an app that has a gateway, add a second provider entry with no gateway and pass its name on that call. The call then skips the gateway, so the gateway’s logs and limits don’t apply to it.

'workers-ai-direct' => [
    'driver'     => 'workers-ai',
    'key'        => env('CLOUDFLARE_AI_API_TOKEN'),
    'account_id' => env('CLOUDFLARE_ACCOUNT_ID'),
],

Third-party models and the gateway route

Third-party models are other providers’ models, such as OpenAI’s, that Cloudflare serves for you. They don’t work on the gateway route. That route sends key as Authorization, and Cloudflare forwards that header to the provider as the provider’s own key instead of using a key you stored. A Cloudflare token isn’t a valid OpenAI key, so the call returns HTTP 401 with OpenAI’s Incorrect API key provided. A gateway_token doesn’t change that (tested on 2026-11-05). Use the direct route for third-party models. See third-party models.

Model names

Write bare Workers AI IDs on every route, such as @cf/openai/gpt-oss-120b. The /compat path needs a workers-ai/ prefix to know where to send the call, and the package adds it for you. On any other URL, a workers-ai/ prefix throws on text calls. For Clef and Clairic, the package removes the prefix.

The gateway provider path

AI Gateway also has a workers-ai/v1 path, which you can use by setting gateway_path. It isn’t the default. On an authenticated gateway, chat and embeddings returned 200 on this path with gateway_token in tests on 2026-11-05. Earlier tests on 2026-09-09 got 401 on embeddings on a gateway with authentication on, so /compat stays the default.

Type to search…

↑↓ navigate↵ selectEsc close