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
-
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.
-
Envoyez le livre
POST /api/v1/translation-requestsaccepte un EPUB, des chapitres TXT ou DOCX, ou un document JSON. Libris Translate répond aussitôt202 Accepted. -
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. -
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).
#!/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.
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,failedavec sa raison, oucancelled. 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.translatedpour ê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/v1n’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çoit402 automation_not_licensed. -
Le même accès pour un agent
POST /mcpré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.latestdésigne le dernier) : eux seuls sont traduits.?scope=newne télécharge qu’eux,?scope=volumele 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, etsplit=headingsdé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 avec402 licence_quota_insufficient(ouallowance_insufficientpour 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 chemin | Portée | Rô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.