API доступен по HTTPS

Документация Media Helper API

API для уникализации фото, видео и ZIP-архивов с медиа: загрузка файла или архива, выбор шаблона, создание копий, получение ZIP-архива с результатом и проверка баланса.

Пример запроса Смотреть методы

Base URL

https://api.unik.rest

✓Авторизация через Authorization: Bearer
✓Результат обработки возвращается ZIP-архивом
✓Шаблон выбирается по названию из бота или по стандартному коду

Быстрый старт

Базовый сценарий: отправка файла или ZIP-архива и получение ZIP-архива с результатом.

1. Получите API-ключ

API-ключ создаётся в Telegram-боте и передаётся в заголовке Authorization.

2. Укажите шаблон

Поле template_name — это название шаблона из бота. Также доступны стандартные коды: normal, creative, document_photo, scan.

curl -X POST "https://api.unik.rest/api/v1/unique/process" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@media.zip" \
  -F "copies=10" \
  -F "template_name=normal" \
  -F "wait_timeout=600" \
  --output api_result.zip

Стандартные шаблоны

Стандартные шаблоны доступны без дополнительной настройки. В поле template_name можно передавать код шаблона или название шаблона из бота.

Код API	Название в боте	Описание
normal	Обычные фото/видео	Стандартный шаблон для фото и видео.
creative	Креативы	Шаблон для рекламных креативов.
document_photo	Фото документов	Шаблон для фотографий документов.
scan	Сканы	Шаблон для сканов документов.

Авторизация

Все пользовательские методы требуют API-ключ в формате Bearer Token.

Authorization: Bearer YOUR_API_KEY

API-ключ должен передаваться только в заголовке Authorization.

Форматы и лимиты

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

Фото

jpg, jpeg, png, webp, heic, heif

Видео

mp4, mov, mkv, webm, avi

Архивы

zip с фото/видео. Максимум 10 медиафайлов в одном архиве. Неподдерживаемые файлы и файлы сверх лимита игнорируются.

Копии

Поле copies: от 1 до 25 на каждый принятый файл. Результаты API возвращаются ZIP-архивом.

Методы API

Список доступных методов API.

GET/api/v1/health

Публичная проверка доступности API gateway.

curl "https://api.unik.rest/api/v1/health"

GET/api/v1/balance

Возвращает баланс пользователя по API-ключу.

curl "https://api.unik.rest/api/v1/balance" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/v1/unique/formats

Возвращает актуальный список поддерживаемых форматов.

curl "https://api.unik.rest/api/v1/unique/formats" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/v1/unique/process

Создаёт задачу, ожидает завершения обработки и возвращает ZIP-архив.

Для массовой уникализации передайте file=@media.zip. Архив разбирается на поддерживаемые фото/видео, максимум 10 медиафайлов в одном ZIP, остальные файлы игнорируются.

Поле	Тип	Описание
file	file	Фото, видео или ZIP-архив с несколькими фото/видео для массовой уникализации. В ZIP принимается максимум 10 медиафайлов.
copies	integer	Количество копий: 1–25 на каждый принятый файл.
template_name	string	Название шаблона из бота или стандартный код: normal, creative, document_photo, scan.
wait_timeout	integer	Необязательно. Ожидание результата в секундах, по умолчанию 600.

curl -X POST "https://api.unik.rest/api/v1/unique/process" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@media.zip" \
  -F "copies=10" \
  -F "template_name=normal" \
  -F "wait_timeout=600" \
  --output api_result.zip

POST/api/v1/unique/create

Создаёт задачу и возвращает job_id для последующей проверки статуса.

curl -X POST "https://api.unik.rest/api/v1/unique/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@1.jpg" \
  -F "copies=10" \
  -F "template_name=normal"

POST/api/v1/unique/status

Проверяет статус задачи.

curl -X POST "https://api.unik.rest/api/v1/unique/status" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"job_id\":\"JOB_ID\"}"

POST/api/v1/unique/result

Скачивает результат готовой задачи ZIP-архивом.

curl -X POST "https://api.unik.rest/api/v1/unique/result" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"job_id\":\"JOB_ID\"}" \
  --output api_result.zip

Ответы

Если обработка завершилась в пределах wait_timeout, возвращается ZIP-архив. Если обработка не завершилась, возвращается JSON со статусом задачи.

Задача создана

{
  "ok": true,
  "status": "queued",
  "job_id": "b7a9f0e4-2f4c-4b7a-91b8-0f7c3a2d1a21",
  "media_type": "mixed",
  "files": 3,
  "copies_per_file": 10,
  "copies": 30,
  "template_name": "Обычные фото/видео",
  "estimated_cost": 0.3,
  "currency": "USD"
}

Обработка выполняется

{
  "ok": false,
  "status": "running",
  "error": "processing_timeout",
  "message": "The job is still processing. Use this job_id to download the result later.",
  "job_id": "b7a9f0e4-2f4c-4b7a-91b8-0f7c3a2d1a21",
  "result_available": false
}

Ошибки

Ошибки возвращаются в формате JSON. Поле error содержит код ошибки.

Ошибка	Что означает
invalid_api_key	API-ключ отсутствует или неверный.
unsupported_media_format	Формат файла не поддерживается или в ZIP нет подходящих медиафайлов. Если в ZIP больше 10 медиафайлов, лишние игнорируются.
invalid_copies	Количество копий вне допустимого диапазона.
template_not_found	Шаблон с таким названием не найден.
template_has_no_filters	В шаблоне нет фильтров для выбранного типа файла; при ZIP такие файлы игнорируются, а если не осталось валидных файлов — задача не создаётся.
insufficient_balance	На балансе недостаточно средств.
result_not_ready	Результат задачи ещё не готов.