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

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.

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. Los agentes que referencien este proveedor necesitaran ser actualizados.

Respuesta

204 No Content

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)

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.