← Обзор / ai-search / api / search

REST API

Используйте REST API AI Search, чтобы отправлять запросы к экземплярам AI Search по HTTP.

Аутентификация

Для всех запросов требуется токен API с AI Search:Edit и AI Search:Run разрешения.

В панели управления Cloudflare перейдите в My Profile > API-токены.
Перейдите в API-токены ↗
Выберите Create Token.
Выберите Create Custom Token.
Введите Имя токена, например AI Search Manager.
В разделе Разрешения, добавьте два разрешения:
- Аккаунт > AI Search:Edit
- Аккаунт > AI Search:Run
Выберите Continue to summary, затем выберите Create Token.
Скопируйте и сохраните значение токена. Это ваш API_TOKEN.

Включите токен в Authorization заголовок для всех запросов:

Authorization: Bearer <API_TOKEN>

Поиск и чат

AI Search предоставляет два API для выполнения запросов к экземпляру. Оба используют совместимый с OpenAI messages формате.

Поиск возвращает релевантные чанки контента. Используйте этот вариант, если хотите сами обрабатывать генерацию или выводить результаты напрямую.
Chat completions получает контент и одним вызовом генерирует ответ.

Пути API

API AI Search доступны по двум базовым путям:

Путь	Описание
`/accounts/{account_id}/ai-search/instances/{id}/`	Работает с конкретным экземпляром
`/accounts/{account_id}/ai-search/namespaces/{namespace}/instances/{id}/`	Работает с экземплярами в пределах пространство имён

Следующие операции одинаковы для обоих путей. Для API, привязанного к пространству имён, см. Справочник по API пространства имён.

Поиск

Выполните поиск в конкретном экземпляре. Эндпойнт поиска также принимает query строковый параметр. Полную спецификацию см. в Справочник по 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"
      }
    ]
  }'

Chat completions

Сгенерировать ответ из конкретного экземпляра. Полную спецификацию см. в Справочник по API Chat completions.

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 событие, за которым следует потоковый ответ.

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]

Поиск и чат между экземплярами

API поиска и chat completions также доступны на уровне пространства имён. Они работают так же, как конечные точки экземпляра, но вы передаёте instance_ids массив, чтобы указать, какие экземпляры нужно запросить. Каждый чанк в ответе включает instance_id поле, указывающее, из какого экземпляра он получен. Полную спецификацию см. в Справочник по 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"]
    }
  }'