Ctrlk
WebsitePlatform

Бег

Создать новую сессию обработки видео

post

Этот эндпоинт позволяет администратору (или суб-администратору) загрузить видеофайл для обработки и создать новый ресурс "сессии" от имени другого пользователя. Сервер вернет session_id, который можно использовать для проверки статуса или получения деталей/результатов сессии.

Тело запроса (Multipart/Form-Data)

Необходимо указать следующие поля:

  • user_id (строка, обязательно): ID пользователя, от имени которого создается сессия.

  • video (файл, обязательно): Исходный видеофайл для обработки.

  • session_name (строка, опционально): Человекочитаемое название сессии.

  • incline_degree (строка или число, опционально): Числовое значение, представляющее угол наклона.

  • body_joint_angles (массив строк, опционально): Список названий суставов через запятую (например, 'elbow, knee, ankle'). По умолчанию ['all'], если не указано.

Структура ответа

При успешном выполнении (HTTP 200) ответ представляет собой JSON-объект с:

  • session_id (строка): Уникальный идентификатор созданной сессии.

  • title (строка): Название сессии (по умолчанию используется резервное значение, если session_name не указано).

Рабочий процесс

  1. Отправьте POST-запрос с multipart/form-data, содержащий обязательные поля user_id и video, а также любые опциональные поля.

  2. Укажите действительный токен API-KEY в заголовке Authorization.

  3. У вызывающего должны быть права администратора для успешного создания сессии от имени другого пользователя.

  4. В случае успеха сервер вернет session_id и title.

  5. В случае ошибки (например, отсутствие обязательных полей, недостаток прав) вернется JSON-объект с ключом error.

Пример cURL:

Authorizations
AuthorizationstringRequired

Укажите ваш Bearer-токен (Firebase auth) в формате: Bearer <токен>

Body
user_idstringRequired

Обязательно. ID пользователя, для которого создается сессия (форма: текст).

videostringRequired

Обязательно. Исходный видеофайл для обработки (форма: файл).

session_namestringOptional

Опционально. Описательное название сессии (форма: текст).

incline_degreestringOptional

Опционально. Числовая строка, указывающая угол наклона (форма: текст).

body_joint_anglesarrayOptional

Опционально. Список названий суставов через запятую. Доступные значения: 'ankle', 'knee', 'elbow', 'hip', 'shoulder'. Пример: ankle,knee,hip

Responses
200

Сессия обработки видео успешно создана (HTTP 200).

application/json
session_idstringRequired

Уникальный идентификатор созданной сессии.

titlestringRequired

Название сессии (по умолчанию, если не указано).

post
/running/sessions/

Получить общие метрики

get

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

Структура ответа (HTTP 200)

Ответ представляет собой JSON-объект со следующей структурой:

  • avg_metrics (объект): Содержит средние значения, рассчитанные по всем сессиям.

    • avg_speed (число): Средняя скорость.

    • avg_power (число): Средняя мощность.

    • avg_cadence (число): Средний каденс.

    • avg_flight_time (число): Среднее время полета.

  • last_session_metrics (объект): Содержит детальные метрики последней сессии.

    • speed (объект): Метрики скорости с:

      • avg (число): Средняя скорость.

      • min (число): Минимальная скорость.

      • max (число): Максимальная скорость.

    • normalized_power (объект): Метрики нормализованной мощности с ключами avg, min, max.

    • cadence (объект): Метрики каденса с ключами avg, min, max.

    • total_distance (число): Общее расстояние.

    • power (объект): Метрики мощности с ключами avg, min, max.

    • stride_time (объект): Метрики времени шага с ключами avg, min, max.

    • total_time (число): Общее время сессии.

    • contact_time (объект): Метрики времени контакта с ключами avg, min, max.

    • contact_angle (объект): Метрики угла контакта с ключами avg, min, max.

    • incline (объект): Метрики наклона с ключами avg, min, max.

    • pace (объект): Метрики темпа с ключами avg, min, max.

    • stride_length (объект): Метрики длины шага с ключами avg, min, max.

    • rbalance (объект): Метрики баланса с ключами avg, min, max.

    • flight_time (объект): Метрики времени полета с ключами avg, min, max.

    • footstrike (строка): Тип постановки стопы (например, 'midfoot').

  • last_session_created_at (объект): Временная метка создания последней сессии, содержащая:

    • date (строка): Дата в формате ДД/ММ/ГГГГ.

    • time (строка): Время в формате ЧЧ:MM AM/PM.

