Договор API

Публичная отдача — без API вовсе

Файл ищется на диске веб-сервером. Не нашли — 404, а не «сгенерируй на лету».

GET https://img.example.com/i/<путь варианта>
GET https://v.keepix.cloud/v/<путь>/master.m3u8

Заголовки отдачи одинаковы для всех арендаторов и не меняются:

cache-control: public, max-age=31536000, immutable
x-content-type-options: nosniff
content-security-policy: default-src 'none'; sandbox
cross-origin-resource-policy: cross-origin
access-control-allow-origin: *

Ни одной Set-Cookie: на хосте отдачи нет ни сессий, ни JavaScript.

Подпись

Каждый запрос приватного API подписывается. Четыре заголовка:

X-Media-Tenant: <код арендатора>
X-Media-Key-Id: <идентификатор ключа>
X-Media-Ts:     <время unix, секунды>
X-Media-Sign:   hex(HMAC-SHA256(secret, METHOD "\n" PATH "\n" TS "\n" sha256(тело)))

PATH — путь вместе со строкой запроса (/api/v1/put?kind=prodimg&key=42). Иначе параметры остались бы неподписанными и подмену kind или key никто бы не заметил. Тело пустого запроса хешируется как пустая строка (e3b0c442…), а не как литерал "".

Окно — 300 секунд. Секрет — ASCII-строка из 64 шестнадцатеричных знаков; ею и подписывают, декодировать ничего не надо.

Минимальный подписывающий клиент

#!/bin/bash
METHOD=$1; PATHQ=$2; BODY=$3
TS=$(date +%s)
BH=$( [ -f "$BODY" ] && sha256sum "$BODY" | cut -d' ' -f1 \
                     || printf '' | sha256sum | cut -d' ' -f1 )
SIG=$(printf '%s\n%s\n%s\n%s' "$METHOD" "$PATHQ" "$TS" "$BH" \
      | openssl dgst -sha256 -hmac "$KP_SECRET" -hex | sed 's/.*= //')
curl -H "X-Media-Tenant: $KP_TENANT" -H "X-Media-Key-Id: $KP_KEYID" \
     -H "X-Media-Ts: $TS"           -H "X-Media-Sign: $SIG" \
     --data-binary @"$BODY" -X "$METHOD" "https://keepix.cloud$PATHQ"

Точки

Сверка: убедиться, что долетело всё

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

Как это делается

1. Нарезаете свой список на пачки по 1000 и на каждую шлёте POST /api/v1/reconcile со своими размерами и хешами.
2. Смотрите на summary: если ok равно числу записей — пачка сошлась, читать остальное незачем.
3. Не сошлось — в items лежит, что именно и почему. С "only":"problems" сошедшиеся не возвращаются вовсе: ответ на удачную пачку в тысячу записей — около 270 байт.

Что значит каждый ответ

status	что произошло
ok	Есть, и размер с хешем сходятся. Если вы не прислали ни размера, ни хеша, ok значит только «есть».
missing	Такого ключа (или такого варианта у него) у сервиса нет. Это и есть то, что надо дослать.
mismatch	Есть, но не то: в why написано, размер разошёлся или хеш.
pending	Объект принят, вариант ещё делается — видео в очереди. Дослать нечего, надо подождать.
unverified	Есть, но сверить с вашим хешем нечем. Такое бывает у файлов, принятых до 4 сентября 2026 года.

Отпечаток пачки

В ответе есть digest — sha256 по строкам kind|key|variant|bytes|sha256, отсортированным как строки и склеенным через \n. Посчитайте его у себя тем же способом: если совпал, пачка сошлась целиком, и разбирать тысячу ответов не нужно. Порядок записей в запросе на отпечаток не влияет.

Сверка не считается операцией и не тратит пакет. Проверять, что ваши файлы на месте, можно не оглядываясь на счёт.

С чем именно сравнивается

Сервис снимает EXIF и GPS со всего, что принимает. Значит файл, лежащий у нас, байт в байт не равен присланному, если в нём были метаданные. Сравнение поэтому идёт с тем, что вы прислали: размер и хеш запоминаются до чистки. В ответе bytes и sha256 — присланное, stored_bytes — то, что лежит на диске.

Оговорка для старых файлов: для принятых до 4 сентября 2026 года, 02:54, хеш присланного не записывался и вычислен из хранимой копии задним числом. Если такой файл нёс метаданные, наш хеш — хеш очищенной копии, и сверка покажет mismatch законно. Проверяется просто: пришлите файл заново, приём идемпотентен.

Отказы

Отказ приходит с причиной словами и машинным кодом. Причина не пересказывает исключение библиотеки: машинную строку читает оператор в журнале, а не вы в ответе.

{ "ok": false, "error": { "code": "sign_stale",
    "message": "The signature is older than 300 s (clocks differ by 4000 s). Check the clock on your machine." } }

Отказ всегда объясняет причину словами и никогда не пересказывает исключение библиотеки: машинную строку читает наш оператор в журнале, а не вы в ответе.

Админ-API

Отдельная точка входа /api/admin/v1/* со своим конфигом, своим журналом и своей подписью. Ею пользуется только общая панель управления. Ключи подписи арендаторов в панель не отдаются: это право писать в чужое хранилище.