Traduce PDFs con BabelDOC en una URL base de OpenAI personalizada.

Respuesta rápida: tres flags enrutan cada llamada de traducción.

La línea de comandos de BabelDOC toma el endpoint directamente: --openai activa el traductor LLM, --openai-base-url configura a dónde van las peticiones, --openai-api-key autentica, y --openai-model elige el id del modelo. Los propios ejemplos del README muestran exactamente este conjunto de flags, y su nota sobre el servicio de traducción establece que solo se admiten LLM compatibles con OpenAI, lo que hace de un gateway multi-proveedor compatible con OpenAI la opción natural en lugar de un rodeo. Como el id del modelo se reenvía como un string simple, funciona cualquier cosa que sirva el endpoint: los propios documentos upstream recomiendan modelos amigables con la compatibilidad OpenAI de las familias GLM y DeepSeek, y a través de APIsRouter esos conviven junto a ids de Claude y Gemini detrás de la misma URL 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"

Cómo convierte BabelDOC un PDF en llamadas de modelo.

BabelDOC (funstory-ai en GitHub, unas 9K estrellas, del equipo detrás de Immersive Translate) es un traductor de documentos PDF que preserva el diseño: analiza la estructura del documento, protege fórmulas y figuras, encuentra párrafos, los traduce con un LLM, y reconstruye el PDF como una versión monolingüe traducida y una versión bilingüe lado a lado. Se distribuye como CLI y como API de Python, y es la contraparte autoalojada del servicio alojado de BabelDOC. La fase de traducción es donde importa el endpoint. Un documento se convierte en muchas peticiones de chat-completions del tamaño de un párrafo, regulado por el flag --qps (4 consultas por segundo por defecto) y procesado por un pool de workers (pool-max-workers, por defecto igual al valor de QPS). Esa forma tiene dos consecuencias. Primero, la traducción es una carga de trabajo de volumen: un PDF largo son cientos de llamadas pequeñas, así que el precio por token se acumula rápido. Segundo, a diferencia de las cargas de recuperación donde el modelo mayormente lee, la traducción escribe aproximadamente tanto como lee, así que el precio de tokens de salida importa tanto como el de entrada al comparar ids. BabelDOC también cachea las traducciones, así que volver a ejecutar un documento reutiliza resultados previos a menos que pases --ignore-cache. Los CSV de glosario (--glossary-files) fijan terminología a lo largo de la ejecución, y --max-pages-per-part divide documentos muy grandes en partes que se traducen y fusionan automáticamente.

Configuración completa: flags de CLI o el archivo de config TOML.

Para uso repetido, los mismos ajustes viven en un archivo TOML pasado con --config. La tabla [babeldoc] acepta las mismas claves en kebab-case: openai, openai-model, openai-base-url, openai-api-key, más las opciones de rendimiento y de salida. Esto mantiene la clave fuera de tu historial de shell y hace que un perfil de traducción sea reproducible entre documentos. La configuración de abajo es un perfil práctico de volumen: un id rápido para la mayoría de los documentos, QPS elevado para coincidir con un gateway agrupado, y ambos modos de salida mantenidos. Cambia openai-model a un id más fuerte para documentos donde el matiz importa más que el rendimiento.

