REST API v1

Публичная документация API

Автоматическая загрузка книг, томов, глав и изображений. API отвечает JSON в UTF-8, использует Bearer-токены и проверяет права владельца на каждом запросе.

Авторизация

Токен не расширяет права аккаунта

Передавайте ключ только в заголовке Authorization: Bearer rhb_…. Обычный токен переводчика ограничен выбранными scope и назначенными книгами. content:manage является административным super-scope: он открывает Content Manager и все методы Translator API для всех книг без назначения команды; редактору этот scope недоступен.

curl --fail-with-body \
  -H "Authorization: Bearer $RANOBEHUB_TOKEN" \
  -H "Accept: application/json" \
  https://ranobehub.org/api/v1/translator/books

Создать, показать, скопировать, перевыпустить или отозвать ключ можно в разделе API панели управления.

Переводчикам

Книги, тома, главы и публикация

Существующие методы сохранены; новые возможности добавляются без переименования старых URL и полей.

GET/api/v1/translator/booksbooks:read
Доступные книги

Книги, к которым у владельца токена есть редакционный доступ.

GET/api/v1/translator/books/:idbooks:read
Книга

Основные метаданные выбранной книги.

PATCH/api/v1/translator/books/:idbooks:write
Метаданные книги

Совместимый существующий метод частичного обновления.

GET/api/v1/translator/books/:id/volumesvolumes:read
Оглавление по томам

Список томов с номером, названием и статусом.

POST/api/v1/translator/books/:id/volumesvolumes:write
Создать том

Создаёт том; повтор номера возвращает 409.

PATCH/api/v1/translator/books/:id/volumes/:volumeIdvolumes:write
Изменить или переставить том

При смене номера moveChapters=true переносит главы вместе с томом.

DELETE/api/v1/translator/books/:id/volumes/:volumeIdvolumes:delete
Удалить том

Удаляется только пустой том; иначе возвращается 409.

GET/api/v1/translator/books/:id/chapterschapters:read
Оглавление

Главы по порядку со счётчиками и назначенными конкретной главе переводчиками.

POST/api/v1/translator/books/:id/chapterschapters:create
Создать главу

Санитайзит HTML, вычисляет метаданные и опционально принимает translatorIds.

GET/api/v1/translator/chapters/:idchapters:read
Получить главу

Полный HTML, метаданные, translatorIds и сведения о переводчиках главы.

PATCH/api/v1/translator/chapters/:idchapters:update
Обновить или переставить главу

Можно менять содержимое и опционально заменять translatorIds; предыдущая версия сохраняется.

DELETE/api/v1/translator/chapters/:idchapters:delete
Удалить главу

Удаляет главу и связанные редакционные черновики, ревизии и комментарии.

POST/api/v1/translator/books/:id/imageschapters:images
Загрузить изображение

multipart/form-data, поле image; JPEG, PNG, WebP или GIF до 12 МБ.

DELETE/api/v1/translator/books/:id/images?mediaId=:mediaIdchapters:images
Удалить изображение

Удаляет только изображение главы, принадлежащее указанной книге.

GET/api/v1/translator/chapters/:id/schedulechapters:read
Получить расписание

Возвращает будущую редакцию главы или null.

PUT/api/v1/translator/chapters/:id/schedulechapters:schedule
Отложить публикацию

Создаёт или заменяет будущую редакцию на срок до 366 дней.

DELETE/api/v1/translator/chapters/:id/schedulechapters:schedule
Отменить публикацию

Удаляет запланированную редакцию, не меняя текущую главу.

GET/POST/api/v1/translator/books/:id/translation-brancheschapters:read / chapters:update
Ветки перевода

Получение и создание независимых веток перевода.

POST/api/v1/translator/books/:id/ai-chapterschapters:create
AI-перевод

Запускает поддерживаемый сервером процесс AI-перевода главы.

Глава

Создание и пересчёт

POST /api/v1/translator/books/125/chapters
{
  "volume": 1,
  "number": 12,
  "title": "Глава 12",
  "html": "<p>Текст…</p><img src="/api/media/9001" alt="Карта">",
  "draft": false,
  "sourceId": "import:12",
  "translatorIds": [12, 18]
}

