REST API

使用 AI Search REST API，可通过 HTTP 查询你的 AI Search 实例。

认证

所有请求都需要具有 AI Search:Edit 和 AI Search:Run 权限的 API token。

在 Cloudflare 仪表板中，前往 My Profile（我的个人资料） > API Tokens（API 令牌）。
Go to API Tokens ↗
选择 Create Token（创建令牌）。
选择 Create Custom Token（创建自定义令牌）。
输入 Token name（令牌名称），例如 AI Search Manager。
在 Permissions（权限） 下，添加两项权限：
- Account > AI Search:Edit
- Account > AI Search:Run
选择 Continue to summary（继续查看摘要），然后选择 Create Token（创建令牌）。
复制并保存 token 值。这就是你的 API_TOKEN。

在所有请求的 Authorization header 中包含该 token：

Authorization: Bearer <API_TOKEN>

搜索与 chat

AI Search 提供两个用于查询实例的 API。二者均使用与 OpenAI 兼容的 messages 格式。

Search（搜索） 返回相关内容分块（chunks）。当你希望自行处理生成或直接展示结果时使用。
聊天补全（Chat completions） 在一次调用中检索内容并生成响应。

API 路径

AI Search API 提供两个基础路径：

路径	说明
`/accounts/{account_id}/ai-search/instances/{id}/`	针对特定实例操作
`/accounts/{account_id}/ai-search/namespaces/{namespace}/instances/{id}/`	针对 namespace 内的实例操作

以下操作对两种路径均相同。关于 namespace 作用域 API，请参阅 Namespace API 参考。

Search

搜索特定实例。search 端点也接受 query 字符串参数。完整规范请参阅 Search API 参考。

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/instances/<INSTANCE_NAME>/search" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "content": "What is Cloudflare?",
        "role": "user"
      }
    ]
  }'

聊天补全

从特定实例生成响应。完整规范请参阅聊天补全 API 参考。

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/instances/<INSTANCE_NAME>/chat/completions" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "content": "What is Cloudflare?",
        "role": "user"
      }
    ]
  }'

流式传输

将 stream 设为 true，以 Server-Sent Events（SSE）形式接收响应。检索到的 chunks 会先作为 chunks 事件发送，随后是流式响应。

event: chunks
data: [{"id":"chunk-001","type":"text","score":0.85,"text":"...","item":{"key":"about-cloudflare.md","timestamp":1775925540000},"scoring_details":{"vector_score":0.85}}]

data: {"id":"id-1776072781845","created":1776072781,"model":"@cf/meta/llama-3.3-70b-instruct-fp8-fast","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" document"}}]}

data: {"id":"id-1776072781845","created":1776072781,"model":"@cf/meta/llama-3.3-70b-instruct-fp8-fast","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" you provided doesn"}}]}

data: {"id":"id-1776072781845","created":1776072781,"model":"@cf/meta/llama-3.3-70b-instruct-fp8-fast","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"'t contain"}}]}

data: {"id":"id-1776072781845","created":1776072781,"model":"@cf/meta/llama-3.3-70b-instruct-fp8-fast","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" information"}}]}

data: [DONE]

跨实例搜索与 chat

search 与 chat completions API 也可在 namespace 级别使用。其工作方式与实例端点相同，但需传入 instance_ids 数组以指定要查询的实例。响应中的每个 chunk 都包含 instance_id 字段，标识其来源实例。完整规范请参阅 Namespace API 参考。

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/namespaces/<NAMESPACE>/search" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is Cloudflare?"
      }
    ],
    "ai_search_options": {
      "instance_ids": ["product-docs", "customer-abc123"]
    }
  }'