Provider params

Routing picks the provider; provider params tune what that provider does. There are two layers:

• Canonical fields (L1) - one cross-provider name, translated to each vendor's wire param by Speko.
• providerOptions (L2) - provider-scoped passthrough, validated against Speko's param registry. A provider's options apply only when that provider serves the request.

Where params are accepted

Each providerOptions param in the registry declares the surfaces it supports. Sending one on the wrong surface is rejected with unsupported_surface - for example Deepgram's streaming-only endpointing on /v1/transcribe. Canonical fields use the failover rules below; diarization currently has batch mappings only.

Canonical fields (L1)

Per-provider wire mapping:

diarization and wordTimestamps are batch-only. Either one makes the done frame carry words: an array of { text, start, end, confidence?, speaker? } with start/end in seconds from the start of the audio (multiply by 1000 for subtitle cue times). wordTimestamps is served by gemini-3.5-transcribe and by Deepgram's batch models (not Flux). Gemini cannot combine it (or diarization) with keywords, so the term list is dropped for that request, and Google caps timestamped audio at 30 minutes. Pin Gemini to be sure of it. A demote-class field excludes candidates that cannot serve it rather than selecting one that can, and automatic routing does not rank the pre-recorded Gemini row, so an unpinned request answers 422 no_capable_provider unless a Deepgram model is on the language's ladder. When Gemini fails, a pinned request falls back to Deepgram if Deepgram ranks for the language:

-H 'X-Speko-Stt-Options: {"wordTimestamps":true}' \
-H 'X-Speko-Constraints: {"allowedProviders":{"stt":["gemini:gemini-3.5-transcribe"]}}'

The Router needs no pin — its automatic routing filters candidates on the capability itself. Streaming speaker forwarding is not exposed yet. Speaker labels from diarization-capable providers are normalized to S0, S1, ... on word-level output, regardless of the vendor's native labeling.

Deepgram Flux models deliberately accept none of the canonical or provider-specific params in these tables.

providerOptions (L2)

{
  "providerOptions": {
    "deepgram": { "dictation": true },
    "elevenlabs": { "timestamps_granularity": "word" }
  }
}

• Keys are provider ids; each inner object is validated against the registry tables below.
• Unknown providers, unknown params, wrong types, invalid enum values, and numbers outside a strict 0-1 range return 400 invalid_provider_options with per-param details.
• Numbers outside a documented non-unit range pass through with an out_of_range warning - the provider decides.
• A provider's options apply only when that provider serves the request. On failover they never cross to the winning provider; the losing provider's dict is discarded.
• Options for a provider outside your allowedProviders pins produce a provider_not_pinned warning; they still apply if routing picks that provider.
• Spelling a canonical field inside providerOptions while also setting it at the top level (for example providerOptions.deepgram.diarize next to diarization, or voice_settings.speed next to speed) is rejected as canonical_collision - set one spelling.

STT params

Google and xAI expose only the canonical fields above. OpenAI and Cartesia expose no tunable STT params yet.

TTS params

voice_settings (ElevenLabs) properties:

Failover behavior

• Drop-class params are omitted for a candidate that cannot serve them. The request still runs; the omission is reported as a param_dropped warning and the param is absent from applied.
• Demote-class params (diarization) remove incapable candidates from the failover ladder before the first attempt, each reported as a candidate_excluded warning. If no candidate remains, the request fails with 422 { "error": "no_capable_provider", "code": "NO_CAPABLE_PROVIDER", "param": "diarization" } instead of silently running without the capability.

When a request carries any of the new fields, the response reports what actually applied:

• /v1/transcribe: the final done SSE event gains effectiveParams: { provider, model, applied, defaultsVersion }, plus warnings when non-empty.
• /v1/transcribe/stream: a metadata frame after ready carries the same object.
• /v1/synthesize: response headers X-Speko-Applied-Params (JSON array of param names) and X-Speko-Warnings (JSON array, capped at 2 KB).

Requests without any of the new fields get byte-identical responses to before these fields existed.

Workload defaults

workload: 'conversation' | 'transcription' | 'narration' applies per-provider defaults from the registry. Defaults are presence-keyed: no workload, no defaults. Explicit fields always override defaults. Responses echo defaultsVersion (currently 2026-08-06) so a registry change is visible.

A default only applies when the candidate's surface and model support the param. On /v1/synthesize, workload: "narration" additionally prefers a 24 kHz output ladder when the request sets no sampleRate and at least one candidate serves that rate.

Use-case vocabulary

Three vocabularies coexist on different surfaces:

Vertical profiles: customer-support, sales-outbound, healthcare, telephony-receptionist, voice-assistant, education-tutoring, restaurant-ordering, mental-health-coaching, legal-intake, financial-banking-ivr.

Guides: Batch transcription, Narration.