服务 API 令牌

服务 API 令牌授予 AI Search 访问您账户中 R2 存储桶的权限。仅当您将 R2 存储桶连接为数据源时才需要此令牌。如果您使用网站或通过 Items API 直接上传文件，则不需要服务 API 令牌。

何时需要服务 API 令牌

当您创建 type: "r2" 的 AI Search 实例时，需要服务 API 令牌。该令牌授权 AI Search 从您的 R2 存储桶读取对象以建立索引。

通过仪表板或 Wrangler 创建

获取服务 API 令牌最简单的方式是至少一次通过仪表板或 Wrangler CLI 创建基于 R2 的 AI Search 实例。Cloudflare 会在设置流程中自动为您创建并注册服务令牌。

创建后，该令牌会保存到您的账户，并在所有 AI Search 实例之间复用。您无需为每个实例创建新令牌。

通过 API 创建

如果需要以编程方式创建服务 API 令牌，请按以下步骤操作。

1. 创建具有令牌创建权限的 API 令牌

您需要一个具有创建其他令牌权限的 API 令牌。

在 Cloudflare 仪表板中，前往 My Profile（我的个人资料） > API Tokens（API 令牌）。
Go to API Tokens ↗
选择 Create Token（创建令牌）。
选择 Create Custom Token（创建自定义令牌）。
输入 Token name（令牌名称），例如 Token Creator。
在 Permissions（权限） 下，选择 User（用户） > API Tokens（API 令牌） > Edit（编辑）。
选择 Continue to summary（继续到摘要），然后选择 Create Token（创建令牌）。
复制并保存令牌值。这是您的 CREATOR_TOKEN。

2. 创建服务令牌

使用 Create token API 创建具有 AI Search Index Engine 权限的服务令牌。将 <CREATOR_TOKEN> 替换为第 1 步中的令牌，将 <ACCOUNT_ID> 替换为您的账户 ID。

curl -X POST "https://api.cloudflare.com/client/v4/user/tokens" \
  -H "Authorization: Bearer <CREATOR_TOKEN>" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "AI Search Service API Token",
    "policies": [
      {
        "effect": "allow",
        "resources": {
          "com.cloudflare.api.account.<ACCOUNT_ID>": "*"
        },
        "permission_groups": [
          { "id": "9e9b428a0bcd46fd80e580b46a69963c" }
        ]
      }
    ]
  }'

保存响应中的 id 和 value：

{
	"result": {
		"id": "<CF_API_ID>",
		"name": "AI Search Service API Token",
		"status": "active",
		"value": "<CF_API_KEY>"
	},
	"success": true
}

3. 向 AI Search 注册令牌

使用 AI Search tokens API 注册服务令牌。将 <API_TOKEN> 替换为具有 AI Search Edit 权限的 API 令牌。

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/tokens" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  --data '{
    "cf_api_id": "<CF_API_ID>",
    "cf_api_key": "<CF_API_KEY>",
    "name": "AI Search Service Token"
  }'

保存响应中的 id。这是创建基于 R2 的实例时要传递的 token_id：

{
	"success": true,
	"result": {
		"id": "<TOKEN_ID>",
		"name": "AI Search Service Token",
		"cf_api_id": "<CF_API_ID>",
		"created_at": "2025-12-25 01:52:28",
		"enabled": true
	}
}

4. 创建实例时使用令牌

创建基于 R2 的实例时传递 token_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-r2-docs",
    "type": "r2",
    "source": "<R2_BUCKET_NAME>",
    "token_id": "<TOKEN_ID>"
  }'

管理令牌

注册后，服务 API 令牌会安全存储，并在您账户中的所有 AI Search 实例之间复用。

轮换令牌

要从仪表板创建新的服务 API 令牌：

在 Cloudflare 仪表板中前往现有的 AI Search 实例。
Go to AI Search ↗
选择 Settings（设置）。
在 General（常规） 下，找到 Service API Token（服务 API 令牌） 并选择编辑图标。
选择 Create a new token（创建新令牌）。
选择 Save（保存）。

要通过 API 创建新令牌，请按照上面的第 1 步至第 3 步操作。

查看已注册的令牌

列出您账户中已向 AI Search 注册的服务 API 令牌：

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