API reference

https://api.suisse-speech.ch/v1/tts

Send the complete text, receive the complete audio.

By default the response body is the audio itself, with the media type of the requested format and the metadata in X-Suisse-* headers. Set output: "json" (or send Accept: application/json) to receive a JSON envelope with base64 audio instead.

Two speech models are available:

• studio (default) — Our premier expressive engine. Natural prosody, nuanced delivery, and native support for regional Swiss German dialect translation and nuances. Recommended for production announcements, IVR greetings, audio content, and high-fidelity speech.
• swift — Low-latency engine optimized for real-time conversational streaming, telephone interactions, and instant responses.

language selects the language, dialect the regional variety within it. Swiss German (de-CH) is dialect-aware:

• standard: supra-regional Swiss German (default).
• zurich: Zurich dialect (Züritüütsch).
• bern: Bernese dialect (Bärndütsch).
• basel: Basel dialect (Baaseldütsch).
• luzern: Lucerne dialect (Lozärnerdütsch). Both models render the text into the dialect - its own words and forms, not an accent - so the text may be written in Standard German. swift does it in real time on the stream; studio does it with the highest fidelity and is the one to use for prepared audio. The compact form language: "de-CH-zurich" is accepted as an alternative to the two fields.

Regional varieties and accents

The catalogue has two levels. language is a code that may carry a region, and a regional standard variety is its own code: it-CH, fr-CA, en-GB, en-IN, de-AT. dialect is a variety inside one language: de-CH + stgallen, fr-CH + geneve, en-GB + scottish. The compact form <language>-<dialect> (de-CH-stgallen) is accepted wherever a language code is, by recognition too.

Switzerland: Swiss German in its regional dialects and as Swiss High German (de-CH + hochdeutsch, spoken word for word), Swiss French with the accents of the Romandie, and Swiss Italian (it-CH). Swiss German dialects are rendered into the dialect; every other variety keeps the words exactly as written and changes only pronunciation, melody and rhythm.

GET /capabilities is the list. Every language and dialect there carries a status: verified is measured in production, supported is rendered on a best-effort basis and no quality figure is published for it.

Following the language of a conversation

Recognition reports the language it detected in lang, in the same codes this endpoint accepts as language, the compact dialect form included. A client that lists its target locales as recognition candidates (lang = de-CH-zurich,fr-CH,en) receives exactly one of them back and can pass it here unchanged. No mapping table and no server-side session is involved: every request stands on its own. The reply text may be written in Standard German; for de-CH it is spoken in the chosen dialect. For High German use de-CH-hochdeutsch (Swiss High German) or de.

style is a free-text delivery prompt (up to 600 characters) — e.g. "freundlich und herzlich", "ruhig und geduldig, kurze Pausen nach jedem Satz", or "professionell und sachlich". It steers how the text is spoken, never what is spoken: the supplied text is always rendered verbatim.

A text value whose first element is <speak> is parsed as markup. Each construct is realised for real rather than passed on as a hint:

say-as with digits or telephone speaks Swiss numbers the way our phone agents do: dialect digit words and 3-3-2-2 grouping, so +41 31 533 22 02 in Bernese becomes "null drüü eis, füf drüü drüü, zwöi zwöi, null zwöi".

Elements that are not supported are rejected by name with an explanation in error.detail, never silently ignored. <audio> and <phoneme> are refused deliberately; use <sub alias> to respell a word. Call GET /capabilities for the authoritative list.

Billed in produced audio seconds, measured to the second, with no minimum per request.

Request body · application/json · SynthesisRequest

Responses

wss://api.suisse-speech.ch/v1/tts/stream

Open a socket, push text as it becomes available, receive audio while the rest of the text is still being written. Lower time-to-first-audio than batch, and the right mode when the text comes from a live source.

Authenticate with the X-API-Key request header, or — from a browser, which cannot set handshake headers — with the subprotocol field: Sec-WebSocket-Protocol: suisse.v1, key.<api key>.

{"type":"session.start","model":"swift","voice":"anna","language":"de-CH","dialect":"zurich",
 "speed":1.0,"style":"freundlich","format":"pcm16","sample_rate_hz":24000}
{"type":"text.append","text":"Grüezi. "}
{"type":"text.flush"}
{"type":"session.end"}

Add "transport":"binary" to session.start to receive audio as raw binary WebSocket frames instead of base64 inside JSON — a third fewer bytes and no decode step. Control frames stay JSON, so a binary frame is always audio, in order, in the encoding session.ready names. The default is json, so existing clients are unaffected.

Text is synthesised segment by segment at sentence boundaries. Send text.flush to force a partial segment out without ending the session. A text.append whose content is a complete <speak> document is expanded into passages immediately, so markup works in this mode too.

