Route OpenAI, Anthropic, and Workers AI requests through Cloudflare AI Gateway's unified endpoint for caching, logging, retries, and fallback

Documented steps

1. No setup is strictly required: a gateway named `default` is auto-created on your first request, so `{gateway_id}` can literally be `default` until you make a named one.
2. Use the OpenAI-compatible unified endpoint: `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat/chat/completions`, and specify the model as `{provider}/{model}` in the request body.
3. Model id examples from the current docs: `openai/gpt-5.2`, `anthropic/claude-4-5-sonnet`, `google/gemini-2.5-pro`, `grok/grok-4`, `workers-ai/@cf/meta/llama-3.3-70b-instruct-fp8-fast`, and `dynamic/<route-name>` to invoke a configured dynamic route.
4. Point the OpenAI SDK at the gateway by overriding baseURL: `new OpenAI({ apiKey: "{cf_api_token}", baseURL: "https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat" })` — switching providers then becomes a model-string change, not a code change.
5. Provider-specific passthrough endpoints also exist at `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/{provider}/...` when you need native provider request/response shapes instead of the OpenAI-compatible format.
6. Enable per-request caching with the header `cf-aig-cache-ttl: <seconds>` (minimum 60, maximum 2,592,000 = 1 month). If caching is enabled in the dashboard but no TTL is sent, the dashboard default applies; if disabled there, the fallback TTL is 5 minutes.
7. Bypass cache for a specific call with `cf-aig-skip-cache: true`, and override the dedup key with `cf-aig-cache-key: <custom-string>`. Read `cf-aig-cache-status` on the response for HIT or MISS.
8. Tag requests for analytics and filtering with `cf-aig-metadata: {"team":"AI","user":12345,"test":true}` — a flat JSON object, maximum 5 entries, values limited to string, number, or boolean.
9. Override cost accounting with `cf-aig-custom-cost: {"per_token_in":0.000001,"per_token_out":0.000002}`. It applies only when the request actually reaches the provider.
10. Configure fallback / dynamic routing by POSTing an ARRAY of provider configs (endpoint, auth headers, provider-specific params) to the universal endpoint. Cloudflare tries each entry in order, advancing on model errors or request timeouts.
11. Determine which attempt served the response from the `cf-aig-step` response header: 0 = primary succeeded, 1 = first fallback, 2 = second fallback, and so on. Log this — silent fallback to a weaker model is otherwise invisible.
12. To require a token on every call into the gateway, open the gateway's Settings, create an authentication token with Run permission, save it, then enable Authenticated Gateway. Unauthenticated direct HTTP calls will then fail while Worker binding calls remain pre-authenticated.
13. With Authenticated Gateway on, pass the token via the standard `Authorization` header for api.cloudflare.com REST calls, but via `cf-aig-authorization` for provider-native calls to gateway.ai.cloudflare.com.
14. Control logging per request with `cf-aig-collect-log: <bool>` (log the request at all) and `cf-aig-collect-log-payload: <bool>` (log metadata without storing full payload bodies) — the practical lever for prompts you must not retain.
15. Official documentation (verify before relying on limits, which change): https://developers.cloudflare.com/ai-gateway/ | https://developers.cloudflare.com/ai-gateway/usage/chat-completion/ | https://developers.cloudflare.com/ai-gateway/configuration/caching/ | https://developers.cloudflare.com/ai-gateway/configuration/fallbacks/ | https://developers.cloudflare.com/ai-gateway/configuration/authentication/ | https://developers.cloudflare.com/ai-gateway/observability/custom-metadata/ | https://developers.cloudflare.com/ai-gateway/configuration/custom-costs/ | https://developers.cloudflare.com/ai-gateway/observability/logging/