Capabilities API

Все возможности BeatAPI используются одинаково: данные соцсетей (Xiaohongshu, Douyin, TikTok, Bilibili, Weibo, X, Instagram, YouTube и других), модели текста, изображений, видео и решений, веб-поиск и медиапроцессы. Достаточно трёх вызовов:

Search: найдите нужную пользователю возможность и выберите reference.
Inspect: получите по этой ссылке входные данные, цену и готовность.
Run: выполните вызов и получите результат либо задачу для проверки статуса.

Каждый ответ содержит next с точным следующим вызовом. Агент копирует его и заполняет <placeholders>, а не угадывает контракт. Копируйте ссылки reference точно из ответа, не составляйте их самостоятельно.

Search и Inspect бесплатны и не требуют ключа. Run расходует баланс и требует Authorization: Bearer <BeatAPI API key>; ключ принимается с префиксом sk- и без него. Те же операции доступны как инструменты MCP capabilities_search, capabilities_inspect и capabilities_run по адресу https://beatapi.io/mcp.

Search

curl -sS -X POST https://api.beatapi.io/v1/capabilities/search \
  -H 'Content-Type: application/json' \
  -d '{"query":"小红书 搜索笔记"}'

Поле	Тип	Значение
`query`	string	Задача словами пользователя: платформа и действие на китайском или английском (`抖音用户作品`, `tiktok user profile`, `video model`). Подойдёт и целое предложение.
`kind`	string	Необязательно: `model`, `data` или `workflow`.
`platform`	string	Необязательно: slug или название, например `xiaohongshu` или `小红书`.
`limit`	integer	1–50, по умолчанию 5.
`cursor`	string	`next_cursor` предыдущей страницы.
`view`	string	`compact` по умолчанию возвращает по карточке на результат; `full` — полные контракты.
`group_by`	string	`function` группирует совпадения по назначению.

Поле data содержит компактные карточки: reference, title, summary, price, readiness и однострочное описание входа signature. Поле understood показывает, какие слова запроса учтены, а какие пропущены.

Обзор. Если запрос содержит только платформу (小红书) или задан group_by: "function", ответ заполняет groups: функции платформы — поиск, контент, комментарии, пользователи, тренды, ленты, торговля и эфиры. В каждой группе есть количество, примеры reference и аргументы search для остальных результатов. Пустой запрос возвращает карту каталога.
Нет совпадений. Вместо пустой страницы ответ содержит hints с подсказками по переформулировке и slug платформ.

Inspect

curl -sS -X POST https://api.beatapi.io/v1/capabilities/inspect \
  -H 'Content-Type: application/json' \
  -d '{"reference":"data:xiaohongshu.app_v2.search_notes"}'

Inspect возвращает полный контракт: input_schema с обязательными полями, типами и ограничениями; pricing; execution.mode (sync возвращает результат сразу, async — задачу); readiness и next — вызов Run с готовым reference и заглушками обязательных входных полей.

`readiness`	Значение
`ready`	Выполняется через Run; вход, выход и цена опубликованы.
`runnable`	Выполняется через Run, вход описан, но структура выхода не опубликована: читайте нужные данные из результата.
`listed`	Не выполняется через Run либо вход не описан. Причина указана в `next`; найдите альтернативу.

Угаданный или ошибочный reference возвращает 404 not_found с suggestions — ближайшими опубликованными ссылками — и next, который проверяет наиболее подходящую.

Run

curl -sS -X POST https://api.beatapi.io/v1/capabilities/run \
  -H "Authorization: Bearer $BEATAPI_API_KEY" -H 'Content-Type: application/json' \
  -d '{"reference":"data:xiaohongshu.app_v2.search_notes","input":{"keyword":"AI 视频"},"view":"preview"}'

Поле	Значение
`reference`	Ссылка reference, проверенная через Inspect.
`operation`	`start` по умолчанию, `status` или `result`.
`input`	Для `start`: соответствует проверенной `input_schema`. Неизвестные поля внутри `input` отклоняются.
`task_id`	Для `status`: задача, возвращённая асинхронным запуском.
`request_id`	Для `result`: `request_id`, возвращённый синхронным запуском.
`view`	`full` по умолчанию в REST либо `preview`. Применяется и при проверке статуса.
`max_items`	При `preview`: сколько элементов оставить в `items`, по умолчанию 5, максимум 50.
`fields`	Сохраняемые пути: `items[].<key>` для ключей каждого элемента списка, иначе пути от корня через точку (`[]` проходит массив).
`idempotency_key`	Уникальный ключ задачи на верхнем уровне рядом с `reference` либо заголовок `Idempotency-Key`. Повторно используйте только для повтора того же запуска.

Ответ запуска зависит от вида возможности:

