Proveedores

verbatra incluye cinco proveedores detrás de una sola interfaz: Anthropic, OpenAI, Gemini y openai-compatible (un servidor local o autoalojado compatible con OpenAI) son modelos de lenguaje grandes, y DeepL es un servicio de traducción automática. Seleccionas uno en el bloque provider de tu configuración, por id. Cada id de modelo en esta página es un ejemplo, no una recomendación: los catálogos de modelos cambian, así que consulta la lista actual de tu proveedor.

¿Cuál elijo?

Cualquier proveedor funciona con cualquier formato y comando; la elección va de coste, calidad, privacidad y cómo consigues una clave.

• ¿Proyecto pequeño o secundario, y lo quieres gratis? Usa Gemini. Tiene un nivel de API gratuito de verdad, así que puedes traducir una app entera a coste cero. Consigue una clave en Google AI Studio y define GEMINI_API_KEY. El nivel gratuito tiene límite de tasa (mira la nota más abajo), que solo importa en una primera ejecución grande.
• ¿La mejor calidad de traducción para una app de producción? Usa Anthropic u OpenAI. Ambos son LLM de pago y leen ANTHROPIC_API_KEY u OPENAI_API_KEY.
• ¿Alto volumen, dirigido por glosario, o sin LLM de por medio? Usa DeepL. Es una API dedicada de traducción automática con un nivel gratuito y uno de pago, y soporta un glosario nativo por id. No traduce cadenas con marcadores de posición (mira la nota más abajo); para esas, usa un proveedor LLM.
• ¿Sin conexión, sin coste, o tus cadenas no pueden salir de tu red? Usa openai-compatible. Apunta verbatra a un servidor de inferencia local o autoalojado (LM Studio, Ollama, vLLM) en lugar de a una API alojada. Sin cuenta, sin clave de API y sin salida de red más allá de tu propia máquina o LAN.

¿No lo tienes claro? Empieza en el nivel gratuito de Gemini y cambia de proveedor más tarde editando un solo id en tu configuración. Nada más cambia.

Las claves vienen del entorno

verbatra nunca lee una clave de API de la configuración. Cada proveedor alojado lee exactamente una variable de entorno:

Define la variable en .env (que verbatra init añade a .gitignore) o expórtala en tu shell o en el almacén de secretos de tu CI. Cuando la variable no está definida o está vacía, el proveedor falla con un error estructurado MISSING_API_KEY cuyo mensaje nombra la variable pero nunca incluye el valor de una clave. Nunca confirmes una clave real.

openai-compatible es distinto: la mayoría de los servidores locales no necesitan clave, así que no está en esta tabla. Mira su propia sección más abajo para saber cómo resuelve su clave.

Anthropic

provider: {
  id: "anthropic",
  options: {
    model: "claude-sonnet-4-6", // example model id
    maxTokens: 4096,
  },
}

Lee ANTHROPIC_API_KEY. model y maxTokens son ambos obligatorios. maxTokens limita los tokens que puede producir una sola respuesta; es la opción de límite de tokens de salida de este proveedor (los demás la llaman maxOutputTokens).

OpenAI

provider: {
  id: "openai",
  options: {
    model: "gpt-5.4-mini", // example model id
    maxOutputTokens: 4096,
  },
}

Lee OPENAI_API_KEY. model y maxOutputTokens son ambos obligatorios.

Gemini

provider: {
  id: "gemini",
  options: {
    model: "gemini-2.5-flash", // example model id
    maxOutputTokens: 4096,
  },
}

Lee GEMINI_API_KEY. model y maxOutputTokens son ambos obligatorios.

DeepL

provider: {
  id: "deepl",
  options: {},
}

Lee DEEPL_API_KEY. DeepL es una API de traducción automática, no un LLM: no tiene campo model ni límite de tokens de salida. La única opción es un glossaryId opcional que nombra un glosario que ya has creado en DeepL:

provider: {
  id: "deepl",
  options: {
    glossaryId: "<your-glossary-id>",
  },
}

DeepL se degrada con elegancia en lugar de fallar cuando no puede respetar un ajuste, e informa de cada degradación como un aviso en la ejecución:

