Quick answer
Cloudflare’s unified model-access paths are the env.AI.run() binding and Cloudflare-authenticated /ai/ REST endpoints. Select a gateway in the binding options or with cf-aig-gateway-id on REST calls to apply AI Gateway observability and controls.
Migration is not automatically urgent. Cloudflare says the existing Workers AI /ai/run/@cf/{model} REST path continues to work. Move when the unified path’s provider access, gateway controls, authentication, or billing benefits justify the change and tests prove compatibility.
Choose an endpoint shape
| Shape | Typical fit |
|---|---|
POST /ai/run | Universal model and modality calls |
POST /ai/v1/chat/completions | OpenAI-compatible chat client |
POST /ai/v1/responses | OpenAI-compatible responses client |
POST /ai/v1/messages | Anthropic-compatible messages client |
| Workers binding | Code already running in Workers with an AI binding |
Compatibility shape does not promise identical provider semantics. Verify supported parameters, streaming events, tool calls, error objects, usage fields, content types, model prefixes, and response normalization for every model used.
Migration sequence
Inventory current endpoints, bindings, model names, provider keys, authentication, timeouts, retries, cache behavior, payload logging, and billing. Pick a gateway boundary per application and environment. Create least-privilege Cloudflare credentials and keep rollback configuration intact.
Run non-sensitive golden requests through both paths. Compare output schema, stop reasons, token counts, latency, errors, rate-limit headers, retries, cached responses, and cost attribution. Test malformed input, provider failure, timeout, limit exhaustion, credential revocation, and gateway unavailability.
Roll out by a bounded cohort and monitor request counts, latency, error rates, tokens, spend, and unexpected provider or model selection. Do not retry a state-changing tool workflow without idempotency and reconciliation.
Billing and data gates
Enabling the gateway path does not by itself enable prepaid credits for Workers AI. Cloudflare documents a separate Unified billing setting on the gateway. Confirm whether the request uses prepaid credits, standard Workers AI billing, or another provider path.
Review whether prompts and responses are logged, who can access them, and how caching, retention, and deletion behave. Use named gateways when data, budget, identity, or operational boundaries differ.
Read the default gateway guide and unified billing guide before production migration.
Frequently asked questions
Must existing Workers AI REST calls migrate immediately?
Cloudflare’s May changelog says the existing Workers AI /ai/run/@cf/{model} REST path continues to work; migration should follow verified product needs and testing.
Which unified REST shapes does Cloudflare document?
Cloudflare documents /ai/run plus OpenAI-compatible chat completions and responses endpoints and an Anthropic-compatible messages endpoint.
How is a gateway selected on REST calls?
Use the cf-aig-gateway-id header for a named gateway or default; Cloudflare says default is created on the first authenticated request.
Official sources
Source check: August 12, 2026. Recheck endpoints, authentication, SDK compatibility, models, gateways, pricing, logging, and deprecation status.