{"type":"session.ready","request_id":"...","voice":"anna","language":"de-CH",
 "dialect":"zurich","encoding":"pcm16","sample_rate_hz":24000,"frame_bytes":4096}
{"type":"audio.chunk","seq":1,"encoding":"pcm16","sample_rate_hz":24000,"data":"<base64>"}
{"type":"segment.done","characters":42,"duration_seconds":2.31,"cache":"miss"}
{"type":"mark","name":"after_ref","offset_seconds":7.15}
{"type":"session.complete","duration_seconds":7.94,"frames":48,"cache":{"hits":0,"misses":3}}
{"type":"error","error":{"code":"tts.unavailable","message":"...","request_id":"..."}}

Audio frames are a fixed frame_bytes in size apart from the final one. Concatenate the decoded data values in seq order to reconstruct the stream.

Responses

https://api.suisse-speech.ch/v1/tts/voices

The voice catalogue on its own, for clients that only need to populate a picker. A subset of GET /capabilities.

Responses

https://api.suisse-speech.ch/v1/tts/prewarm

On this service synthesised audio is processed in memory and not stored, so prewarming stores nothing: every phrase comes back skipped, and nothing is synthesised or billed. The endpoint stays for compatibility.

Needs a live key: a sandbox key never reaches the engine, so there would be nothing to warm.

Request body · application/json

Responses

https://api.suisse-speech.ch/v1/stt

Sync transcription for short audio (≤ 25 MB, ≤ 5 min). Pass audio as multipart/form-data with field audio. Optional fields: lang (default de-CH), vocabulary (JSON array of up to 200 strings to bias recognition).

Multilingual recognition

lang takes one language code, several candidates separated by commas (de-CH,fr-CH,en), or auto (short for de-CH,fr-CH,it,en). With more than one candidate the spoken language is detected automatically, the transcript is written in that language, and the result reports it in lang. The reported value is always one of the candidates given, and is accepted unchanged as language by POST /tts and /tts/stream. Name only the languages you expect: fewer candidates means a steadier result on short utterances.

A candidate may carry a region or a dialect (fr-CH, de-CH-zurich) and is reported back exactly so, which lets the choice of dialect travel with the code. Recognition reports the language, not the dialect that was spoken.

Swiss German dialects and Standard German are both recognised under de-CH and are written in Standard German.

Request body · multipart/form-data

Responses

wss://api.suisse-speech.ch/v1/stt/stream

WebSocket endpoint at wss://api.suisse-speech.ch/api/v1/stt/stream. Upgrade with the X-API-Key header (or ?api_key=sv_... query param).

{"type":"config","lang":"de-CH","vocabulary":["..."]}     // first message
{"type":"audio.append","data":"<base64 PCM16 16kHz mono>"} // chunks
{"type":"audio.end"}                                       // signal end

Binary frames are also accepted as raw PCM16 audio after config.

{"type":"session.ready","request_id":"..."}
{"type":"transcript.partial","text":"...","words":[...],"lang":"de-CH","duration_s":1.2}
{"type":"transcript.final","text":"...","words":[...],"lang":"de-CH","duration_s":3.4}
{"type":"session.complete","request_id":"..."}
{"type":"error","code":"stt.upstream_unavailable","message":"...","request_id":"..."}

Partial events are emitted on a fixed 250 ms cadence.

Multilingual recognition

lang in config takes one code, comma-separated candidates ("de-CH,fr-CH,en") or "auto", exactly as on POST /stt. Every transcript.partial and transcript.final then carries the language detected for that stretch of speech in lang, so a change of language during a session is visible as it happens.

Responses

https://api.suisse-speech.ch/v1/jobs

Parameters

Responses

https://api.suisse-speech.ch/v1/jobs

For text long enough that holding a connection open for the whole synthesis is the wrong shape. Acknowledged in milliseconds; the audio is collected later from /jobs/{id}/audio.

Everything is validated at submission, so a bad voice or malformed markup is a 400 here rather than a failure discovered later.

Results are kept for 48 hours. Up to 200 jobs may be queued per key. Jobs queue behind interactive traffic and are metered identically.

Request body · application/json

Responses

https://api.suisse-speech.ch/v1/jobs/{id}

Parameters

Responses

https://api.suisse-speech.ch/v1/jobs/{id}/audio

Parameters

Responses

https://api.suisse-speech.ch/v1/capabilities

Runtime discovery. Returns every voice, language, dialect, audio format, parameter range and error code the service accepts, plus the calling key's own quota for the current day.

Read this instead of hard-coding values: a new voice or language appears here without any client change.

Responses

https://api.suisse-speech.ch/v1/usage

Read from the billing ledger, not from the rate limiter's expiring counters, so these are the same numbers an invoice is built from, in the same unit. A customer billed by the second is entitled to reconcile continuously rather than at month end.

Sandbox traffic is reported separately and is never billed.

Parameters

Responses

Runtime description of the whole service. Generated from the same catalogues the request handlers validate against, so it cannot drift from the implementation.