Обработка ошибок

  • 400 Неверный запрос: Неверные параметры запроса (например, неверный UID администратора).

  • 401 Неавторизован: Отсутствует или недействителен токен доступа.

  • 403 Запрещено: Недостаточно прав для получения общих метрик.

  • 404 Не найдено: Сессии не найдены или метрики недоступны.

  • 500 Внутренняя ошибка сервера: Произошла непредвиденная ошибка на сервере.

Безопасность

В заголовке Authorization должен быть указан действительный токен API-KEY.

Authorizations
AuthorizationstringRequired

Укажите ваш Bearer-токен (Firebase auth) в формате: Bearer <токен>

Responses
200

Общие метрики успешно получены.

application/json
get
/running/sessions/metrics/total/

Получить детали сессии бега

get

Получает детальную информацию о конкретной сессии бега, идентифицированной по session_id.

Параметр пути

  • session_id (строка, обязательно): Уникальный идентификатор сессии для получения.

Параметр запроса

  • demo (логический, опционально): Установите true, чтобы получить демонстрационные данные сессии бега вместо реальных.

Структура ответа

При успешном выполнении (HTTP 200) ответ представляет собой JSON-объект, содержащий следующие поля:

  • metrics (объект): Словарь массивов метрик (например, скорость, каденс, расстояние). Каждый ключ соответствует массиву чисел.

  • angles (объект): Словарь массивов углов (например, lhip_angle, rsho_angle). Каждый ключ соответствует массиву чисел.

  • all_timestamps (массив чисел): Список временных меток (в секундах) для данных сессии.

  • analyzed_video_url (строка, URI): URL анализированного видео (с наложенными ключевыми точками).

  • video_url (строка, URI): URL оригинального загруженного видео.

  • segments (целое число): Количество обработанных сегментов.

  • created_at (объект): Объект, содержащий:

    • date (строка): Дата создания в формате ДД/ММ/ГГГГ.

    • time (строка): Время создания в формате ЧЧ:MM AM/PM.

  • user_name (строка): Имя пользователя, связанного с сессией.

  • activity (строка): Тип активности (например, 'Running').

  • title (строка): Название сессии.

  • calculated_metrics (объект): Словарь, содержащий вычисленную статистику (например, средние, минимальные и максимальные значения) для различных метрик.

  • summary (строка): Опциональное текстовое резюме сессии.

Обработка ошибок

  • 400 Неверный запрос: Неверные параметры запроса (например, неверный UID администратора).

  • 401 Неавторизован: Отсутствует или недействителен токен доступа.

  • 403 Запрещено: Пользователь не имеет достаточных прав для доступа к сессии.

  • 404 Не найдено: Сессия не существует или недействительна для указанной активности.

  • 500 Внутренняя ошибка сервера: Произошла непредвиденная ошибка на стороне сервера.

Безопасность

В заголовке Authorization должен быть указан действительный токен API-KEY.

Authorizations
AuthorizationstringRequired

Укажите ваш Bearer-токен (Firebase auth) в формате: Bearer <токен>

Path parameters
session_idanyRequired
Query parameters
demobooleanOptional

Установите true, чтобы получить демонстрационные данные сессии бега вместо реальных.

Responses
200

Данные сессии успешно получены.

application/json
all_timestampsnumber[]Required

Список временных меток, связанных с сессией.

analyzed_video_urlstring · uriOptional

Публичный URL анализированного видео.

video_urlstring · uriOptional

Публичный URL оригинального видео.

segmentsintegerOptional

Количество обработанных сегментов.

user_namestringOptional

Имя пользователя, связанного с этой сессией.

activitystringRequired

Тип активности (например, 'Running').

titlestringOptional

Название сессии.

summarystringOptional

Опциональное резюме сессии.

get
/running/sessions/{session_id}/

Экспортировать данные сессии бега

get

Получает детальные данные сессии для экспорта конкретной сессии бега, идентифицированной по session_id.

Параметр пути

  • session_id (строка, обязательно): Уникальный идентификатор сессии для экспорта.

Параметр запроса

  • demo (логический, опционально): Установите true, чтобы получить предварительно сгенерированные демонстрационные данные сессии бега вместо реальных.

Структура ответа (HTTP 200)

