AI ПаделДокументация API На сайт

Сервер корта: компьютерное зрение

Розыгрыши с траекторией мяча, итог матча, здоровье камер и брони на корты. Запись — клубный токен; чтение — клубный токен или токен игрока.

Базовый адрес: https://адрес-вашего-сервера/api · Руководство по разделу: Сервер корта и облако

Розыгрыш целиком #

POST/v1/cv/rally

Доступ: Клубный токен Заголовок X-Club-Token: <клубный токен> — токен сервера корта клуба.

Розыгрыш целиком: время, прореженная траектория мяча в пикселях кадра, удары со скоростью, победившая команда. Повтор того же rally_no перезаписывает запись — очередь корта после обрыва связи может слать дубли.

Заголовки

ИмяТипОбязательноОписание
x-club-tokenстрокадаКлубный токен сервера корта

Тело запроса application/json

ПолеТипОбязательноОписание
match_idстрока (uuid)даmatchId
courtстроканетИмя корта
rally_noцелоедаНомер розыгрыша — по нему повтор перезаписывает запись
не меньше 0
t_startчислодаНачало, unix-секунды
t_endчислодаКонец, unix-секунды
duration_sчислонетДлительность, с; 0 — посчитать из t_start и t_end
по умолчанию 0.0
pathмассив [массив [число]]нетПрореженная траектория мяча [x, y] в пикселях кадра, до 400 точек
элементов до 400
path_fwцелоенетШирина кадра траектории
по умолчанию 0
path_fhцелоенетВысота кадра траектории
по умолчанию 0
shotsмассив [объект]нетУдары, до 500
элементов до 500
shots[].tчислодаВремя удара, unix-секунды
shots[].v_kmhчислонетСкорость, км/ч
по умолчанию 0.0
shots[].xцелоенетx в пикселях кадра
по умолчанию 0
shots[].yцелоенетy в пикселях кадра
по умолчанию 0
max_kmhчислонетМаксимальная скорость, км/ч
по умолчанию 0.0
avg_kmhчислонетСредняя скорость, км/ч
по умолчанию 0.0
shots_countцелоенетЧисло ударов; 0 — по длине shots
по умолчанию 0
winner_teamстрока, или nullнетВыигравшая команда: A или B (1 и 2 тоже принимаются)

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

curl -X POST "https://адрес-вашего-сервера/api/v1/cv/rally" \
  -H "X-Club-Token: <клубный токен>" \
  -H "Content-Type: application/json" \
  -d '{
  "match_id": "8c0f4a52-2d1e-4b7a-9f63-1a5e7d9b3c20",
  "court": "court4",
  "rally_no": 1,
  "t_start": 1759418000.0,
  "t_end": 1759418012.4,
  "duration_s": 12.4,
  "path": [[312, 401], [355, 380]],
  "path_fw": 1024,
  "path_fh": 768,
  "shots": [{"t": 1759418001.2, "v_kmh": 74.0, "x": 312, "y": 401}],
  "max_kmh": 96.0,
  "avg_kmh": 58.2,
  "shots_count": 7,
  "winner_team": "A"
}'

Ответы

КодdetailЗначение
200—Успешный ответ; пример ниже
401bad_club_tokenНеверный клубный токен
404match_not_foundМатч не найден, чужого клуба или вы не участник
422[…]Ошибка проверки параметров или тела: detail — список ошибок

Пример ответа

{"ok": true, "rallyId": "1f7c2a90-3b4d-4e5f-8a6b-7c8d9e0f1a2b", "shots": 9}

Итог матча #

POST/v1/cv/match-summary

Доступ: Клубный токен Заголовок X-Club-Token: <клубный токен> — токен сервера корта клуба.

Итог матча: число розыгрышей, скорости, тепловая карта и маршруты мяча. Повтор обновляет итог, вторая карта не создаётся. Если есть розыгрыши и удары, облако заполняет у матча среднее число ударов за розыгрыш.

Заголовки

ИмяТипОбязательноОписание
x-club-tokenстрокадаКлубный токен сервера корта

Тело запроса application/json

ПолеТипОбязательноОписание
match_idстрока (uuid)даmatchId
courtстроканетИмя корта
ralliesцелоенетЧисло розыгрышей
по умолчанию 0
max_kmhчислонетМаксимальная скорость, км/ч
по умолчанию 0.0
avg_kmhчислонетСредняя скорость, км/ч
по умолчанию 0.0
total_shotsцелоенетВсего ударов
по умолчанию 0
heatмассив [массив [число]]нетТепловая карта: [x, y, n] — клетка в пикселях кадра и счётчик, до 8000
элементов до 8000
trailsмассив [массив [число]]нетМаршруты мяча: [x1, y1, x2, y2, n] — переход между клетками и счётчик, до 4000
элементов до 4000
fwцелоенетШирина кадра
по умолчанию 0
fhцелоенетВысота кадра
по умолчанию 0

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

