REST API

REST API 允许你通过同一个 Cloudflare API 调用任何模型 — 无论托管在 Cloudflare 上还是 OpenAI、Anthropic 或 Google 等第三方提供商 — 并自动应用所有 AI Gateway 功能 — 日志记录、缓存、速率限制等。

无需提供商 SDK 或 API 密钥。身份验证和计费通过你的 Cloudflare 账户处理。第三方模型通过 Unified Billing 计费，Workers AI 模型遵循 Workers AI 定价。

端点

提供四个端点，每个适用于不同用例：

端点	格式	用例	第三方模型	Workers AI 模型 (`@cf/`)
`POST /ai/run`	包含 `model`、`input` 的信封	所有模型和模态（LLM、图像、TTS、ASR）	✅ 是	✅ 是
`POST /ai/v1/chat/completions`	OpenAI chat completions	LLM — 兼容 OpenAI SDK	✅ 是	✅ 是
`POST /ai/v1/responses`	OpenAI Responses API	智能体工作流 — 兼容 OpenAI SDK	✅ 是	✅ 取决于模型
`POST /ai/v1/messages`	Anthropic Messages API	LLM — 兼容 Anthropic SDK	✅ 是	❌ 否

身份验证

使用具有 AI Gateway 权限的 Cloudflare API 令牌进行身份验证。在 Authorization 标头中传递它。

模型命名

第三方模型使用 author/model 格式：

openai/gpt-4.1 — OpenAI
anthropic/claude-sonnet-4 — Anthropic
google/gemini-3-flash — Google
xai/grok-3 — xAI

Workers AI 模型使用 @cf/author/model 格式（例如 @cf/moonshotai/kimi-k2.6）。Workers AI 请求还需要 cf-aig-gateway-id 标头 — 请参阅调用 Workers AI 模型了解详情。

在模型目录中浏览可用模型。

`/ai/run` — 通用端点

接受任何模型及其每模型架构。模型特定参数放在 input 内。

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/run" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "openai/gpt-4.1",
    "input": {
      "messages": [
        {
          "role": "user",
          "content": "What is Cloudflare?"
        }
      ],
      "max_tokens": 512
    }
  }'

调用 Workers AI 模型

要调用 Workers AI 模型，在模型名称中使用 @cf/ 前缀，并包含 cf-aig-gateway-id 标头以指定路由通过的 gateway。

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/run" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "cf-aig-gateway-id: default" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "@cf/moonshotai/kimi-k2.6",
    "input": {
      "messages": [
        {
          "role": "user",
          "content": "What is Cloudflare?"
        }
      ]
    }
  }'

URL 路径中包含模型 ID 的现有 Workers AI 端点仍然可用：

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/run/@cf/moonshotai/kimi-k2.6" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "messages": [
      {
        "role": "user",
        "content": "What is Cloudflare?"
      }
    ]
  }'

`/ai/v1/chat/completions` — 兼容 OpenAI

使用标准 OpenAI chat completions 格式。model 字段使用相同的 author/model 命名。此端点兼容 OpenAI SDK 和其他兼容 OpenAI 的客户端。

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
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",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "What is Cloudflare?"
      }
    ],
    "max_tokens": 512,
    "temperature": 0.7,
    "stream": true
  }'

OpenAI SDK

将 OpenAI SDK 的 baseURL 指向 Cloudflare API：

import OpenAI from "openai";

const openai = new OpenAI({
	apiKey: CLOUDFLARE_API_TOKEN,
	baseURL: `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/ai/v1`,
});

const response = await openai.chat.completions.create({
	model: "openai/gpt-4.1",
	messages: [{ role: "user", content: "What is Cloudflare?" }],
});

`/ai/v1/responses` — OpenAI Responses API

使用 OpenAI Responses API 格式进行智能体工作流。兼容 OpenAI SDK。

import OpenAI from "openai";

const openai = new OpenAI({
	apiKey: CLOUDFLARE_API_TOKEN,
	baseURL: `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/ai/v1`,
});

const response = await openai.responses.create({
	model: "openai/gpt-4.1",
	input: "What is Cloudflare?",
});

`/ai/v1/messages` — 兼容 Anthropic

使用 Anthropic Messages API 格式。兼容 Anthropic SDK。

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/messages" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "anthropic/claude-sonnet-4-5",
    "max_tokens": 512,
    "messages": [
      {
        "role": "user",
        "content": "What is Cloudflare?"
      }
    ]
  }'

将 Anthropic SDK 的 baseURL 指向 Cloudflare API：

import Anthropic from "@anthropic-ai/sdk";

const anthropic = new Anthropic({
	apiKey: CLOUDFLARE_API_TOKEN,
	baseURL: `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/ai/v1`,
});

const message = await anthropic.messages.create({
	model: "anthropic/claude-sonnet-4-5",
	max_tokens: 512,
	messages: [{ role: "user", content: "What is Cloudflare?" }],
});

提供商工具和 Web 搜索

某些提供商通过这些端点公开原生工具 — 包括服务端 Web 搜索。请参阅 Web Search 了解每个提供商支持的模型及各自使用的请求格式。在模型目录中浏览规范模型 ID。

指定 gateway

默认情况下，第三方模型请求通过你账户的默认 AI Gateway 路由。要使用特定 gateway，请包含 cf-aig-gateway-id 标头。Workers AI 请求始终需要此标头。

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "cf-aig-gateway-id: default" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "anthropic/claude-sonnet-4",
    "messages": [
      {
        "role": "user",
        "content": "Hello"
      }
    ]
  }'

使用 OpenAI SDK 时，通过 defaultHeaders 设置标头：

const openai = new OpenAI({
	apiKey: CLOUDFLARE_API_TOKEN,
	baseURL: `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/ai/v1`,
	defaultHeaders: {
		"cf-aig-gateway-id": "default",
	},
});

在该 gateway 上配置的所有 AI Gateway 功能 — 缓存、速率限制、Guardrails 和日志记录 — 都适用于该请求。

按请求配置

使用 cf-aig-* 标头按请求控制 AI Gateway 行为：

标头	类型	说明
`cf-aig-skip-cache`	boolean	对此请求跳过缓存。
`cf-aig-cache-ttl`	number	缓存 TTL（秒）。
`cf-aig-cache-key`	string	自定义缓存键。
`cf-aig-collect-log`	boolean	对此请求开启或关闭日志记录。
`cf-aig-request-timeout`	number	请求超时（毫秒）。
`cf-aig-max-attempts`	number	重试次数（最多 5 次）。
`cf-aig-retry-delay`	number	重试延迟（毫秒，最多 5000）。
`cf-aig-backoff`	string	退避方法：`constant`、`linear` 或 `exponential`。
`cf-aig-metadata`	JSON string	附加到日志条目的自定义元数据。

有关这些选项的更多详情，请参阅请求处理和缓存。