• Un mapa de términos glossary configurado no se aplica (DeepL solo usa un id de glosario creado de antemano), informado como GLOSSARY_IGNORED.
• tone se asigna a la formalidad de DeepL: formal pasa a más formal, informal a menos formal, neutral o un tono ausente se omite. Con una clave del nivel gratuito, la formalidad no está soportada, así que un tono distinto del predeterminado se degrada al predeterminado, informado como FORMALITY_DOWNGRADED.

openai-compatible

Apunta verbatra a un servidor que habla la API Chat Completions de OpenAI: LM Studio, Ollama, vLLM y similares funcionan todos. El id nombra el protocolo de cable, no dónde corre el servidor, así que una API alojada que hable el mismo protocolo también encaja aquí.

provider: {
  id: "openai-compatible",
  options: {
    baseUrl: "http://192.168.178.74:1234/v1",
    model: "qwen2.5-14b-instruct", // example: whatever your server exposes
    maxOutputTokens: 1024,
  },
}

baseUrl, model y maxOutputTokens son obligatorios. A diferencia de todos los demás proveedores, baseUrl vive en la configuración y no en el entorno: es una dirección de red que ya conoces (una IP de LAN o localhost), no un secreto. Debe ser una URL absoluta válida con esquema http o https; cualquier otra cosa, incluido un esquema ausente, hace fallar la validación de la configuración de inmediato.

baseUrl debe incluir el segmento de ruta de la API de tu servidor, normalmente /v1: LM Studio, Ollama y vLLM sirven todos sus rutas compatibles con OpenAI bajo /v1. Un baseUrl sin él sigue siendo una URL sintácticamente válida, así que pasa la validación de la configuración y en su lugar falla en tiempo de solicitud al llegar a la ruta equivocada.

Una API alojada que hable el mismo protocolo funciona igual. La API de chat completions de Mistral es un ejemplo:

provider: {
  id: "openai-compatible",
  options: {
    baseUrl: "https://api.mistral.ai/v1",
    model: "mistral-large-latest", // example: check Mistral's current model list
    maxOutputTokens: 4096,
    apiKeyEnvVar: "MISTRAL_API_KEY",
  },
}

apiKeyEnvVar nombra la variable de entorno que contiene tu clave para ese servidor. Es el mismo proveedor openai-compatible apuntado a otro endpoint, no un proveedor dedicado de Mistral.

Las claves son opcionales

La mayoría de los servidores de inferencia locales no necesitan clave de API, así que openai-compatible resuelve su clave en tres niveles, en orden:

1. apiKeyEnvVar, un campo opcional de la configuración que nombra una variable de entorno de la que leer una clave real. Si defines este campo y su variable nombrada no está definida o está vacía, verbatra falla con MISSING_API_KEY en lugar de caer en silencio al siguiente nivel, porque dijiste explícitamente que se requiere una clave.
2. OPENAI_COMPATIBLE_API_KEY, una variable de entorno por convención, leída cuando apiKeyEnvVar no está definido. Si está definida y no vacía, verbatra la usa; si no, verbatra sigue adelante sin error.
3. El marcador "local", enviado cuando ninguno de los anteriores resuelve nada. Es una cadena fija y no secreta, no una clave real, y es exactamente lo que hace que un servidor local sin clave funcione con cero configuración.

apiKeyEnvVar nunca puede nombrar ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY ni DEEPL_API_KEY: la validación de la configuración lo rechaza de plano, así que una configuración no puede apuntar este proveedor a la clave de un proveedor alojado por su nombre. El cliente tampoco lee nunca OPENAI_API_KEY por su cuenta y siempre pasa un valor de clave explícito al SDK subyacente, así que una clave alojada nunca puede llegar a un baseUrl personalizado.

Elegir un modelo local

Prefiere un modelo ajustado por instrucciones, sin razonamiento y con buena cobertura multilingüe. verbatra pide un único objeto JSON estricto y lo valida, así que quieres un modelo que siga de forma fiable las indicaciones de formato. qwen2.5-14b-instruct es un valor por defecto razonable; elige el mayor modelo de ese tipo que tu hardware ejecute bien.

Un modelo local malo falla de forma ruidosa, no en silencio: verbatra valida cada respuesta del proveedor contra un esquema canónico más la integridad de marcadores de posición e ICU, así que un modelo que emite prosa de razonamiento o JSON truncado se rechaza con un error INVALID_RESPONSE u OUTPUT_TRUNCATED en lugar de escribir una traducción corrupta.

