REST API

本指南将引导你使用 REST API 创建 AI Search 实例。

1. 创建 API token

你需要具有 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。

2. 创建 AI Search 实例

使用 Create instance API 创建实例。将 <ACCOUNT_ID> 替换为你的账户 ID。

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/instances" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  --data '{
    "id": "my-instance"
  }'

连接数据源（可选）

你可以创建连接到网站或 R2 存储桶作为数据源的实例。AI Search 会自动索引内容。

网站：

自动抓取并索引你拥有的网站。

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/instances" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  --data '{
    "id": "my-instance",
    "type": "web-crawler",
    "source": "example.com"
  }'

R2 存储桶：

索引存储在 R2 存储桶中的文档。连接 R2 存储桶需要 service API token。如果此前从未创建过基于 R2 的实例，需要在创建请求中传入 token_id 字段。设置说明请参阅 service API token 配置。

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/instances" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  --data '{
    "id": "my-instance",
    "type": "r2",
    "source": "<R2_BUCKET_NAME>",
    "token_id": "<SERVICE_TOKEN_ID>"
  }'

3. 添加内容

如果创建实例时未连接数据源，请使用 Items API 上传文件。若已连接网站或 R2 存储桶，可跳过此步骤。

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/instances/my-instance/items" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -F "file=@/path/to/your/file.pdf"

AI Search 会自动索引已上传的文件。

4. 检查索引状态

检查内容是否已完成索引。

curl "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/instances/my-instance/stats" \
  -H "Authorization: Bearer <API_TOKEN>"

试用

索引完成后，运行你的第一个查询。

curl "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/instances/my-instance/search" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "content": "How do I get started?",
        "role": "user"
      }
    ]
  }'

你也可以在仪表板中测试查询：进入你的实例并选择 Playground（演练场） 选项卡。

REST API

1. 创建 API token

2. 创建 AI Search 实例

连接数据源（可选）

3. 添加内容

4. 检查索引状态

试用

集成到应用

Workers binding

REST API