curl -X POST "https://адрес-вашего-сервера/api/v1/cv/match-summary" \
  -H "X-Club-Token: <клубный токен>" \
  -H "Content-Type: application/json" \
  -d '{
  "match_id": "8c0f4a52-2d1e-4b7a-9f63-1a5e7d9b3c20",
  "court": "court4",
  "rallies": 42,
  "max_kmh": 118.0,
  "avg_kmh": 61.5,
  "total_shots": 310,
  "heat": [[320, 240, 7]],
  "trails": [[320, 240, 360, 260, 3]],
  "fw": 1024,
  "fh": 768
}'

Ответы

КодdetailЗначение
200—Успешный ответ; пример ниже
401bad_club_tokenНеверный клубный токен
404match_not_foundМатч не найден, чужого клуба или вы не участник
422[…]Ошибка проверки параметров или тела: detail — список ошибок

Пример ответа

{"ok": true, "heat": 120, "trails": 64}

Здоровье корта раз в 10 с #

POST/v1/cv/health

Доступ: Клубный токен Заголовок X-Club-Token: <клубный токен> — токен сервера корта клуба.

Здоровье корта: камеры, версия программы, диск и видеокарта. Сервер корта шлёт его раз в 10 секунд; хранится только последнее состояние. Незнакомый тег камеры не отбрасывается, а возвращается в unknown_tags. В ответе — отметки розыгрышей, сделанные игроками в приложении за последние 30 минут (каждая выдаётся один раз).

Заголовки

ИмяТипОбязательноОписание
x-club-tokenстрокадаКлубный токен сервера корта

Тело запроса application/json

ПолеТипОбязательноОписание
courtстрокадаИмя корта
tsчислонетВремя замера, unix-секунды; 0 — время облака
по умолчанию 0.0
camerasмассив [объект]нетКамеры, до 32
элементов до 32
cameras[].tagстрокадаРоль камеры — тег из согласованного списка (выдаётся при подключении)
cameras[].modelстроканетМодель камеры
cameras[].onlineлогическоенетКамера на связи
по умолчанию false
cameras[].fpsчислонетКадров в секунду
по умолчанию 0.0
cameras[].failsцелоенетСбоев чтения (накопительно)
по умолчанию 0
cameras[].reopensцелоенетПереподключений (накопительно)
по умолчанию 0
cameras[].last_frame_age_sчислонетВозраст последнего кадра, с
по умолчанию 0.0
cameras[].brightчислонетЯркость кадра
по умолчанию 0.0
cameras[].temp_cчисло, или nullнетТемпература камеры, °C, если известна
cameras[].droppedцелоенетПотерянных кадров (накопительно)
по умолчанию 0
cameras[].drop_ratioчислонетДоля потерянных кадров
по умолчанию 0.0
appобъектнетПрограмма сервера корта
app.versionстроканетВерсия программы
app.uptime_sцелоенетВремя работы, с
по умолчанию 0
hostобъектнетЖелезо сервера корта
host.disk_free_gbчисло, или nullнетСвободно на диске, ГБ
host.disk_used_pctчисло, или nullнетЗанято диска, %
host.gpu_temp_cчисло, или nullнетТемпература видеокарты, °C
host.gpu_nameстроканетВидеокарта

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

curl -X POST "https://адрес-вашего-сервера/api/v1/cv/health" \
  -H "X-Club-Token: <клубный токен>" \
  -H "Content-Type: application/json" \
  -d '{
  "court": "court4",
  "ts": 1759418400.0,
  "cameras": [{"tag": "обзор-хайлайты", "online": true, "fps": 25.0}],
  "app": {"version": "1.2137", "uptime_s": 86400},
  "host": {"disk_free_gb": 412.5, "gpu_temp_c": 61.0}
}'

Ответы

КодdetailЗначение
200—Успешный ответ; пример ниже
401bad_club_tokenНеверный клубный токен
422[…]Ошибка проверки параметров или тела: detail — список ошибок

Пример ответа

{
  "ok": true,
  "cameras": 4,
  "unknown_tags": [],
  "marks": [{"id": "0d4e8f21-6a3b-4c7d-9e1f-2a5b8c0d3e47", "ts": 1759418400.5, "source": "app"}]
}

Данные компьютерного зрения по матчу #

GET/v1/cv/match/{match_id}

Доступ: Клубный токен или токен игрока Либо X-Club-Token: <клубный токен>, либо Authorization: Bearer <токен игрока>. Если передан клубный токен, проверяется он.

Розыгрыши матча с траекториями и ударами и итог (тепловая карта, маршруты), если матч закрыт. С клубным токеном доступны только матчи своего клуба.

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

ИмяТипОбязательноОписание
match_idстрока (uuid)даИдентификатор матча

Заголовки

ИмяТипОбязательноОписание
x-club-tokenстроканетКлубный токен сервера корта

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

curl -X GET "https://адрес-вашего-сервера/api/v1/cv/match/8c0f4a52-2d1e-4b7a-9f63-1a5e7d9b3c20" \
  -H "X-Club-Token: <клубный токен>"

Ответы

