Providers

Providers are the AI services that power each stage of the voice pipeline. VOCALS supports swappable providers for three types: STT (speech-to-text), LLM (language model), and TTS (text-to-speech).

Each provider configuration stores an encrypted API key, the selected model, and optional provider-specific settings. Agents reference provider IDs to define their pipeline.

Available Providers

Type	Name	Description
stt	deepgram	Deepgram Nova real-time STT
stt	openai	OpenAI Whisper API STT
stt	whisper	OpenAI Whisper (local) STT
stt	elevenlabs	ElevenLabs STT
stt	qwen	Alibaba Qwen STT
llm	openai	OpenAI GPT models
llm	claude	Anthropic Claude models
llm	google	Google Gemini models
llm	kimi	Moonshot Kimi models
tts	deepgram	Deepgram TTS
tts	openai	OpenAI TTS
tts	elevenlabs	ElevenLabs TTS
tts	qwen	Alibaba Qwen TTS
tts	resemble	Resemble AI TTS

List Providers

GET /providers

Returns all provider configurations for the current tenant, ordered by type and name.

Response

[
  {
    "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"
  }
]

Response Fields

Field	Type	Description
id	uuid	Provider config ID
type	string	stt, llm, or tts
name	string	Provider name (e.g. deepgram, openai)
model_id	string	Selected model identifier
extra_config	object | null	Provider-specific configuration
is_active	boolean	Whether the provider is active
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp

The API key is never returned in responses.

Get Provider

GET /providers/{provider_id}

Returns a single provider configuration.

Response

Same schema as the list item above.

Create Provider

POST /providers

Request Body

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

Request Fields

Field	Type	Required	Default	Description
type	string	Yes	--	Provider type: stt, llm, or tts
name	string	Yes	--	Provider name (must be a registered provider)
api_key	string	Yes	--	Provider API key (encrypted before storage)
model_id	string	Yes	--	Model identifier to use
extra_config	object	No	null	Provider-specific settings
is_active	boolean	No	true	Whether the provider is active

Response

201 Created -- Returns the ProviderResponse object.

If the type is not stt, llm, or tts, the API returns 400. If the name is not a registered provider for the given type, the API returns 400 with the list of available providers.

Update Provider

PUT /providers/{provider_id}

Update a provider's API key, model, configuration, or active status. Only include the fields you want to change.

Request Body

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

Request Fields

Field	Type	Required	Description
api_key	string	No	New API key (re-encrypted)
model_id	string	No	New model identifier
extra_config	object	No	Updated provider-specific settings
is_active	boolean	No	Enable or disable the provider

Response

200 OK -- Returns the updated ProviderResponse.

Delete Provider

DELETE /providers/{provider_id}

Permanently deletes a provider configuration. Any agents referencing this provider will need to be updated.

Response

204 No Content

List Available Models

GET /providers/{provider_id}/models

Fetches the list of available models for a saved provider using its stored API key. Queries the provider's API when possible, or returns a hardcoded list for providers that do not support model enumeration.

Response

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

Field	Type	Description
models	array[string]	Available model identifiers
source	string	api (fetched from provider), hardcoded (static list), or error (fetch failed)

Fetch Models (Ad-hoc)

POST /providers/models

Fetch available models without saving a provider configuration. Useful for testing an API key before creating a provider.

Request Body

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

Response

Same ProviderModelsResponse schema as above.

Test Provider

POST /providers/{provider_id}/test

Validates that a saved provider's API key and configuration are working correctly. Calls the provider's validate() method.

Response

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

Field	Type	Description
success	boolean	Whether validation passed
message	string	Human-readable result message

Returns 400 if the API key is invalid, or a response with success: false if validation fails for other reasons.