Вид	Режим	`input`	Результат
Данные соцсетей и веба	sync	`input_schema` действия	Объект данных; при `preview` список находится в `items`
Веб-исследование (`data:web.research`)	async, от 30 с до 3 мин	`{"query": …}`	Задача: проверяйте по указанию `next` каждые 10–15 секунд; результат в `data.output`, неудачный запуск не оплачивается
Текстовые модели	sync	`{"input": "<prompt or messages>"}`, необязательные `instructions`, `max_output_tokens`, `temperature`	`{object: "text.result", model, status, output_text, usage, request_id}`
JEV (`model:jev-1.14`, `model:jev-1.14-free`)	sync	`{"state": …, "questions": …}`	`{id, model, answers, usage}`
Модерация текста (`model:beat-moderation-1.0`)	sync	`{"input": "<text to check>"}`	`{id, model, results, policy_version, usage}`
Модерация изображения (`model:beat-moderation-vision-1.0`)	sync	`{"image_url": "<link or data URL>", "input": "<optional text>"}`	`{id, model, results, policy_version, usage}`
Модерация текста и до четырёх изображений (`model:beat-moderation-2.0`)	sync	`{"input": "<optional text>", "image_urls": ["<link or data URL>"]}`; одно изображение также можно передать через `image_url`	`{id, model, results, policy_version, usage}`
Модели изображений, видео и рабочие процессы	async	`input_schema` возможности	Задача: проверяйте через `operation: "status"` каждые 5–10 секунд до `succeeded` или `failed`

Представление результата. Ответы платформ могут занимать десятки килобайт, а списки находятся в разных вложенных полях. При view: "preview" основной список поднимается в верхнеуровневый items: сохраняются первые max_items элементов с сокращёнными полями. Поле items_path указывает исходный путь (data.data.items, results, …), а items_total — общее число. Длинные строки сокращаются, размер ответа ограничен; ответ помечается truncated и содержит result_ref. Поле fields оставляет только указанные пути, например items[].<key> для ключей каждого элемента. Полный результат можно бесплатно получить тем же ключом в течение часа:

{ "reference": "data:xiaohongshu.app_v2.search_notes", "operation": "result", "request_id": "<request_id>", "fields": ["items[].<key>"] }

В REST по умолчанию используется view: "full", на MCP-сервере — preview.

Формат `next` для вашего клиента

Передайте X-Beat-Client: mcp или http по умолчанию. Это меняет только запись next.call:

http: полная команда curl к https://api.beatapi.io с Authorization: Bearer $BEATAPI_API_KEY для вызовов с ключом.
mcp: {"tool": "capabilities_run", "arguments": {…}}. MCP-сервер BeatAPI передаёт этот заголовок самостоятельно.

Поле next.action содержит search, inspect, run, status, result или none; next.note объясняет, что вернёт вызов.

Ошибки

Каждая ошибка содержит retryable. Если оно равно false, исправьте запрос, а не повторяйте его. Полная таблица есть в разделе ошибок.

Статус	Код	Что делать
400	`bad_request`	Повторите Inspect и исправьте указанное поле.
401	`missing_api_key`	Ключ не передан: добавьте `Authorization: Bearer <key>`.
401	`invalid_api_key`	Ключ неверен, просрочен, отключён или исчерпал лимит. Проверьте его в панели управления; не повторяйте запрос.
402	`insufficient_credits`	Пополните баланс.
403	`forbidden`	Ключу или аккаунту недоступна возможность, например модель нельзя оплачивать бонусом. Пополнение открывает доступ.
404	`not_found`	Используйте вариант из `suggestions` или повторите поиск.
409	`idempotency_conflict`	Тот же `idempotency_key` использован для другого запроса; задайте новый ключ.
429	`rate_limit_exceeded`	Подождите время из `Retry-After`, также указанное в `retry_after_seconds`. Бесплатный JEV допускает один запрос в минуту до первого пополнения.
500	`internal_error`	Повторите один раз.
503	`processing_unavailable` или другой код `processing_*`	Вызов не завершён и не оплачен. Повторите позже с увеличивающейся задержкой; для повтора асинхронного запуска используйте тот же `idempotency_key`.

В MCP вызов, дошедший до шлюза, всегда возвращает результат инструмента. Ошибка шлюза передаётся с isError: true и тем же JSON-объектом ошибки в текстовом содержимом, чтобы агент мог прочитать причину и исправить вызов.

Для агентных платформ с импортом OpenAPI

https://beatapi.io/agent-openapi.json — сокращённый OpenAPI-документ с этими тремя операциями, веб-поиском, Bearer-авторизацией и описаниями для агентов. Импортируйте его в платформу, создающую инструменты из OpenAPI. Полный контракт находится в https://beatapi.io/openapi.json, руководство агента — в https://beatapi.io/skill.md.