Providers and routing

How Speechbase chooses an upstream TTS provider, and how BYOK and Managed Routing differ.

A synthesis request always resolves to one upstream provider, one provider model, and one voice. Speechbase gives you a consistent API for making that choice, then handles provider credentials, dispatch, errors, logs, and response formatting around it.

Model strings

Inline requests choose a provider with a model string:

{
  "mode": "inline",
  "model": "openai/gpt-4o-mini-tts",
  "voice": "alloy",
  "text": "Hello from Speechbase."
}

The prefix before / is the provider ID. The part after / is the provider's model ID. The gateway validates the provider, loads the matching SDK integration, and dispatches the request with your configured provider access.

Saved voices resolve the same way, but the provider and model are stored on the voice row:

{
  "mode": "voice",
  "voiceId": "01940f8a-2dc1-7000-9b6c-fc6dd8a0a4d2",
  "text": "This request uses the voice's provider and model."
}

Provider state

GET /v1/audio/providers returns the provider catalog plus your workspace state:

Field	Meaning
`enabled`	Whether requests are allowed to route to this provider. Toggle this in the dashboard under Speech Gateway -> Model Providers.
`byok`	Whether a provider key is stored for this provider. BYOK requests fail if this is false.
`models`	Prefixed model strings you can pass to synthesis and conversation endpoints.

Use provider enablement as a deployment control. If a provider is temporarily disabled, calls that target it fail before any upstream request is made.

Provider access models

BYOK

BYOK means "bring your own key." You store an upstream provider credential in Speechbase, and the gateway uses it when your request targets that provider.

Provider charges go to your account at the upstream provider. Speechbase stores only encrypted key material plus metadata such as last four characters and updated time. See Bring your own provider keys for the lifecycle.

Managed Routing

Managed Routing is the provider-access model where Speechbase manages provider relationships, billing, and quotas for your workspace. You still call the same Speechbase endpoints and select models the same way, but Speechbase owns the upstream provider relationship instead of requiring you to maintain a provider API key.

Managed Routing is useful when you want one Speechbase bill, predictable spend controls, and fewer provider accounts to manage. Availability depends on your plan and workspace enablement. If Managed Routing is not enabled for the provider you target, use BYOK or contact Speechbase to enable it.

Multi-provider conversations

Conversation requests can mix providers turn by turn:

{
  "turns": [
    {
      "model": "elevenlabs/eleven_v3",
      "voice": "EXAV...",
      "text": "I'm on ElevenLabs."
    },
    {
      "model": "openai/gpt-4o-mini-tts",
      "voice": "alloy",
      "text": "I'm on OpenAI."
    }
  ],
  "gapMs": 400,
  "volumeDbfs": -16,
  "output": "mp3"
}

Speechbase validates provider access for every referenced provider before dispatching any turn. If one provider is missing, disabled, or unavailable, the request fails as a whole rather than returning a partially stitched file.

Common routing failures

Error	What to check
`unknown_provider`	The model prefix is not one of the provider IDs returned by `GET /v1/audio/providers`.
`no_api_key`	The provider is not configured for BYOK in your workspace, and Managed Routing is not available for that request.
`provider_disabled`	The provider is connected but disabled in Speech Gateway -> Model Providers.
`provider_unavailable`	The upstream provider returned an error or could not be reached after gateway retries.

See Errors for the full response shapes.