Getting Started

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

RenderCache синхронизирует кэши симуляций и текстуры между площадками студии через региональные кэш-узлы. Управлять передачами можно из консоли, из CLI-агента rcd или через REST API — например, из post-render-скрипта Houdini или из события рендер-менеджера.

1. 01

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

2. 02

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

3. 03

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

4. 04

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

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

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

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

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

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

rcd login --workspace northlight
rcd agent register --name ws-fx-07 --role source --region msk
Start-Service rcd

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

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

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

import os, requests

resp = requests.post(
    "https://api.rendercache.ru/api/v1/sync",
    headers={
        "Authorization": f"Bearer {os.environ['RC_TOKEN']}",
        "Idempotency-Key": "4f1c2a9e-sh0420-v14",
    },
    json={
        "project": "NH_0420",
        "source": "/mnt/cache/fx/fluid_sim_v04/fluid_sim_v04.$F4.vdb",
        "frames": {"start": 1001, "end": 1240},
        "targets": ["farm-spb-*", "farm-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.rendercache.ru
Authorization: Bearer rcs_9wQ…redacted
Content-Type: application/json
Idempotency-Key: 4f1c2a9e-sh0420-v14

{
  "project": "NH_0420",
  "source": "/mnt/cache/fx/fluid_sim_v04/fluid_sim_v04.$F4.vdb",
  "frames": { "start": 1001, "end": 1240 },
  "targets": ["farm-spb-*", "farm-msk-01"],
  "priority": "high",
  "verify": "blake3"
}

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

Authentication

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

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

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

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

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

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

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

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

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

Chunked Uploads

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

Большие файлы загружаются частями по 8 МиБ (последний чанк может быть меньше). Каждый чанк шифруется AES-256-GCM на стороне клиента и сопровождается хешем BLAKE3 исходных данных. Агент rcd делает это автоматически; 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.rendercache.ru/api/v1/uploads \
  -H "Authorization: Bearer $RC_TOKEN" \
  -d '{
    "project": "NH_0420",
    "path": "fx/fluid_sim_v04/fluid_sim_v04.1042.vdb",
    "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.rendercache.ru/api/v1/uploads/us_8Hq2fK3x/chunks/1873 \
  -H "Authorization: Bearer $RC_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  -H "X-RC-Chunk-Hash: blake3:5d2a…09fe" \
  --data-binary @chunk_1873.enc

Докачка

Сессия живёт 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": ["farm-spb-01", "farm-spb-02", "farm-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 'farm-ams-*'." }
  }
}

Коды ошибок

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

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

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

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