Ответ представляет собой JSON-объект, который включает:

  • metrics (объект): Словарь, где каждый ключ представляет метрику (например, 'speed', 'cadence'), а его значение - массив чисел.

  • keypoints (объект): Словарь, где каждый ключ представляет ключевую точку (например, 'lknev', 'ltoev'), а его значение - массив чисел.

  • angles (объект): Словарь, где каждый ключ представляет угол (например, 'lelb_angle', 'lhip_angle'), а его значение - массив чисел.

  • all_timestamps (массив чисел): Массив временных меток (в секундах), соответствующих точкам данных.

  • contact (массив логических значений): Массив логических значений, указывающих статус контакта.

  • activity (строка): Тип активности (например, 'Running').

Обработка ошибок

  • 400 Неверный запрос: Неверные параметры запроса (например, неверный UID администратора).

  • 401 Неавторизован: Отсутствует или недействителен токен доступа.

  • 403 Запрещено: Пользователь не имеет достаточных прав для доступа к данным этой сессии.

  • 404 Не найдено: Запрошенная сессия не существует или недействительна для активности.

  • 500 Внутренняя ошибка сервера: Произошла непредвиденная ошибка сервера.

Безопасность

В заголовке Authorization должен быть указан действительный токен API-KEY.

Authorizations
AuthorizationstringRequired

Укажите ваш Bearer-токен (Firebase auth) в формате: Bearer <токен>

Path parameters
session_idanyRequired
Query parameters
demobooleanOptional

Установите true, чтобы получить предварительно сгенерированные демонстрационные данные сессии бега вместо реальных.

Responses
200

Данные сессии успешно экспортированы.

application/json
all_timestampsnumber[]Required

Список временных меток (в секундах).

contactboolean[]Required

Массив, указывающий статус контакта (true/false).

activitystringRequired

Тип активности (например, 'Running').

get
/running/sessions/{session_id}/export/

Анализ беговой формы

post

Получение детального отчета по анализу беговой формы для указанной сессии. Требуется действительный токен администратора и активная подписка (Pro, Premium, Enterprise или Standard).

Запрос

  • Параметр пути:

    • session_id (строка, обязательно): Уникальный идентификатор сессии, для которой запрашивается отчет.

  • Параметр запроса:

    • demo (логический, опционально): Установите true для получения демо-отчета вместо реального.

Структура ответа (HTTP 200)

Ответ в формате JSON содержит:

  • metrics (объект): Усредненные показатели шага, такие как speed, balance, cadence, contact_angle, eversion_velocity, knee_flexion, posture_angle, ankle_angle, com_oscillation, stride_angle, mean_h.

  • images (объект): Три ключевых снимка с тегами contact_angle, push_angle, knee_ankle; каждый содержит публичный URL изображения.

  • user_info (объект): Информация о пользователе:

    • age (целое число)

    • gender (строка)

    • height (число, см)

    • weight (число, кг)

    • email (строка, email)

    • uid, display_name, admin_name, last_session, phone, brand, shoeModel, shoeSize, leg_length, ycom (разные типы)

  • form_comments (объект, опционально): Рекомендации GenAI по блокам contact_angle, hip_extension_at_foot_takeoff, foot_contact_angle_and_torso_lean.

  • date (строка): Дата генерации отчета в формате ДД/ММ/ГГГГ.

Обработка ошибок

  • 400 Bad Request: Неверный токен или параметры.

  • 401 Unauthorized: Токен отсутствует или недействителен.

  • 403 Forbidden: Требуются права администратора.

  • 404 Not Found: Сессия не найдена или у пользователя нет активного тарифа.

  • 500 Internal Server Error: Непредвиденная ошибка сервера.

Безопасность

В заголовке Authorization должен быть указан действительный API-KEY токен.

Authorizations
AuthorizationstringRequired

Укажите ваш Bearer-токен (Firebase auth) в формате: Bearer <токен>

Path parameters
session_idanyRequired
Query parameters
demobooleanOptional

Установите true для получения демо-отчета.

Responses
200

Отчет успешно получен.

application/json
datestringRequired

Дата отчета в формате ДД/ММ/ГГГГ.

Example: 13/07/2025
post
/running/sessions/{session_id}/form-analysis/

Создание комментариев к анализу формы

post

Генерация персонализированных комментариев GenAI для каждого блока беговой формы (contact-angle, hip-extension at foot take-off, foot-contact angle & torso lean) плюс общая рекомендация. Возвращает идентификаторы тредов.

