API invisia media

REST API для загрузки, обработки и доставки изображений и видео. Все запросы идут на https://media.invisia.biz по HTTPS (HTTP/2), ответы — JSON в кодировке UTF-8.

Текущая версия — v1. Мы не ломаем совместимость внутри версии: новые поля в ответах могут появляться, существующие не меняются.

Авторизация

Каждый запрос к /api/v1/ подписывается ключом проекта в заголовке Authorization. Ключ создаётся в кабинете, раздел «Проект → Ключи API».

curl https://media.invisia.biz/api/v1/files \
  -H "Authorization: Bearer im_live_••••••••••••••••"

Без ключа или с неверным ключом API отвечает 401:

{ "error": "unauthorized", "message": "Missing or invalid API key" }

Ошибки и лимиты

Код	error	Когда
`400`	`bad_request`	Неверные параметры запроса
`401`	`unauthorized`	Нет ключа или ключ отозван
`404`	`not_found`	Файл или загрузка не найдены
`413`	`too_large`	Часть больше 2 МБ или файл больше лимита тарифа
`429`	`rate_limited`	Больше 600 запросов в минуту на ключ

Загрузка файла

POST/api/v1/files

Простая загрузка одним запросом multipart/form-data — для файлов до 25 МБ.

Поле	Тип	Описание
`file`	file	Сам файл
`folder`	string	Папка внутри проекта, необязательно
`private`	bool	Отдавать только по подписанной ссылке

Загрузка по частям

Для больших файлов и нестабильной мобильной сети. Клиент открывает загрузку, отправляет части по порядку и читает поток событий обработки. Оборванную часть можно отправить повторно — сервер собирает файл по номерам частей.

POST/api/v1/uploads

{ "upload_id": "5814402907716253", "part_size": 1048576, "expires_in": 600 }

POST/api/v1/uploads/{upload_id}?part={n}

Тело — бинарные данные части (application/octet-stream, не больше 2 МБ). Номера частей начинаются с 0.

GET/api/v1/uploads/{upload_id}

Долгоживущий ответ с ходом обработки: сервер держит соединение открытым до 10 минут и присылает события по мере готовности превью и видео-вариантов.

Список и удаление

GET/api/v1/files?folder=catalog&limit=100

DELETE/api/v1/files/{id}

Трансформации изображений

Параметры добавляются к адресу файла /i/{project}/{path}. Каждая комбинация кэшируется отдельно.

Параметр	Значения	Описание
`w`, `h`	1–8192	Ширина и высота в пикселях
`fit`	cover, contain, fill, inside	Как вписать в заданный размер
`fmt`	auto, avif, webp, jpeg, png	`auto` выбирает лучший формат по заголовку Accept
`q`	1–100	Качество сжатия, по умолчанию 80
`blur`	0–100	Размытие, удобно для заглушек

https://media.invisia.biz/i/demo/mountains.svg?w=1200&fmt=auto&q=75

Видео

Загруженные MP4 и MOV перекодируются в HLS. Плейлист доступен по адресу /v/{project}/{id}/master.m3u8, постер — /v/{project}/{id}/poster.jpg.

Подписанные ссылки

Для приватных файлов добавьте exp (unix-время) и sig — HMAC-SHA256 от пути и параметров на секретном ключе проекта. Просроченная ссылка возвращает 403.

Кэш

DELETE/api/v1/cache?url={url}

Удаляет файл и все его варианты из кэша на всех узлах. Обычно занимает до 30 секунд.