> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.beatapi.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server. # Capabilities API > Единый цикл Search → Inspect → Run для данных соцсетей, моделей, веб-поиска и рабочих процессов BeatAPI. Каждый ответ указывает следующий вызов. # Capabilities API Все возможности BeatAPI используются одинаково: данные соцсетей (Xiaohongshu, Douyin, TikTok, Bilibili, Weibo, X, Instagram, YouTube и других), модели текста, изображений, видео и решений, веб-поиск и медиапроцессы. Достаточно трёх вызовов: 1. **Search**: найдите нужную пользователю возможность и выберите `reference`. 2. **Inspect**: получите по этой ссылке входные данные, цену и готовность. 3. **Run**: выполните вызов и получите результат либо задачу для проверки статуса. Каждый ответ содержит `next` с точным следующим вызовом. Агент копирует его и заполняет ``, а не угадывает контракт. Копируйте ссылки reference точно из ответа, не составляйте их самостоятельно. Search и Inspect бесплатны и не требуют ключа. Run расходует баланс и требует `Authorization: Bearer `; ключ принимается с префиксом `sk-` и без него. Те же операции доступны как инструменты MCP `capabilities_search`, `capabilities_inspect` и `capabilities_run` по адресу `https://beatapi.io/mcp`. ## Search ```bash 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 ```bash 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 ```bash 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[].` для ключей каждого элемента списка, иначе пути от корня через точку (`[]` проходит массив). | | `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": ""}`, необязательные `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": ""}` | `{id, model, results, policy_version, usage}` | | Модерация изображения (`model:beat-moderation-vision-1.0`) | sync | `{"image_url": "", "input": ""}` | `{id, model, results, policy_version, usage}` | | Модерация текста и до четырёх изображений (`model:beat-moderation-2.0`) | sync | `{"input": "", "image_urls": [""]}`; одно изображение также можно передать через `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[].` для ключей каждого элемента. Полный результат можно бесплатно получить тем же ключом в течение часа: ```json { "reference": "data:xiaohongshu.app_v2.search_notes", "operation": "result", "request_id": "", "fields": ["items[]."] } ``` В 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`, исправьте запрос, а не повторяйте его. Полная таблица есть в разделе [ошибок](/errors). | Статус | Код | Что делать | | ------ | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | `bad_request` | Повторите Inspect и исправьте указанное поле. | | 401 | `missing_api_key` | Ключ не передан: добавьте `Authorization: Bearer `. | | 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`.