Запрос

  • session_id (параметр пути, обязательно): ID сессии для генерации комментариев.

Ответ (201)

JSON-объект с идентификаторами тредов:

  • contact_angle: ID треда для блока contact angle. - push_angle: ID треда для блока push angle. - knee_ankle: ID треда для блока knee-ankle. - general_form_recommendation: ID треда для общей рекомендации.

Обработка ошибок

  • 403 Forbidden: Отсутствует активный тариф. - 404 Not Found: Сессия не найдена. - 500 Internal Server Error: Непредвиденная ошибка сервера.

Безопасность

Требуется действительный API-KEY токен или ключ в заголовках.

Authorizations
AuthorizationstringRequired

Укажите ваш Bearer-токен (Firebase auth) в формате: Bearer <токен>

Path parameters
session_idanyRequired
Responses
post
/running/sessions/{session_id}/form-recommendations/

Анализ походки

post

Получение детального отчета по анализу походки для указанной сессии. Требуется действительный токен администратора и активная подписка (Pro, Premium, Enterprise или Standard).

Запрос

  • Параметр пути:

    • session_id (строка, обязательно): Уникальный идентификатор сессии.

  • Параметр запроса:

    • demo (логический, опционально): Установите true для получения демо-отчета.

Структура ответа (HTTP 200)

JSON-объект содержит:

  • left (объект) и right (объект): Данные для левой/правой стороны:

    • peak_time (число): Пиковое время в анализе.

    • initiator (строка): Инициатор цикла походки.

    • phases (объект): Фазы (flight, takeoff, mid_stance, strike, new_strike):

      • video_frame (целое число): Номер кадра.

      • graph_phase (целое число): Фаза на графике.

      • video_phase (целое число): Фаза в видео.

      • image_url (строка, URI): URL снимка фазы.

    • angles (объект): Углы (posture_angle, lhip_angle и др.):

      • current (массив[число]): Текущие значения.

      • next (массив[число]): Прогнозируемые значения.

      • std_dev (массив[число]): Стандартные отклонения.

    • graph_timestamps (массив[число]): Временные метки (мс).

  • user_info (объект): Информация о пользователе (аналогично form-analysis).

  • report_comments (объект, опционально): Рекомендации по углам.

  • date (строка): Дата отчета в формате ДД/ММ/ГГГГ.

Обработка ошибок

Аналогично endpoints form-analysis.

Безопасность

Требуется действительный API-KEY токен.

Authorizations
AuthorizationstringRequired

Укажите ваш Bearer-токен (Firebase auth) в формате: Bearer <токен>

Path parameters
session_idanyRequired
Query parameters
demobooleanOptional

Установите true для получения демо-отчета.

Responses
200

Отчет успешно получен.

application/json
report_commentsobjectOptional

(Опционально) Рекомендации по углам.

datestringRequired

Дата отчета в формате ДД/ММ/ГГГГ.

post
/running/sessions/{session_id}/gait-analysis/

Создание рекомендаций по анализу походки

post

Создание рекомендаций по анализу походки

Этот эндпоинт генерирует персонализированные рекомендации для конкретной сессии на основе анализа беговой походки пользователя. Каждая рекомендация содержит биомеханические инсайты, советы по осанке и рекомендации по тренировкам для различных углов суставов.

Пример использования: Отправьте POST запрос на /running/sessions/{session_id}/recommendation/, где {session_id} — уникальный идентификатор сессии.

Параметры:

  • session_id (строка, обязательно): Уникальный ID сессии, для которой генерируются рекомендации.

Структура ответа (HTTP 201): Возвращает JSON-объект, сопоставляющий каждый показатель угла походки с ID рекомендации, включая левую и правую стороны:

  • left_posture_angle, left_hip_angle, left_knee_angle, left_ankle_angle

  • right_posture_angle, right_hip_angle, right_knee_angle, right_ankle_angle

Примечания:

  • Сессия должна быть валидной и соответствовать отчету по анализу походки.

  • Требуется активный тарифный план (Pro, Premium, Enterprise или Standard).

Authorizations
AuthorizationstringRequired

Укажите ваш Bearer-токен (Firebase auth) в формате: Bearer <токен>

Path parameters
session_idanyRequired
Responses
post
/running/sessions/{session_id}/recommendation/

