Skip to content
Cloudflare Docs
Docs DirectoryAPIsSDKs

Getting started

Last reviewed: almost 2 years ago

In this guide, you will learn how to set up and use your first AI Gateway.

Get your account ID and authentication token

Before making requests, you need two things:

  1. Your Account ID — find it in the Cloudflare dashboard.
  2. A Cloudflare API token — create an API token with AI Gateway - Read and AI Gateway - Edit permissions. The example below also uses Workers AI, so add Workers AI - Read as well.

Send your first request

Run the following command to make your first request through AI Gateway:

Terminal window
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "moonshotai/kimi-k2.6",
    "provider": "cloudflare",
    "messages": [
      {
        "role": "user",
        "content": "What is Cloudflare?"
      }
    ]
  }'

Create a gateway manually

You can also create gateways manually with a custom name and configuration through the dashboard or API.

Go to AI Gateway
  1. Log into the Cloudflare dashboard ↗ and select your account.
  2. Go to AI > AI Gateway.
  3. Select Create Gateway.
  4. Enter your Gateway name. Note: Gateway name has a 64 character limit.
  5. Select Create.

Provider authentication

Authenticate with your upstream AI provider using one of the following options:

  • Unified Billing: Use the AI Gateway billing to pay for and authenticate your inference requests. Refer to Unified Billing.
  • BYOK (Store Keys): Store your own provider API Keys with Cloudflare, and AI Gateway will include them at runtime. Refer to BYOK.
  • Request headers: Include your provider API Key in the request headers as you normally would (for example, Authorization: Bearer <OPENAI_API_KEY>).

Integration options

REST API

Call any model — whether hosted on Cloudflare or by a third-party provider — through the same Cloudflare API. No provider SDKs or API keys needed — authentication and billing are handled through your Cloudflare account. Three endpoints are available: /ai/run for all modalities, /ai/v1/chat/completions for OpenAI SDK compatibility, and /ai/v1/responses for agentic workflows.

Terminal window
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "openai/gpt-4.1-mini",
    "messages": [{"role": "user", "content": "What is Cloudflare?"}]
  }'

Refer to REST API for details and examples.

Provider-specific endpoints

For direct integration with specific AI providers, use dedicated endpoints that maintain the original provider's API schema while adding AI Gateway features.

https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/{provider}

Available providers:

Next steps