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

Базовый адрес — https://wl.hikuri.top/api/v1. Формат обмена — JSON, кодировка UTF-8.

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

Ключ проекта передаётся заголовком. Ключей у проекта может быть несколько, каждый отзывается отдельно.

Authorization: Bearer clp_live_9f4c2b7e1a0d

Без заголовка сервер отвечает 401, с недействительным или отозванным ключом — 403.

Поставить задачу

POST /api/v1/jobs

{
  "source": "https://example.org/raw/clip.mov",
  "profile": "web-hd",
  "options": {
    "thumbnails": [0, 15, 60],
    "loudness": "ebu-r128"
  },
  "callback": "https://example.org/hooks/clipline"
}

Ответ 202 с идентификатором задачи. Поле source можно опустить, если файл уже загружен — тогда передайте upload с его идентификатором.

Узнать состояние

GET /api/v1/jobs/j_8f2c1ad4

{
  "job": "j_8f2c1ad4",
  "state": "encoding",
  "progress": 62,
  "duration": 738.4,
  "created_at": "2026-02-11T09:14:03Z"
}

Состояние	Что означает
`queued`	задача принята, ждёт свободного кодировщика
`fetching`	забираем исходник по указанной ссылке
`encoding`	идёт кодирование, поле `progress` заполнено
`ready`	файл готов и доступен для скачивания
`failed`	обработка прервана, причина в поле `error`

Забрать результат

GET /video/download?job=j_8f2c1ad4

Отдаётся сам файл. Поддерживаются заголовки Range и If-Range, поэтому докачка и перемотка работают штатно. Если задача ещё не завершена, ответ 409; если срок хранения истёк — 410.

Для подписанных ссылок к адресу добавляются параметры expires и sig. Подпись считается по строке из идентификатора задачи и срока годности на секретном ключе проекта.

Удалить

DELETE /api/v1/jobs/j_8f2c1ad4

→ 204 No Content

Удаляет результат и метаданные. Хранение с этого момента не тарифицируется.

Ошибки

Код	Когда	Что делать
400	неверные параметры задачи	исправить тело запроса
401	нет заголовка авторизации	добавить ключ
403	ключ отозван или подпись неверна	выпустить новый ключ
409	файл ещё не готов	повторить позже
410	срок хранения истёк	поставить задачу заново
429	слишком часто	смотреть `Retry-After`
503	плановые работы	повторить через минуту

Ограничения частоты

60 запросов в минуту на ключ для методов чтения и 20 в минуту для постановки задач. Скачивание готовых файлов не ограничивается.