Получить сводку по беговой сессии

get

Получить подробную сводку по беговой сессии, используя её уникальный session_id. Эта сводка включает как количественные метрики производительности, так и опциональную качественную сводку, сгенерированную GenAI, если она доступна.

Инструкции по использованию:

  1. Отправьте GET запрос с session_id в параметре пути.

  2. Эндпоинт вернет JSON-объект, содержащий различные разделы сводки сессии.

Параметр запроса

  • demo (логический, опционально): Установите true, чтобы получить предварительно сгенерированную демо-сводку для этой беговой сессии.

Структура ответа:

  • summary_text (объект, опционально): Содержит комментарии, сгенерированные GenAI, если доступны. Этот объект может включать следующие ключи:

    • balance_and_posture: Комментарии по балансу и осанке атлета (например, советы по улучшению баланса при беге).

    • performance_metrics: Общие комментарии по производительности, такие как изменения скорости, каденса и мощности.

    • running_mechanics: Наблюдения по механике бега, включая время контакта, время полета, время шага и длину шага.

    • final_summary: Итоговое общее замечание, суммирующее производительность сессии.

    • distance_and_duration: Комментарии по общему расстоянию и продолжительности сессии.

  • performance_metrics (объект): Содержит агрегированные метрики производительности с их минимальными, максимальными, средними значениями и сырыми данными в виде массива, включая:

    • speed (в м/с)

    • pace (в мин/км)

    • cadence (шагов/мин)

    • power (в Ваттах)

    • normalized_power (в Вт/кг)

  • running_mechanics (объект): Содержит данные по механике бега:

    • contact_time (в секундах)

    • flight_time (в секундах)

    • stride_time (в секундах)

    • stride_length (в метрах)

    • footstrike: Строка, описывающая наиболее распространенный тип постановки стопы (например, 'forefoot').

  • balance_and_posture (объект): Содержит метрики, связанные с балансом и осанкой:

    • balance: Включает минимальный, максимальный, средний баллы баланса и массив значений баланса.

    • contact_angle: Включает минимальный, максимальный, средний углы контакта (в градусах) и массив значений углов контакта.

  • distance_and_duration (объект): Содержит сырые значения для:

    • total_distance (в метрах)

    • total_time (в секундах)

  • user_information (объект): Содержит детальную информацию о пользователе, включая:

    • ycom: Значение YCOM пользователя

    • weight: Вес пользователя в килограммах

    • age: Возраст пользователя

    • height: Рост пользователя в сантиметрах

    • leg_length: Длина ноги пользователя

    • shoeSize: Размер обуви пользователя

    • gender: Пол пользователя

    • user: Уникальный ID пользователя

    • brand: Информация о бренде обуви (если есть)

    • shoeModel: Информация о модели обуви (если есть)

    • email: Email пользователя

    • display_name: Отображаемое имя пользователя

  • session_date (строка): Дата сессии в формате строки (например, 'ДД/ММ/ГГГГ').

Примечание: Поле summary_text будет присутствовать только если для сессии сохранены комментарии, сгенерированные GenAI.

Authorizations
AuthorizationstringRequired

Укажите ваш Bearer-токен (Firebase auth) в формате: Bearer <токен>

Path parameters
session_idanyRequired
Query parameters
demobooleanOptional

Установите true, чтобы получить предварительно сгенерированную демо-сводку для этой беговой сессии.

Responses
200

Сводка сессии успешно получена

application/json
session_datestringRequired

Дата сессии в формате строки (например, '07/04/2025')

get
/running/sessions/{session_id}/summary/

Сгенерировать сводку для беговой сессии

post

Запустить генерацию сводки для беговой сессии. Этот эндпоинт создает отдельные сводки для каждого блока на основе метрик сессии, включая метрики производительности, механику бега, баланс и осанку, а также расстояние/продолжительность, а также итоговую общую сводку. Возвращает JSON-объект, содержащий ID сводок для каждого блока.

Authorizations
AuthorizationstringRequired

Укажите ваш Bearer-токен (Firebase auth) в формате: Bearer <токен>

Path parameters
session_idanyRequired
Query parameters
measurement_systemstring · enumOptional

Система измерений: 'metric' или 'imperial'

Possible values:
Responses
post
/running/sessions/{session_id}/summary/
PreviousАнализированное видеоNextПрыжки

Last updated

Was this helpful?