Libris
English

API d’automatisation

Envoyez un livre, recevez-le traduit.

L’API d’automatisation permet à un script ou à un autre serveur de confier des livres à Libris sans passer par l’interface. Tout le pipeline se déroule seul, sous le pilote automatique, et chaque requête se termine par un résultat ou par une raison explicite.

Référence de l’API Lire le guide de l’API sur GitHub Installer

Le principe

  1. Créez un jeton

    Dans Mon compte › Jetons d’API, cochez seulement les portées dont le script a besoin. Le secret ne s’affiche qu’une fois.

  2. Envoyez le livre

    POST /api/v1/translation-requests accepte un EPUB, des chapitres TXT ou DOCX, ou un document JSON. Libris répond aussitôt 202 Accepted.

  3. Suivez-le

    Interrogez l’état avec ?wait= pour que l’appel attende la fin de la requête, ou laissez un webhook signé vous prévenir, jusqu’à chaque lot de chapitres traduits.

  4. Récupérez le résultat

    L’EPUB traduit pour un EPUB, validé par EPUBCheck, un EPUB bilingue, ou du JSON, du texte ou un ZIP de chapitres, avec le rapport de fin.

Un exemple complet

Envoyer un EPUB, attendre la fin, puis télécharger le livre traduit et lire le rapport. Le script attend LIBRIS_URL, LIBRIS_TOKEN et PROVIDER_ID dans l’environnement, et utilise curl et jq. Il est repris tel quel du guide de l’API (en anglais).

bash 
#!/usr/bin/env bash
set -euo pipefail

REQUEST_ID=$(curl -sS -X POST "$LIBRIS_URL/api/v1/translation-requests" \
  -H "Authorization: Bearer $LIBRIS_TOKEN" \
  -H "Idempotency-Key: book-fr-1" \
  -F "file=@book.epub" -F target_language=fr -F provider_id="$PROVIDER_ID" \
  | jq -r .request_id)

while :; do   # each call answers when the request ends, or after 60 seconds
  STATUS=$(curl -sS "$LIBRIS_URL/api/v1/translation-requests/$REQUEST_ID?wait=60" \
    -H "Authorization: Bearer $LIBRIS_TOKEN" | jq -r .status)
  case "$STATUS" in completed|completed_with_residuals|failed|cancelled) break ;; esac
done
echo "Request ended: $STATUS"

if [ "$STATUS" = completed ] || [ "$STATUS" = completed_with_residuals ]; then
  curl -sS "$LIBRIS_URL/api/v1/translation-requests/$REQUEST_ID/result" \
    -H "Authorization: Bearer $LIBRIS_TOKEN" -o book.fr.epub
fi
curl -sS "$LIBRIS_URL/api/v1/translation-requests/$REQUEST_ID" \
  -H "Authorization: Bearer $LIBRIS_TOKEN" | jq '.report | {outcome, residual_total, usage}'

Un client d’exemple, sans rien à installer

examples/libris_client.py est un petit client Python qui n’utilise que la bibliothèque standard. Il envoie un EPUB, des chapitres TXT ou un document JSON, attend la fin par long polling, télécharge le résultat, patiente quand le débit est limité et reçoit les webhooks après avoir vérifié leur signature. Utilisez-le comme commande, ou importez-le dans votre code.

bash 
export LIBRIS_URL=https://libris.example.org LIBRIS_TOKEN=lbr_xxxxxxxx_...
python3 examples/libris_client.py epub livre.epub --target-language fr --provider-id "$PROVIDER_ID" --out livre.fr.epub
LIBRIS_WEBHOOK_SECRET=... python3 examples/libris_client.py webhooks --port 8080
Lire le client d’exemple sur GitHub Référence de l’API

Pensée pour les scripts qui tournent sans surveillance

  • Jetons à portée limitée

    Six portées, de series:read à results:read, expiration optionnelle et révocation immédiate. Les jetons sont stockés sous forme d’empreinte SHA-256 et limités en débit, jeton par jeton.

  • Requêtes idempotentes

    Avec l’en-tête Idempotency-Key, un envoi répété renvoie la première requête au lieu d’en créer une seconde.

  • Une requête finit toujours

    Chaque requête se termine en completed, completed_with_residuals, failed avec sa raison, ou cancelled. Aucune ne reste en cours indéfiniment.

  • Webhooks signés

    Signature HMAC-SHA256, hôtes autorisés uniquement, aucune adresse privée sauf autorisation explicite, et nombre de tentatives borné. Demandez chapters.translated pour être prévenu à chaque lot de chapitres.

  • Un rapport avec chaque résultat

    État des passages, passages conservés en original avec leur raison, coût estimé et coût réel, passages et chapitres à relire en priorité, durées, et les décisions de l’import et du pilote automatique.

  • Séparée de l’interface

    /api/v1 n’accepte que des jetons d’API, et un jeton n’ouvre jamais les routes de l’interface.

  • Une série suivie dans le temps

    Envoyez les nouveaux chapitres au volume qui contient les précédents (volume.latest trouve le dernier) : seuls eux sont traduits. ?scope=new ne télécharge qu’eux, ?scope=volume tout le volume mis à jour.

  • Parties, prologues, interludes

    Les chapitres d’un document JSON prennent un type (kind), une partie (part), un nom (label) et une place (after) ; les envois TXT et DOCX les lisent dans les noms de fichiers, et split=headings découpe un fichier à ses titres de chapitre.

  • Budgets et file équitable

    Un jeton peut avoir un budget de coût par mois ou au total (402 budget_exceeded), un plafond de priorité et ses propres quotas (429 queue_full). L’état indique où la requête attend dans la file, et pourquoi.

Points d’accès

Méthode et cheminPortéeRôle
POST /api/v1/translation-requests content:write (+ pipeline:start) Envoyer un EPUB, des chapitres TXT ou DOCX, ou un document JSON
GET /api/v1/translation-requests/{id} jobs:read État, avancement et rapport (?wait= pour attendre la fin)
POST …/{id}/pause · …/resume · …/cancel jobs:control Mettre en pause, reprendre ou annuler la tâche
GET /api/v1/translation-requests/{id}/result results:read Télécharger le résultat (EPUB, EPUB bilingue, JSON, TXT ou ZIP) : les chapitres de la requête, les nouveaux seulement ou tout le volume (?scope=)
GET /api/v1/providers content:write Lister les fournisseurs qu’une requête peut utiliser
GET /api/v1/series · /api/v1/series/{id} series:read Lister vos séries, ou une série et ses tomes
GET /api/v1/glossaries · …/{id} · …/{id}/export/{format} series:read Lister vos glossaires partagés, en lire un, ou le télécharger en JSON, CSV ou TBX
POST /api/v1/glossaries · …/{id}/import content:write Créer un glossaire partagé, ou y importer des termes (?dry_run=true pour prévisualiser)
GET · PUT /api/v1/series/{id}/shared-glossary series:read · content:write Voir ou changer le glossaire partagé que suit une série

La référence complète

Options des requêtes, format du document JSON, champs de l’état et du rapport, vérification des webhooks, erreurs et limites : tout est dans le guide de l’API, en anglais.

Référence de l’API Lire le guide de l’API sur GitHub