Proveedores

Los proveedores son los servicios de IA que potencian cada etapa del pipeline de voz. VOCALS soporta proveedores intercambiables para tres tipos: STT (speech-to-text), LLM (modelo de lenguaje) y TTS (text-to-speech).

Cada configuracion de proveedor almacena una API key cifrada, el modelo seleccionado y configuraciones opcionales especificas del proveedor. Los agentes referencian IDs de proveedor para definir su pipeline.

Proveedores Disponibles

Tipo	Nombre	Descripcion
`stt`	`deepgram`	Deepgram Nova STT en tiempo real
`stt`	`openai`	API de OpenAI Whisper STT
`stt`	`whisper`	OpenAI Whisper (local) STT
`stt`	`elevenlabs`	ElevenLabs STT
`stt`	`qwen`	Alibaba Qwen STT
`stt`	`fish`	Fish Audio STT
`llm`	`openai`	Modelos OpenAI GPT
`llm`	`claude`	Modelos Anthropic Claude
`llm`	`google`	Modelos Google Gemini
`llm`	`kimi`	Modelos Moonshot Kimi
`tts`	`deepgram`	Deepgram TTS
`tts`	`openai`	OpenAI TTS
`tts`	`elevenlabs`	ElevenLabs TTS
`tts`	`qwen`	Alibaba Qwen TTS
`tts`	`resemble`	Resemble AI TTS
`tts`	`fish`	Fish Audio TTS
`tts`	`google`	Google Cloud TTS (Neural2/WaveNet, Chirp3-HD, Studio)
`tts`	`google_gemini`	Google Gemini TTS (Gemini API)

google y google_gemini son proveedores distintos

Apuntan a APIs de Google diferentes y no son intercambiables. google llama a Cloud Text-to-Speech y toma una API key de Cloud Text-to-Speech; google_gemini llama a la Gemini API y toma una API key de la Gemini API, que se factura por separado. Una clave de uno es rechazada por el otro. Consulta Integración de Proveedores para la comparación completa.

Modelos de Google Gemini TTS

google_gemini acepta uno de tres valores de model_id:

`model_id`	Notas
`gemini-2.5-flash-preview-tts`	Predeterminado. Baja latencia y económico - el modelo a usar en telefonía.
`gemini-2.5-pro-preview-tts`	Mayor calidad, orientado a salida tipo pódcast/audiolibro.
`gemini-3.1-flash-tts-preview`	Ajustado para narración expresiva.

Reproduce estos ids exactamente. Los modelos 2.5 terminan en -preview-tts mientras que el modelo 3.1 termina en -tts-preview; la inconsistencia es de Google, y un id "corregido" devuelve 404 en el momento de la síntesis. Los tres son modelos Preview y Google puede cambiar los ids cuando alcancen la versión estable.

La voz se define en el agente como un nombre preconstruido simple (por ejemplo Zephyr), no como un id completo con prefijo de locale, y google_gemini no toma ningún parámetro de idioma - el idioma hablado sigue al texto del agente.

Listar Proveedores

GET /providers

Devuelve todas las configuraciones de proveedores del tenant actual, ordenadas por tipo y nombre.

Respuesta

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "stt",
    "name": "deepgram",
    "model_id": "nova-2",
    "extra_config": null,
    "is_active": true,
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-02-20T14:00:00Z"
  }
]

Campos de Respuesta

Campo	Tipo	Descripcion
`id`	uuid	ID de configuracion del proveedor
`type`	string	`stt`, `llm`, o `tts`
`name`	string	Nombre del proveedor (ej. `deepgram`, `openai`)
`model_id`	string	Identificador del modelo seleccionado
`extra_config`	object \| null	Configuracion especifica del proveedor
`is_active`	boolean	Si el proveedor esta activo
`created_at`	datetime	Marca de tiempo de creacion
`updated_at`	datetime	Marca de tiempo de ultima actualizacion

La API key nunca se devuelve en las respuestas.

Obtener Proveedor

GET /providers/{provider_id}

Devuelve una configuracion de proveedor individual.

Respuesta

Mismo esquema que el elemento de la lista anterior.

Crear Proveedor

POST /providers

Cuerpo de la Solicitud

{
  "type": "stt",
  "name": "deepgram",
  "api_key": "dg_live_abc123...",
  "model_id": "nova-2",
  "extra_config": { "language": "en" },
  "is_active": true
}

Campos de la Solicitud