Parseo tolerante para modelos locales y más pequeños

openai-compatible solicita el mismo formato de respuesta estricto y restringido por esquema que el proveedor alojado openai. La única diferencia está a la vuelta: los modelos locales y más pequeños tienden más a envolver una respuesta por lo demás correcta en prosa alrededor o en una valla de código Markdown a pesar de que se les pide que no, así que openai-compatible extrae el primer objeto JSON balanceado en cualquier parte de la respuesta antes de parsear, cosa que el proveedor alojado no hace. Su salida pasa igualmente por exactamente la misma validación de esquema y las mismas comprobaciones de integridad de marcadores de posición e ICU que la de cualquier otro proveedor: la salida de un modelo local es entrada no de fiar, y una respuesta malformada o con marcadores de posición discordantes se rechaza de la misma manera.

Tono y glosario entre proveedores

Los campos opcionales tone y glossary de la configuración (consulta Archivo de configuración) se aplican por proveedor:

• Tono. Los proveedores LLM (Anthropic, OpenAI, Gemini y openai-compatible) reciben el tono con la solicitud y se les instruye para respetarlo. DeepL lo asigna a la formalidad, con la degradación del nivel gratuito descrita arriba.
• Glosario. Los proveedores LLM reciben el mapa de términos y se les instruye para tratar sus términos como vinculantes. DeepL ignora un mapa de términos (con un aviso GLOSSARY_IGNORED) y aplica solo su glossaryId nativo.

Comportamiento que todo proveedor comparte

Lotes

El trabajo de un locale se divide en sublotes secuenciales de como mucho maxBatchSize entradas (por defecto 50; consulta Archivo de configuración), así que una solicitud sobredimensionada no puede hacer fallar el locale entero. Un sublote fallido se retiene y se reintenta automáticamente en la siguiente ejecución mientras los demás sublotes siguen avanzando. DeepL además reparte un sublote entre tantas solicitudes como exijan sus propios topes por solicitud, de forma transparente.

Reintentos

Los fallos transitorios (una respuesta de límite de tasa o un error de servidor) se reintentan automáticamente con una pequeña espera: los clientes de los SDK de OpenAI, Anthropic y DeepL reintentan por defecto, y verbatra añade un reintento propio equivalente para Gemini, cuyo SDK no lo hace. Los reintentos suavizan tropiezos momentáneos; un fallo sostenido sigue aflorando como un error estructurado.

Errores estructurados

Un fallo de proveedor nunca aflora como un error crudo del SDK, que podría llevar cabeceras de la solicitud o una clave. verbatra clasifica cada fallo por su estado HTTP o la clase de error del SDK y levanta un error estructurado con un código estable y un mensaje fijo y sin secretos:

Un fallo solo afecta a su propio sublote: las claves fallidas se retienen y se recogen de nuevo en la siguiente ejecución.

Límites de tokens de salida

Los cuatro proveedores LLM limitan cuántos tokens puede producir una sola respuesta. Cuando un modelo se detiene porque alcanzó ese tope, verbatra levanta OUTPUT_TRUNCATED en lugar de un fallo genérico de respuesta malformada, con un mensaje fijo:

The provider stopped because the output-token limit was reached. Reduce the batch size or raise the configured max output tokens.

Cualquiera de las dos palancas lo resuelve: baja maxBatchSize en tu configuración para que cada solicitud produzca una respuesta más pequeña, o sube el tope por respuesta del proveedor (maxTokens para Anthropic, maxOutputTokens para OpenAI, Gemini y openai-compatible). DeepL no se ve afectado: no tiene caso de truncado por tokens de salida. verbatra también se recupera por sí solo: cuando un sub-lote se trunca, lo divide en mitades y lo reintenta, bajando hasta una sola entrada, de modo que las claves que caben en una solicitud más pequeña se traducen igualmente y solo una entrada aislada que sigue desbordándose se retiene para la siguiente ejecución.

Señales de revisión

Las traducciones aceptadas de todos los proveedores pasan por las mismas comprobaciones posteriores a la traducción, y un resultado sospechoso (por ejemplo uno idéntico a su origen, o uno que se saltó un término del glosario) se marca hacia la cola de revisión en lugar de rechazarse. Los códigos de motivo y cómo trabajar la cola se cubren en Seguridad de la traducción y Revisión en Studio.