Анализ видео

POST https://api.beatapi.io/v1/video-analysis/tasks

Анализируйте загруженный MP4 или MOV с временными метками, используя стандартный или углублённый мультимодальный анализ.

Авторизация

Authorization   string   обязательный

Передавайте API-ключ BeatAPI как токен Bearer. Создать ключ можно в панели управления.

Authorization: Bearer <BEATAPI_API_KEY>

Храните постоянные API-ключи на доверенных серверах. Для тела запроса обязателен Content-Type: application/json. Если метод принимает Idempotency-Key, этот заголовок необязателен, но рекомендуется для безопасных повторных попыток с точно таким же телом.

Тело запроса

video_url   string   обязательный

Ссылка на MP4 или MOV в хранилище BeatAPI, полученная через POST /v1/files для текущего аккаунта. Максимальная проверенная длительность — 600 секунд.

Формат: uri

prompt   string   обязательный

Инструкция для анализа. Запрашивайте временные метки, если важно точно указать момент события.

Длина: 1 – 12000 символов

analysis_depth   enum<string>   необязательный

Standard — недорогой режим по умолчанию; deep использует более интенсивные рассуждения.

Допустимые значения: standard, deep
По умолчанию: "standard"

max_output_tokens   integer   необязательный

Запрошенный лимит ответа. Использование, сообщённое провайдером, может включать скрытые токены рассуждений сверх этого значения. BeatAPI записывает расхождение для проверки и рассчитывает фактическую стоимость в пределах резерва задачи.

По умолчанию: 2048
Диапазон: 256 – 8192

Ответ

Успешный запрос возвращает HTTP 201.

{
  "data": {
    "id": "task_va8K2qA",
    "object": "task",
    "task_kind": "workflow",
    "capability_id": "video-analysis",
    "capability_version": 1,
    "workflow": "video-analysis",
    "status": "queued",
    "stage": "queued",
    "created_at": 1787385600,
    "updated_at": 1787385600,
    "completed_at": null,
    "output": null,
    "usage": {
      "credits_reserved": 0.01,
      "credits_charged": 0.01,
      "billable_duration_seconds": 60,
      "credits_settled": 0,
      "credits_refunded": 0
    },
    "request_id": "req_va123",
    "error_code": null,
    "error_message": null
  }
}

Глубина анализа и оплата

standard — режим по умолчанию для краткого содержания, деления на фрагменты, временных меток и извлечения данных. Используйте deep, если нужны более подробные рассуждения о движении, контакте, непрерывности действия или неоднозначных событиях.

BeatAPI принимает только MP4 или MOV длительностью до 600 секунд, загруженные тем же аккаунтом через POST /v1/files. По проверенной длительности дорожки рассчитывается резерв входных токенов с запасом. После завершения стоимость определяется по проверенным данным провайдера о входных и выходных токенах.

Актуальные тарифы указаны на странице Video Analysis API и /pricing. Эта страница описывает только контракт запроса.

При создании резервируется максимально возможная сумма для запроса, после чего возвращается задача в очереди. Неиспользованный резерв возвращается после проверки и расчёта фактического числа токенов. Стоимость каждой завершённой задачи округляется вверх до ближайшего $0.01, поскольку общий баланс USD рассчитывается в центах.

По умолчанию модель просматривает обычное видео примерно с частотой 1 FPS. Быстрые действия и частые склейки могут быть пропущены. Если важно движение на уровне кадров, запрашивайте временные метки и используйте более короткие фрагменты.

Следующий шаг

Готовый анализ находится в data.output.text, использование токенов — в data.output.usage. Если задача ожидает свободных ресурсов, опрашивайте GET /v1/tasks/{task_id} до успеха или ошибки.

Ошибки