Campo	Tipo	Requerido	Por defecto	Descripcion
`type`	string	Si	--	Tipo de proveedor: `stt`, `llm`, o `tts`
`name`	string	Si	--	Nombre del proveedor (debe ser un proveedor registrado)
`api_key`	string	Si	--	API key del proveedor (cifrada antes de almacenarse)
`model_id`	string	Si	--	Identificador del modelo a usar
`extra_config`	object	No	null	Configuraciones especificas del proveedor
`is_active`	boolean	No	`true`	Si el proveedor esta activo

Respuesta

201 Created -- Devuelve el objeto ProviderResponse.

Si el type no es stt, llm, o tts, la API devuelve 400. Si el name no es un proveedor registrado para el tipo dado, la API devuelve 400 con la lista de proveedores disponibles.

Predeterminado de Google Gemini: `thinking_budget`

Crear un proveedor LLM con name: "google" y sin thinking_budget en extra_config almacena "extra_config": { "thinking_budget": 0 }, lo que pide el menor razonamiento extendido que permita el modelo seleccionado: desactivado del todo en los modelos Gemini antiguos, y el nivel de razonamiento mas bajo en la generacion actual de Google, que no lo puede desactivar. El razonamiento anade segundos antes de que se pronuncie la primera palabra, y quien llama lo percibe como silencio. Envia tu propio thinking_budget en extra_config para mantener el razonamiento activo (por ejemplo { "thinking_budget": 1024 }); el valor que envies siempre se almacena tal cual.

Esto solo aplica a proveedores recien creados. Los proveedores existentes nunca se modifican, y PUT /providers/{provider_id} nunca anade el campo.

Actualizar Proveedor

PUT /providers/{provider_id}

Actualiza la API key, modelo, configuracion o estado activo de un proveedor. Solo incluye los campos que deseas cambiar.

Cuerpo de la Solicitud

{
  "api_key": "new_key_here",
  "model_id": "nova-2-general",
  "is_active": true
}

Campos de la Solicitud

Campo	Tipo	Requerido	Descripcion
`api_key`	string	No	Nueva API key (re-cifrada)
`model_id`	string	No	Nuevo identificador de modelo
`extra_config`	object	No	Configuraciones especificas del proveedor actualizadas
`is_active`	boolean	No	Activar o desactivar el proveedor

Respuesta

200 OK -- Devuelve el ProviderResponse actualizado.

Eliminar Proveedor

DELETE /providers/{provider_id}

Elimina permanentemente una configuracion de proveedor.

La eliminación se rechaza mientras algún agente siga referenciando el proveedor, de modo que ningún agente queda desvinculado como efecto colateral. Apunta esos agentes a otro proveedor o elimínalos primero, y vuelve a intentarlo.

Respuesta

204 No Content -- el proveedor se eliminó.

409 Conflict -- uno o más agentes todavía usan este proveedor. El cuerpo los nombra:

{
  "detail": {
    "error_code": "provider_in_use",
    "message": "This provider is still used by Demo Restaurant, Reception Bot. Point those agents elsewhere or delete them, then try again.",
    "agents": [
      { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Demo Restaurant" },
      { "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "name": "Reception Bot" }
    ]
  }
}

Campo	Tipo	Descripción
`error_code`	string	`provider_in_use`
`message`	string	Resumen legible, que nombra hasta cinco agentes
`agents`	array[object]	Todos los agentes que bloquean la eliminación, con `id` y `name`

403 Forbidden -- el proveedor es gestionado por VOCALS y no se puede eliminar aquí.

Listar Modelos Disponibles

GET /providers/{provider_id}/models

Obtiene la lista de modelos disponibles para un proveedor guardado usando su API key almacenada. Consulta la API del proveedor cuando es posible, o devuelve una lista predefinida para proveedores que no soportan la enumeracion de modelos.

Respuesta

{
  "models": ["nova-2", "nova-2-general", "nova-2-meeting"],
  "source": "api"
}

Campo	Tipo	Descripcion
`models`	array[string]	Identificadores de modelos disponibles
`source`	string	`api` (obtenido del proveedor), `hardcoded` (lista estatica), o `error` (fallo en la obtencion)

Para google_gemini esto devuelve los tres ids de modelo de Gemini TTS con el predeterminado primero y source: "hardcoded" - la lista es estática, por lo que no se hace ninguna llamada a Google.

Listar Voces de Google

GET /providers/{provider_id}/google-voices

Devuelve el catálogo estructurado de voces de Google Cloud TTS para un proveedor Google TTS guardado, usado para poblar el selector de voces del agente. Las voces Neural2/WaveNet/Chirp3-HD se obtienen en vivo del propio proyecto de Google Cloud del tenant (limitado a la API key almacenada). El proveedor debe ser un proveedor tts llamado google perteneciente al tenant actual.

Respuesta

{
  "voices": [
    {
      "id": "en-US-Chirp3-HD-Charon",
      "label": "Charon (Female)",
      "tier": "chirp",
      "language": "en-US",
      "gender": "Female"
    }
  ],
  "source": "live"
}

Campos de la Respuesta

Campo	Tipo	Descripcion
`voices`	array[object]	Entradas de voz para el selector
`voices[].id`	string	Identificador de voz completo a almacenar como el `voice_id` del agente
`voices[].label`	string	Etiqueta legible para mostrar
`voices[].tier`	string	`neural2`, `wavenet`, o `chirp`
`voices[].language`	string	Locale BCP-47 (uno de los siete soportados: `en-US`, `en-GB`, `es-ES`, `fr-FR`, `de-DE`, `pt-BR`, `it-IT`)
`voices[].gender`	string	`Male`, `Female`, `Neutral`, o vacío cuando no se especifica
`source`	string	`live` (obtenido de Google), `cache` (servido de una obtención reciente), o `error` (la obtención en vivo falló; `voices` viene vacío y el cliente debe recurrir a su propia lista estática)

Un source de error no es un fallo HTTP - el endpoint aún devuelve 200 con un array voices vacío para que el selector pueda degradarse con gracia a su propia lista estática. Las voces Studio nunca se devuelven (ya no son seleccionables para nuevas voces).

Devuelve 404 si el proveedor no se encuentra para el tenant o no es un proveedor Google Cloud TTS. Este endpoint es exclusivo de Cloud TTS: un proveedor google_gemini también devuelve 404, porque sus 30 voces preconstruidas son una lista fija definida por el modelo, sin catálogo por tenant que obtener.

Obtener Modelos (Ad-hoc)

POST /providers/models

Obtiene modelos disponibles sin guardar una configuracion de proveedor. Util para probar una API key antes de crear un proveedor.

Cuerpo de la Solicitud

{
  "type": "stt",
  "name": "deepgram",
  "api_key": "dg_live_abc123..."
}

Respuesta

Mismo esquema ProviderModelsResponse que el anterior.

Probar Proveedor

POST /providers/{provider_id}/test

Valida que la API key y configuracion de un proveedor guardado funcionan correctamente. Llama al metodo validate() del proveedor.

Respuesta

{
  "success": true,
  "message": "Provider deepgram (stt) is working correctly."
}

Campo	Tipo	Descripcion
`success`	boolean	Si la validacion fue exitosa
`message`	string	Mensaje de resultado legible

Devuelve 400 si la API key es invalida, o una respuesta con success: false si la validacion falla por otras razones.

Proveedores Disponibles​

Modelos de Google Gemini TTS​

Listar Proveedores​

Respuesta​

Campos de Respuesta​

Obtener Proveedor​

Respuesta​

Crear Proveedor​

Cuerpo de la Solicitud​

Campos de la Solicitud​

Respuesta​

Predeterminado de Google Gemini: thinking_budget​

Actualizar Proveedor​

Cuerpo de la Solicitud​

Campos de la Solicitud​

Respuesta​

Eliminar Proveedor​

Respuesta​

Listar Modelos Disponibles​

Respuesta​

Listar Voces de Google​

Respuesta​

Campos de la Respuesta​

Obtener Modelos (Ad-hoc)​

Cuerpo de la Solicitud​

Respuesta​

Probar Proveedor​

Respuesta​

Proveedores Disponibles

Modelos de Google Gemini TTS

Listar Proveedores

Respuesta

Campos de Respuesta

Obtener Proveedor

Respuesta

Crear Proveedor

Cuerpo de la Solicitud

Campos de la Solicitud

Respuesta

Predeterminado de Google Gemini: `thinking_budget`

Actualizar Proveedor

Cuerpo de la Solicitud

Campos de la Solicitud

Respuesta

Eliminar Proveedor

Respuesta

Listar Modelos Disponibles

Respuesta

Listar Voces de Google

Respuesta

Campos de la Respuesta

Obtener Modelos (Ad-hoc)

Cuerpo de la Solicitud

Respuesta

Probar Proveedor

Respuesta