Traduisez des PDF avec BabelDOC sur une URL de base OpenAI personnalisée.

Réponse rapide : trois flags routent chaque appel de traduction.

La ligne de commande de BabelDOC prend l'endpoint directement : --openai active le traducteur LLM, --openai-base-url règle où vont les requêtes, --openai-api-key authentifie, et --openai-model choisit l'id du modèle. Les exemples du README montrent exactement cet ensemble de flags, et sa note sur le service de traduction indique que seuls les LLM compatibles OpenAI sont pris en charge, ce qui fait d'une passerelle compatible OpenAI multi-fournisseurs le choix naturel plutôt qu'un contournement. Comme l'id de modèle est transmis comme une simple chaîne, tout ce que sert l'endpoint fonctionne : la documentation amont recommande elle-même des modèles bien adaptés à OpenAI-compatible des familles GLM et DeepSeek, et via APIsRouter ceux-ci se retrouvent aux côtés des ids Claude et Gemini derrière la même URL de base.

babeldoc --files paper.pdf \
  --lang-in en --lang-out zh \
  --openai \
  --openai-model "deepseek-v4-flash" \
  --openai-base-url "https://api.apisrouter.com/v1" \
  --openai-api-key "$APISROUTER_API_KEY"

Comment BabelDOC transforme un PDF en appels de modèle.

