Getting Started

Начало работы

Mesh-Sync синхронизирует 3D-геометрию — меши, облака точек, октодеревья и LOD — между площадками студии через региональные edge-узлы. Управлять передачами можно из консоли, из CLI-агента msync или через REST API — например, из post-build-скрипта Houdini или из события сборки Unreal.

1. 01

   Получите приглашение в рабочее пространство

2. 02

   Установите агент msync на узлы

3. 03

   Выпустите токен сервиса

4. 04

   Вызовите POST /api/v1/sync

Установка агента

Агент msync ставится на каждую машину, которая отдаёт или принимает геометрию: рабочие станции пайплайна, файловые серверы и ноды площадок. Поддерживаются Linux x86_64 (glibc 2.28+) и Windows Server 2019+.

# Пакет из репозитория Mesh-Sync (RHEL / Rocky 8+)
sudo dnf install -y https://get.mesh-sync.ru/msync/msync-2.4.1.x86_64.rpm

# Привязать узел к рабочему пространству и назначить роль
msync login --workspace northlight
msync agent register --name node-spb-02 --role site --region spb
sudo systemctl enable --now msync

# PowerShell от имени администратора
msiexec /i https://get.mesh-sync.ru/msync/msync-2.4.1-x64.msi /qn

msync login --workspace northlight
msync agent register --name ws-geo-07 --role source --region msk
Start-Service msync

Первая синхронизация

Задание синхронизации описывает, что передать (путь к геометрии или последовательности кадров), куда (агенты или группы агентов) и как (приоритет, проверка). API принимает задание асинхронно и сразу возвращает его идентификатор; прогресс можно опрашивать или получать вебхуком.

curl -X POST https://api.mesh-sync.ru/api/v1/sync \
  -H "Authorization: Bearer $MS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f1c2a9e-sh0420-v14" \
  -d '{
    "project": "NH_0420",
    "source": "/mnt/geo/scene/city_block_v04/city_block_v04.$F4.glb",
    "frames": { "start": 1001, "end": 1240 },
    "targets": ["node-spb-*", "node-msk-01"],
    "priority": "high",
    "verify": "blake3",
    "notify": "https://pipeline.studio.ru/hooks/mesh-sync"
  }'

import os, requests

resp = requests.post(
    "https://api.mesh-sync.ru/api/v1/sync",
    headers={
        "Authorization": f"Bearer {os.environ['MS_TOKEN']}",
        "Idempotency-Key": "4f1c2a9e-sh0420-v14",
    },
    json={
        "project": "NH_0420",
        "source": "/mnt/geo/scene/city_block_v04/city_block_v04.$F4.glb",
        "frames": {"start": 1001, "end": 1240},
        "targets": ["node-spb-*", "node-msk-01"],
        "priority": "high",
        "verify": "blake3",
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json()["sync_id"])  # sync_01JBX7Q4M2

POST /api/v1/sync HTTP/1.1
Host: api.mesh-sync.ru
Authorization: Bearer mss_9wQ…redacted
Content-Type: application/json
Idempotency-Key: 4f1c2a9e-sh0420-v14

{
  "project": "NH_0420",
  "source": "/mnt/geo/scene/city_block_v04/city_block_v04.$F4.glb",
  "frames": { "start": 1001, "end": 1240 },
  "targets": ["node-spb-*", "node-msk-01"],
  "priority": "high",
  "verify": "blake3"
}

Ответ 202 Accepted означает, что задание поставлено в очередь. Полное описание полей и ответов — в разделе справочника.

Authentication

Аутентификация

API принимает два вида учётных данных: токены сервиса для скриптов и интеграций и сертификаты агентов (mTLS) для msync. Пароли пользователей консоли для API не используются.

Токены сервиса

Токен выпускает администратор рабочего пространства в разделе Settings → Service tokens или через API. Токен передаётся в заголовке Authorization: Bearer <token>, начинается с префикса mss_ и показывается один раз при создании.

curl -X POST https://api.mesh-sync.ru/api/v1/auth/tokens \
  -H "Authorization: Bearer $MS_ADMIN_TOKEN" \
  -d '{ "name": "houdini-post-build", "scopes": ["sync:write"], "ttl_days": 90 }'

{
  "id": "tok_01JBX2K8ZV",
  "name": "houdini-post-build",
  "token": "mss_9wQ…shown-once",
  "scopes": ["sync:write"],
  "expires_at": "2027-01-21T10:42:07Z"
}

Подпись запросов

Для операций с ключами и для вебхуков Mesh-Sync использует подпись HMAC-SHA256. Подписывается строка timestamp + "." + body; запросы с отметкой времени старше 300 секунд отклоняются.

• X-MS-Timestamp — время в секундах Unix;
• X-MS-Signature — v1= и hex-подпись;
• сравнивайте подписи функцией постоянного времени (hmac.compare_digest).

Chunked Uploads

Загрузка по чанкам

Большие файлы геометрии загружаются частями по 8 МиБ (последний чанк может быть меньше). Каждый чанк шифруется AES-256-GCM на стороне клиента и сопровождается хешем BLAKE3 исходных данных. Агент msync делает это автоматически; API нужен, если вы пишете собственный загрузчик.

Сессия загрузки

1. POST/api/v1/uploads — открыть сессию: имя файла, размер, хеш манифеста. В ответе — upload_id и chunk_size.
2. PUT/api/v1/uploads/{upload_id}/chunks/{index} — отправить чанк. Чанки можно слать параллельно и в любом порядке.
3. POST/api/v1/uploads/{upload_id}/complete — закрыть сессию; сервер сверяет манифест и публикует версию.

curl -X POST https://api.mesh-sync.ru/api/v1/uploads \
  -H "Authorization: Bearer $MS_TOKEN" \
  -d '{
    "project": "NH_0420",
    "path": "scene/city_block_v04/city_block_v04.1042.glb",
    "size": 17083400192,
    "manifest_hash": "blake3:8e0f…c41a"
  }'