HTML очищается на сервере. Количество Unicode-символов и hasImages пересчитываются при создании, обновлении, восстановлении и отложенной публикации.

translatorIds необязателен. В PATCH отсутствие поля сохраняет прежнее авторство, массив заменяет его, а [] очищает явное авторство главы. Все ID должны заранее быть назначены книге через её taxonomy. Ответы GET содержат translatorIds и translators.

Изображения

Сначала файл, затем HTML

curl --fail-with-body \
  -H "Authorization: Bearer $RANOBEHUB_TOKEN" \
  -F "image=@map.webp" \
  https://ranobehub.org/api/v1/translator/books/125/images

Ответ содержит mediaId и относительный url. Этот URL вставляется в <img src>. Внешние HTTPS-изображения тоже допустимы, но управлять их жизненным циклом RanobeHub не может.

Content Manager

Административный импорт новой книги

Этот раздел требует токен администратора со scope content:manage. Обычному переводчику он недоступен.

GET/api/v1/content/resources?type=tags|authors|translators|countries|statusescontent:manage
Справочники

Поиск и получение ID для связей новой книги.

POST/api/v1/content/resourcescontent:manage
Создать ресурс

Создание тега, автора, команды переводчиков или страны.

PATCH/api/v1/content/resources/:type/:idcontent:manage
Изменить ресурс

Частичное обновление справочника.

DELETE/api/v1/content/resources/:type/:idcontent:manage
Удалить ресурс

Связанный с книгами ресурс защищён ответом 409.

GET/POST/api/v1/content/bookscontent:manage
Найти или создать книгу

Поиск по названию/slug и создание книги с начальными связями.

GET/api/v1/content/books/:idcontent:manage
Полные данные книги

Административное представление книги.

PATCH/api/v1/content/books/:idcontent:manage
Изменить книгу

Метаданные, состояние публикации, блокировка и тип произведения.

DELETE/api/v1/content/books/:idcontent:manage
Удалить книгу

Безопасное мягкое удаление без уничтожения глав и истории.

GET/PUT/api/v1/content/books/:id/taxonomycontent:manage
Связи книги

Полная замена тегов, авторов, переводчиков и стран; назначенные команды получают редакционные права.

GET/POST/DELETE/api/v1/content/books/:id/posterscontent:manage
Постеры книги

Получение галереи, загрузка multipart-постера и удаление по posterId.

Постеры

Обложки после создания книги

curl --fail-with-body \
  -H "Authorization: Bearer $RANOBEHUB_TOKEN" \
  -F "poster=@cover.webp" \
  https://ranobehub.org/api/v1/content/books/125/posters

curl --fail-with-body -X DELETE \
  -H "Authorization: Bearer $RANOBEHUB_TOKEN" \
  "https://ranobehub.org/api/v1/content/books/125/posters?posterId=9002"

Поддерживаются JPEG, PNG и WebP до 12 МБ, не более 15 постеров на книгу. GET и ответы мутаций возвращают массив posters, активный posterUrl, количество и лимит.

Автоматический импорт

Рекомендуемая последовательность

  1. Получить или создать теги, авторов, переводчиков и страны.
  2. Создать книгу через Content Manager API.
  3. Назначить связи книги через PUT taxonomy и загрузить постеры.
  4. Создать тома через Translator API.
  5. Загрузить изображения глав и использовать возвращённые URL в HTML.
  6. Создать главы как черновики, проверить оглавление и затем опубликовать либо настроить расписание.
POST /api/v1/content/books
{
  "title": "Название книги",
  "descriptionHtml": "<p>Аннотация</p>",
  "year": 2026,
  "statusId": 1,
  "state": "opened",
  "tagIds": [4, 18],
  "authorIds": [93],
  "translatorIds": [12],
  "countryIds": [3]
}
Ответы

Ошибки и повторные запросы

400 — неверные поля, 401 — токен отсутствует или истёк, 403 — недостаточно scope/прав, 404 — объект не найден, 409 — конфликт номера или используемый ресурс, 413/415 — размер или формат изображения. Для автоматического импорта сохраняйте возвращённые ID и sourceId; не повторяйте POST после сетевой ошибки вслепую.