BabelDOC (funstory-ai sur GitHub, environ 9 000 étoiles, de l'équipe derrière Immersive Translate) est un traducteur de documents PDF qui préserve la mise en page : il analyse la structure du document, protège les formules et les figures, repère les paragraphes, les traduit avec un LLM, et reconstruit le PDF en une version mono traduite et une version double côte à côte. Il est livré comme une CLI et une API Python, et c'est le pendant auto-hébergé du service BabelDOC hébergé. La phase de traduction est là où l'endpoint compte. Un document devient de nombreuses requêtes chat-completions de la taille d'un paragraphe, limitées par le flag --qps (4 requêtes par seconde par défaut) et traitées par un pool de workers (pool-max-workers, qui prend par défaut la valeur du QPS). Cette forme a deux conséquences. D'abord, la traduction est une charge de volume : un long PDF représente des centaines de petits appels, donc le prix par token se cumule vite. Ensuite, contrairement aux charges de récupération où le modèle lit surtout, la traduction écrit à peu près autant qu'elle lit, donc le prix des tokens de sortie compte autant que celui d'entrée quand vous comparez des ids. BabelDOC met aussi en cache les traductions, donc relancer un document réutilise les résultats précédents sauf si vous passez --ignore-cache. Les CSV de glossaire (--glossary-files) figent la terminologie sur toute l'exécution, et --max-pages-per-part scinde les très gros documents en parties traduites et fusionnées automatiquement.

Configuration complète : flags CLI ou fichier de config TOML.

Pour un usage répété, les mêmes réglages vivent dans un fichier TOML passé avec --config. La table [babeldoc] accepte les mêmes clés en kebab-case : openai, openai-model, openai-base-url, openai-api-key, plus les options de débit et de sortie. Cela garde la clé hors de votre historique shell et rend un profil de traduction reproductible d'un document à l'autre. La config ci-dessous est un profil de volume pratique : un id rapide pour la majorité des documents, un QPS relevé pour correspondre à une passerelle mutualisée, et les deux modes de sortie conservés. Remplacez openai-model par un id plus puissant pour les documents où la nuance compte plus que le débit.

[babeldoc]
lang-in = "en-US"
lang-out = "zh-CN"
qps = 10
pool-max-workers = 10

# Translation service
openai = true
openai-model = "deepseek-v4-flash"
openai-base-url = "https://api.apisrouter.com/v1"
openai-api-key = "sk-YOUR-APISROUTER-KEY"

# Output control
no-dual = false
no-mono = false
watermark-output-mode = "no_watermark"

Choisir un modèle de traduction.

Le flux de comparaison est concret : traduisez les mêmes dix pages avec deux ids (le cache indexé par exécution les garde séparés), lisez les versions doubles côte à côte, et vérifiez le journal d'usage par clé pour ce qu'a coûté chaque passe. La plupart des équipes se posent sur un défaut rapide plus un profil premium pour les documents qui le méritent, les deux en fichiers TOML.

• Les documents de volume (manuels, articles lus une fois) conviennent à deepseek-v4-flash : la qualité de traduction tient pour la prose technique et le coût par page est proche du négligeable.
• La traduction vers le chinois est un jeu à domicile pour glm-5.2 et la famille DeepSeek ; la documentation amont pointe elle-même vers les modèles GLM et DeepSeek comme des choix compatibles OpenAI bien élevés.
• Les documents où la nuance est critique (contrats, traductions publiées) justifient claude-sonnet-4-6 ou claude-haiku-4-5-20251001, qui suivent la terminologie et le registre plus fidèlement sur de longs documents.
• Les tokens de sortie comptent ici. La traduction écrit autant qu'elle lit, donc comparez les ids aussi sur la colonne de prix de sortie, pas seulement d'entrée.
• Associez les glossaires aux ids rapides. Un CSV de glossaire fige la terminologie sur laquelle les modèles rapides dérivent parfois, ce qui comble une grande partie de l'écart de qualité sur le texte technique.

Paiement à l'usage · en dessous du tarif officiel

Selected models are priced below official list prices. Exact input, output, cache, and per-request prices are shown for each model.

Modes d'échec et réglage du débit.

QPS est le bouton qui interagit avec la passerelle. Le défaut de 4 requêtes par seconde est conservateur ; la capacité amont mutualisée en soutient généralement plus, et relever --qps (avec pool-max-workers qui le suit) est ce qui évite qu'un document de 300 pages ne prenne tout l'après-midi. Montez-le progressivement en surveillant les réponses 429 plutôt que de sauter à froid vers un grand nombre, car un paragraphe limité en débit retente et ralentit toute l'exécution. Les flags ne s'appliquent que si --openai est réglé. Passer une URL de base sans --openai laisse le traducteur désactivé, ce qui se manifeste par une exécution qui analyse le PDF mais ne traduit jamais. Les ids de modèle sont des chaînes exactes par rapport au listing /v1/models de l'endpoint ; une faute de frappe fait échouer le premier appel de paragraphe avec model-not-found. Un 401 signifie que la clé et l'URL de base ne vont pas ensemble. Les problèmes de mise en page ne sont pas des problèmes d'endpoint. Un texte qui se chevauche, des formules perdues ou des tableaux cassés remontent au côté analyse du PDF (essayez --enhance-compatibility, --ocr-workaround pour les documents scannés, ou le bascule rich-text), et changer de modèle ne les corrigera pas. L'inverse est vrai aussi : une terminologie mal traduite est un problème de modèle ou de glossaire, pas un problème d'analyseur. Le cache peut masquer les changements. Après avoir changé de modèle, passez --ignore-cache si vous voulez que le nouvel id retraduise le contenu que l'ancien id avait déjà couvert ; sinon les paragraphes en cache restent tels quels.

Qui route BabelDOC via une passerelle.

• Les chercheurs qui traduisent des articles en masse, où des centaines de petits appels par document font du tarif de volume et de la visibilité d'usage par clé tout l'enjeu.
• Les équipes qui standardisent une documentation bilingue, faisant tourner un profil rapide par défaut et un profil premium contre le même endpoint avec des chaînes de modèle différentes.
• Les utilisateurs sur des marchés où les modèles de traduction les plus forts pour leur paire de langues appartiennent à différents fournisseurs : les ids GLM, DeepSeek, Claude et Gemini tous derrière une seule clé.
• Les auto-hébergeurs qui remplacent le service hébergé pour des documents confidentiels, en gardant l'analyse locale et en n'envoyant que le texte des paragraphes à un seul endpoint auditable.
• Les développeurs sans accès à la facturation d'un fournisseur donné. Un accès basé sur la recharge, sans exigence de carte, supprime la dépendance à une inscription par fournisseur.

Vérifiez l'endpoint et déboguez le premier document.

Listez les modèles que votre clé peut adresser avant de démarrer une longue exécution ; --openai-model doit correspondre exactement à un id servi. Traduisez ensuite quelque chose de minuscule (un PDF d'une page, ou --pages 1 sur un plus gros) de bout en bout. Un 401 sur le premier paragraphe signifie que la clé ne correspond pas à l'URL de base. Model-not-found est une faute de frappe dans l'id. Une exécution qui analyse mais n'appelle jamais l'endpoint manque de --openai. Des blocages fréquents avec des messages de retry pointent vers un QPS réglé plus haut que ce que soutient l'endpoint ; baissez-le puis remontez progressivement. Une fois que les documents circulent, la console APIsRouter affiche le modèle par requête, le nombre de tokens et la dépense. Le coût de traduction évolue avec la longueur du document dans les deux directions (entrée et sortie), et le journal d'usage par clé est la façon d'apprendre votre coût réel par page pour chaque modèle plutôt que de l'estimer.

curl -s https://api.apisrouter.com/v1/models \
  -H "Authorization: Bearer $APISROUTER_API_KEY" | head -50

# then a one-page smoke test
babeldoc --config babeldoc.toml --files sample.pdf --pages 1

Questions fréquentes