{
  "upload_id": "us_8Hq2fK3x",
  "chunk_size": 8388608,
  "chunks_total": 2037,
  "expires_at": "2026-10-30T10:42:07Z"
}

curl -X PUT https://api.mesh-sync.ru/api/v1/uploads/us_8Hq2fK3x/chunks/1873 \
  -H "Authorization: Bearer $MS_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  -H "X-MS-Chunk-Hash: blake3:5d2a…09fe" \
  --data-binary @chunk_1873.enc

Раздача геометрии edge-узлами

Опубликованная геометрия раздаётся ближайшим edge-узлом по контентно-адресуемым путям. Чанки меша и последовательностей запрашиваются по /v2/geometry/<hash>/chunk.bin, а узлы октодерева и LOD-бандлы — по /bundles/octree/<node_id>/node.pak. Оба пути отдают ETag и Cache-Control: immutable и поддерживают Range для докачки.

curl -L -C - -o chunk_1873.bin \
  -H "Authorization: Bearer $MS_TOKEN" \
  "https://cdn.mesh-sync.ru/v2/geometry/5d2a09fe…c41a/chunk.bin"

# узел октодерева (LOD-бандл)
curl -L -o node.pak \
  -H "Authorization: Bearer $MS_TOKEN" \
  "https://cdn.mesh-sync.ru/bundles/octree/0a3f…17b/node.pak"

Докачка

Сессия живёт 7 дней. После обрыва запросите GET /api/v1/uploads/{upload_id}: поле received содержит битовую карту принятых чанков в Base64. Отправьте только недостающие — повторная отправка уже принятого чанка с тем же хешем безопасна и возвращает 200.

{
  "upload_id": "us_8Hq2fK3x",
  "state": "interrupted",
  "chunks_total": 2037,
  "chunks_received": 1873,
  "received": "//////////////////8AAA…",
  "resume_from": 1873
}

API Reference

POST/api/v1/sync

Создаёт задание синхронизации геометрии или последовательности на один или несколько агентов. Операция идемпотентна при передаче заголовка Idempotency-Key (ключ хранится 24 часа).

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

Ответы

{
  "sync_id": "sync_01JBX7Q4M2",
  "status": "queued",
  "project": "NH_0420",
  "manifest": { "version": 14, "files": 240, "bytes": 17083400192, "chunks": 2048 },
  "delta": { "chunks_to_send": 164, "bytes_to_send": 1375731712 },
  "targets": ["node-spb-01", "node-spb-02", "node-msk-01"],
  "links": { "self": "/api/v1/sync/sync_01JBX7Q4M2" }
}

{
  "error": { "code": "token_invalid", "message": "Token is missing, expired or revoked." }
}

{
  "error": {
    "code": "sync_in_progress",
    "message": "An identical sync for these targets is already running.",
    "sync_id": "sync_01JBX6ZP0D"
  }
}

{
  "error": {
    "code": "validation_failed",
    "fields": { "targets": "No agent matches 'node-ams-*'." }
  }
}

Коды ошибок

Ошибки возвращаются с HTTP-статусом и объектом error с машиночитаемым code.

Лимиты запросов

Управляющие эндпоинты ограничены 600 запросами в минуту на рабочее пространство; загрузка и раздача чанков ограничены только пропускной способностью тарифа. Текущее состояние лимита передаётся в заголовках X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset.

Обновлено 20 октября 2026 · API v1.4 · Статус API