---
title: "Direct and gateway routes"
description: "The ways the package reaches Cloudflare, what each setup needs, and which features work on each."
---

> Documentation Index
> Fetch the complete documentation index at: https://laravel-cf-workersai.meirdick.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Direct and gateway routes

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](/docs/guides/ai-gateway/#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()`.

### Direct

Add to `.env`:

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

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

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

### Gateway

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

```ini
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`:

```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
],
```

### Direct with a gateway header

Add to `.env`:

```ini
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`:

```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')],
],
```

### Custom URL

Add to `.env`:

```ini
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`:

```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](#non-json-models) with a gateway use `gateway.ai.cloudflare.com/v1/{account}/{gateway}/workers-ai/{model}`.
- [`Markdown::of()`](/docs/guides/documents/) calls `/ai/tomarkdown` on `api.cloudflare.com`, or on your `url` if it ends in `/ai/v1`. It does not use `gateway`.
- [`CloudflareWebSearch`](/docs/guides/web-search/) 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`](#non-json-models) | Yes, except [`nova-3`](#non-json-models) |
| 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.

```php
'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](/docs/guides/ai-gateway/#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.

Source: https://laravel-cf-workersai.meirdick.com/docs/concepts/routes/index.mdx
