Медиабанк API

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

Базовый адрес: https://media-bank.siteaccess.ru/v1

Ключи и доступ

Банк общий: все пользователи и сервисы видят все файлы на равных. Владелец (owner) и сервис-загрузчик (created_by) — только метаданные, не ограничение доступа.

Ключ передаётся в заголовке Authorization: Bearer mb_… (или x-api-key). Права ключа: read — поиск и скачивание, write — загрузка и изменение метаданных. Ключи выдаёт администратор сервера:

cd /var/www/lovable.siteaccess.ru/platform && node src/cli.ts bank:key "имя сервиса" read,write

Методы

	Путь	Права	Что делает
GET	`/v1/assets`	read	поиск и список: по смыслу (q), похожие (similar), фильтры
POST	`/v1/search/by-image`	read	поиск по картинке (тело — изображение)
GET	`/v1/assets/{id}`	read	карточка файла
GET	`/v1/assets/{id}/{variant}`	read	файл: original, w1600, w800, w400, poster, web — переадресация 302 на подписанную ссылку S3 (1 час)
POST	`/v1/assets?filename=…`	write	загрузить файл (тело — байты файла), метаданные в заголовке x-bank-meta
PATCH	`/v1/assets/{id}`	write	изменить метаданные
POST	`/v1/assets/{id}/usage`	write	отметить использование файла (проект, место)
POST	`/v1/sources/files`	write	файл, уже лежащий на сервере (например, выход ComfyUI): занести в банк сразу и добавить метаданные
GET	`/v1/sources/file?source=&name=`	read	оригинал по имени файла в сервисе-источнике (после очистки локальных копий)
GET	`/v1/stats`	read	сколько файлов по типам и источникам, популярные категории
GET	`/v1/health`	—	проверка доступности

Загрузка

Тело запроса — сами байты файла (Content-Type: image/*, video/*, audio/* или application/octet-stream), до 500 МБ. Имя с расширением — в ?filename=. Метаданные — JSON в заголовке x-bank-meta (для длинных промптов и нелатинских символов — base64 от JSON, или добавьте их потом через PATCH).

curl -X POST "https://media-bank.siteaccess.ru/v1/assets?filename=coffee.png" \
  -H "Authorization: Bearer $BANK_KEY" \
  -H "Content-Type: image/png" \
  -H "x-bank-meta: $(printf '%s' '{"prompt":"кофейня на рассвете","model":"z-image-turbo","owner":"user@example.com","tags":["кофе","интерьер"]}' | base64 -w0)" \
  --data-binary @coffee.png

Ответ 201 — новый файл, 200 с "duplicate": true — такой файл (по sha256) уже есть: метаданные будут добавлены к существующему. Описание и теги банк дополняет сам в течение нескольких минут (status: new → ready).

Файл уже на сервере

curl -X POST "https://media-bank.siteaccess.ru/v1/sources/files" -H "Authorization: Bearer $BANK_KEY" -H "Content-Type: application/json" \
  -d '{"source":"comfyui","name":"api/1a2b3c/abc_00001_.png","meta":{"prompt":"…","model":"z-image-turbo","owner":"user@example.com","source_ref":"api:gen_123"}}'

Поиск

curl "https://media-bank.siteaccess.ru/v1/assets?q=кофе на рассвете&kind=image&orientation=landscape&limit=20" -H "Authorization: Bearer $BANK_KEY"

Параметр	Значение
`q`	запрос словами на любом языке — поиск по смыслу (векторы bge-m3) и по словам
`similar`	id файла — похожие (по картинке и по смыслу)
`kind`	image, video, audio, voice
`category`, `tags`	категория (начало строки, например «Еда и напитки»), теги через запятую — все должны быть
`orientation`, `ratio`	landscape / portrait / square; 16:9, 4:3, 1:1, 9:16 …
`people`	true / false — есть ли люди
`source`, `status`	источник (comfyui, studio, music, lovable, ваш сервис); new / ready / failed
`limit`, `offset`	до 200, по умолчанию 40

Без q и similar — новые сверху. Поиск по картинке: POST /v1/search/by-image с изображением в теле.

Файлы

urls в ответе — постоянные ссылки API. По ним (с ключом) отдаётся переадресация на подписанную ссылку S3 на 1 час: перемотка видео и докачка работают, файл идёт напрямую из хранилища.

original — исходный файл
w1600, w800, w400 — WebP для сайтов (для видео — из кадра-обложки)
poster, web — обложка и версия для веба (видео, аудио)

Метаданные

Поле	Тип
`title`, `description`, `category`	строка	если не заданы — заполнит банк
`tags`	массив строк	при загрузке объединяются, в PATCH — заменяются
`prompt`, `model`, `params`	строка, строка, объект	для сгенерированных файлов
`owner`	строка	кто создал (email или id) — для истории, доступ не ограничивает
`source`, `source_ref`	строка	сервис и id в нём (по умолчанию source — имя ключа)

Объект файла

{
  "id": "b3f9c2a1d4e5", "kind": "image", "source": "comfyui", "source_ref": "api:gen_123",
  "owner": "user@example.com", "created_by": "api.siteaccess.ru", "status": "ready",
  "title": "Кофейня на рассвете", "description": "…", "tags": ["кофе", "интерьер"], "category": "Еда и напитки / Кофе",
  "prompt": "…", "model": "z-image-turbo", "params": {"seed": 42},
  "width": 1344, "height": 768, "ratio": "16:9", "orientation": "landscape", "mime": "image/png", "bytes": 1543210,
  "urls": {"original": "https://media-bank.siteaccess.ru/v1/assets/b3f9c2a1d4e5/original", "w800": "…"},
  "created_at": "2026-11-13T10:00:00Z"
}

Ошибки

{ "error": { "message": "invalid or missing API key", "type": "authentication_error" } }

400 неверный запрос · 401 нет ключа · 403 у ключа нет прав · 404 не найдено · 413 файл больше 500 МБ · 500 внутренняя ошибка.