[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"

Elegir un modelo de traducción.

El flujo de comparación es concreto: traduce las mismas diez páginas con dos ids (la caché con clave por ejecución los mantiene separados), lee los duales lado a lado, y revisa el log de uso por clave para ver cuánto costó cada pasada. La mayoría de los equipos terminan con un valor por defecto rápido más un perfil premium para documentos que lo merecen, ambos como archivos TOML.

• Los documentos de volumen (manuales, papers que se leen una vez) encajan con deepseek-v4-flash: la calidad de traducción se mantiene para prosa técnica y el coste por página es cercano a insignificante.
• La traducción con destino chino es terreno conocido para glm-5.2 y la familia DeepSeek; los propios documentos upstream apuntan a modelos GLM y DeepSeek como opciones bien comportadas compatibles con OpenAI.
• Los documentos donde el matiz es crítico (contratos, traducciones publicadas) justifican claude-sonnet-4-6 o claude-haiku-4-5-20251001, que siguen la terminología y el registro con más fidelidad a lo largo de documentos largos.
• Los tokens de salida importan aquí. La traducción escribe tanto como lee, así que compara ids también en la columna de precio de salida, no solo en la de entrada.
• Empareja glosarios con ids rápidos. Un CSV de glosario fija la terminología en la que los modelos rápidos a veces derivan, lo que cierra buena parte de la brecha de calidad en texto técnico.

Pago por uso · por debajo del precio oficial

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

Modos de fallo y ajuste de rendimiento.

QPS es el mando que interactúa con el gateway. El valor por defecto de 4 consultas por segundo es conservador; la capacidad upstream agrupada suele sostener más, y elevar --qps (con pool-max-workers siguiéndolo) es cómo un documento de 300 páginas deja de tardar toda la tarde. Auméntalo gradualmente vigilando respuestas 429 en lugar de saltar a un número grande en frío, porque un párrafo limitado por tasa reintenta y ralentiza toda la ejecución. Los flags solo aplican cuando --openai está activado. Pasar una URL base sin --openai deja el traductor desactivado, lo que se manifiesta como una ejecución que analiza el PDF pero nunca traduce. Los ids de modelo son strings exactos contra el listado /v1/models del endpoint; una errata falla la primera llamada de párrafo con model-not-found. Un 401 significa que la clave y la URL base no pertenecen juntas. Los problemas de diseño no son problemas de endpoint. Texto superpuesto, fórmulas perdidas o tablas rotas se rastrean al lado del análisis del PDF (prueba --enhance-compatibility, --ocr-workaround para documentos escaneados, o el interruptor de texto enriquecido), y cambiar de modelo no los arreglará. Lo contrario también aplica: la terminología mal traducida es un problema de modelo o glosario, no de analizador. La caché puede enmascarar cambios. Después de cambiar de modelo, pasa --ignore-cache si quieres que el nuevo id retraduzca contenido que el id anterior ya cubrió; de lo contrario, los párrafos cacheados quedan como estaban.

Quién enruta BabelDOC a través de un gateway.

• Investigadores que traducen papers en volumen, donde cientos de llamadas pequeñas por documento hacen del precio por volumen y la visibilidad de uso por clave todo el juego.
• Equipos que estandarizan documentación bilingüe, ejecutando un perfil rápido por defecto y un perfil premium contra el mismo endpoint con distintos strings de modelo.
• Usuarios en mercados donde los modelos de traducción más fuertes para su par de idiomas están con distintos proveedores: ids de GLM, DeepSeek, Claude y Gemini todos detrás de una clave.
• Autoalojadores que reemplazan el servicio alojado para documentos confidenciales, manteniendo el análisis local y enviando solo el texto de los párrafos a un endpoint auditable.
• Desarrolladores sin acceso a la facturación de un proveedor concreto. El acceso mediante recarga sin necesidad de tarjeta elimina la dependencia de registrarse en cada proveedor.

Verifica el endpoint y depura el primer documento.

Lista los modelos que tu clave puede direccionar antes de empezar una ejecución larga; --openai-model debe coincidir exactamente con un id servido. Luego traduce algo pequeño (un PDF de una página, o --pages 1 en uno más grande) de principio a fin. Un 401 en el primer párrafo significa que la clave no coincide con la URL base. Model-not-found es una errata en el id. Una ejecución que analiza pero nunca llama al endpoint le falta --openai. Bloqueos frecuentes con mensajes de reintento apuntan a un QPS configurado más alto de lo que el endpoint sostiene; bájalo y vuelve a subirlo gradualmente. Una vez que los documentos fluyen, la consola de APIsRouter muestra el modelo por petición, el recuento de tokens y el gasto. El coste de traducción escala con la longitud del documento en ambas direcciones (entrada y salida), y el log de uso por clave es cómo aprendes tu coste real por página para cada modelo en lugar de estimarlo.

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

Preguntas frecuentes