КодdetailЗначение
200—Успешный ответ; пример ниже
401no_tokenНет токена в заголовке Authorization
401invalid_tokenТокен просрочен или подделан — обновите его через /v1/auth/refresh
401bad_club_tokenНеверный клубный токен
404match_not_foundМатч не найден, чужого клуба или вы не участник
422[…]Ошибка проверки параметров или тела: detail — список ошибок

Пример ответа

{
  "matchId": "8c0f4a52-2d1e-4b7a-9f63-1a5e7d9b3c20",
  "clubId": "c1",
  "court": "Корт 4",
  "summary": {
    "rallies": 42,
    "maxKmh": 118.0,
    "avgKmh": 61.5,
    "totalShots": 310,
    "heat": [[320, 240, 7]],
    "trails": [[320, 240, 360, 260, 3]],
    "fw": 1024,
    "fh": 768
  },
  "rallies": [
    {
      "no": 1,
      "tStart": 1759418000.0,
      "tEnd": 1759418012.4,
      "durationS": 12.4,
      "maxKmh": 96.0,
      "avgKmh": 58.2,
      "shotsCount": 7,
      "winnerTeam": "A",
      "path": [[312, 401], [355, 380]],
      "pathFw": 1024,
      "pathFh": 768,
      "shots": [{"t": 1759418001.2, "vKmh": 74.0, "x": 312, "y": 401}]
    }
  ]
}

Последнее состояние корта #

GET/v1/cv/court/{court}/health

Доступ: Клубный токен или токен игрока Либо X-Club-Token: <клубный токен>, либо Authorization: Bearer <токен игрока>. Если передан клубный токен, проверяется он.

Последнее состояние корта и возраст замера в секундах (ageS). С клубным токеном — корт своего клуба; с токеном игрока нужно указать club_id.

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

ИмяТипОбязательноОписание
courtстрокадаИмя корта, как на сервере корта

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

ИмяТипОбязательноОписание
club_idстроканетИдентификатор клуба

Заголовки

ИмяТипОбязательноОписание
x-club-tokenстроканетКлубный токен сервера корта

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

curl -X GET "https://адрес-вашего-сервера/api/v1/cv/court/court4/health?club_id=c1" \
  -H "X-Club-Token: <клубный токен>"

Ответы

КодdetailЗначение
200—Успешный ответ; пример ниже
401no_tokenНет токена в заголовке Authorization
401invalid_tokenТокен просрочен или подделан — обновите его через /v1/auth/refresh
401bad_club_tokenНеверный клубный токен
400club_id_requiredДля токена игрока нужен club_id
404court_health_not_foundОт корта ещё не было данных о здоровье
422[…]Ошибка проверки параметров или тела: detail — список ошибок

Пример ответа

{
  "clubId": "c1",
  "court": "Корт 4",
  "ts": 1759418400.0,
  "ageS": 4.2,
  "cameras": [
    {
      "tag": "обзор-хайлайты",
      "model": "",
      "online": true,
      "fps": 25.0,
      "fails": 0,
      "reopens": 0,
      "last_frame_age_s": 0.1,
      "bright": 0.0,
      "temp_c": null,
      "dropped": 0,
      "drop_ratio": 0.0
    }
  ],
  "app": {"version": "1.2137", "uptime_s": 86400}
}

Брони на корты клуба #

GET/v1/cv/court-bookings

Доступ: Клубный токен Заголовок X-Club-Token: <клубный токен> — токен сервера корта клуба.

Брони на корты клуба: идущая сейчас и ближайшие на три часа вперёд, с составом (без телефонов). Корты передаются повторяющимся параметром court (до 16) с именами, как на сервере корта; без него — все корты клуба. Корт, которого облако не знает, возвращается с known=false. Отменённые брони не возвращаются.

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

ИмяТипОбязательноОписание
courtмассив [строка]нетИмя корта, как на сервере корта
элементов до 16

Заголовки

ИмяТипОбязательноОписание
x-club-tokenстрокадаКлубный токен сервера корта

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

curl -X GET "https://адрес-вашего-сервера/api/v1/cv/court-bookings?court=court4" \
  -H "X-Club-Token: <клубный токен>"

Ответы

КодdetailЗначение
200—Успешный ответ; пример ниже
401bad_club_tokenНеверный клубный токен
422[…]Ошибка проверки параметров или тела: detail — список ошибок

Пример ответа

{
  "clubId": "c1",
  "now": "2026-10-02 18:05",
  "courts": {
    "court4": {
      "known": true,
      "current": {
        "id": "b71c2e94-0a3f-4d58-8e26-9f1d3c5a7b40",
        "court": "Корт 4",
        "day": "2026-10-02",
        "start": "18:00",
        "end": "19:30",
        "durationMin": 90,
        "current": true,
        "players": [
          {
            "user_id": "3d6e9a10-5b2c-4f8e-a1d7-6c4b2e0f9a83",
            "name": "Иван Петров",
            "short": "Иван П.",
            "booker": true
          }
        ]
      },
      "upcoming": []
    }
  }
}