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 Translate sans ouvrir l’interface web. Toute la chaîne tourne sous le pilote automatique, et chaque requête se termine soit par un résultat, soit par une raison explicite.

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 Translate répond aussitôt 202 Accepted.

  3. Suivez la requête

    Interrogez son état avec ?wait= pour que l’appel reste ouvert jusqu’à la fin (600 secondes au plus), ou laissez un webhook signé vous prévenir, y compris après chaque lot de chapitres traduits.

  4. Récupérez le résultat

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

Un exemple complet

Envoyer un EPUB, attendre la fin, 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 sans modification du guide de l’API livré avec Libris Translate (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, 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 interrogation longue, télécharge le résultat, patiente quand le débit est limité et reçoit les webhooks après en avoir vérifié la signature. Il est livré avec Libris Translate, dans examples/ ; lancez-le comme une 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

Pensée pour les scripts sans surveillance

  • Jetons à portée limitée

    Neuf portées, de series:read à library:delete, une expiration facultative et une révocation immédiate. Les jetons sont stockés sous forme d’empreinte SHA-256 et limités chacun à 120 requêtes par minute par défaut.

  • 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.

  • Toute requête a une fin

    Une 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 sans autorisation explicite, et jusqu’à six tentatives en tout par défaut. Abonnez-vous à chapters.translated pour être prévenu à chaque lot de chapitres.

  • Un rapport avec chaque résultat

    État des passages, passages conservés en langue originale et pourquoi, coût estimé et coût réel, passages et chapitres à relire en priorité, durées, et 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. Studio et Pro comprennent l’API ; avec une autre licence, un jeton valide reçoit 402 automation_not_licensed.

  • Le même accès pour un agent

    POST /mcp répond au Model Context Protocol avec les mêmes jetons et les mêmes portées, pour opencode, Claude Code ou Codex. Les scripts passent par l’API REST, les agents par MCP.

  • Une série suivie dans la durée

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

  • Parties, prologues, interludes

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

  • Budgets et file équitable

    Un jeton peut avoir un budget mensuel ou total (402 budget_exceeded), un plafond de priorité et ses propres quotas (429 queue_full). Un livre est compté dès son ajout : celui qui ne tient pas dans ce qui reste du quota de mots de la licence plus la marge est refusé en entier avec 402 licence_quota_insufficient (ou allowance_insufficient pour le quota propre du compte), et rien n’est importé. L’état de la requête indique où elle 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 le travail de la requête
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 tome (?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
POST /api/v1/series/{id}/jobs/{action} jobs:control (+ pipeline:start) Lancer, suspendre, reprendre ou annuler les travaux de toute une série dont vous êtes propriétaire
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 un aperçu)
GET · PUT /api/v1/series/{id}/shared-glossary series:read · content:write Consulter 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 figure dans la référence ci-dessous et dans le guide de l’API livré avec Libris Translate.