Speech-to-text

5.1 Batch: POST /stt

multipart/form-data with field audio (≤ 25 MB, any common container: WAV, MP3, Ogg/Opus, FLAC, AAC, PCM16), optional lang (one code, several candidates or auto, see 5.3; default de-CH) and vocabulary (JSON array of up to 200 domain terms to bias recognition towards: names, products, place names).

curl -X POST https://api.suisse-speech.ch/v1/stt \
  -H "X-API-Key: $SUISSE_SPEECH_KEY" \
  -F audio=@call.wav -F lang=de-CH \
  -F 'vocabulary=["Rüegg","Bircher","Glasfaser"]'

{"text":"…","lang":"de-CH","words":[{"w":"Grüezi","start":0.12,"end":0.58,"conf":0.98}],"duration_s":3.4}

For recordings longer than a few minutes, submit a recognition job instead: it accepts up to 200 MB and runs at roughly a third of real time.

5.2 Realtime: GET /stt/stream (WebSocket)

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

{"type":"config","lang":"de-CH","vocabulary":["Bircher","Rüegg"]}
{"type":"audio.append","data":"<base64 PCM16 16 kHz mono>"}
{"type":"audio.end"}

Binary frames are accepted as raw PCM16 after config. The server replies with session.ready, then transcript.partial on a fixed 250 ms cadence, then transcript.final, then session.complete. Every transcript.partial and transcript.final carries lang, the language of that stretch of speech.

Send audio at real-time pace. Sending faster does not produce transcripts faster, and it will exhaust your budget for no benefit.

5.3 Multilingual recognition

lang takes one code, several candidates separated by commas, or auto. It works the same way on POST /stt, on /stt/stream and on recognition jobs.

With more than one candidate the spoken language is detected automatically, the transcript is written in that language, and every result reports it in lang. On the stream each transcript.partial and transcript.final carries the lang of that stretch of speech, so a change of language during a session is visible as it happens.

The reported value is always one of the candidates you gave. Two things follow:

• You never have to handle a language you did not list. Name only the languages you expect: fewer candidates give a steadier result on very short utterances.
• A candidate may carry a region or a dialect (fr-CH, de-CH-zurich) and is reported back exactly so.

Swiss German dialects and High German are both recognised under de-CH (or de) and both are written as Standard German, which is what downstream language understanding handles best. Recognition reports the language, not the dialect that was spoken: which variety to answer in is your choice (5.4). Two candidates that share a base language (de-CH,de) cannot be told apart; the one listed first is reported.

5.4 From recognition to synthesis: answering in the caller’s language

Both directions use the same codes, so the language a caller speaks is handed from one to the other unchanged:

1. Open recognition with your target locales as candidates: {"type":"config","lang":"de-CH-zurich,fr-CH,en"}
2. Read lang from transcript.final, for example "lang":"fr-CH".
3. Write your reply in that language and synthesise it with language set to the same value: {"type":"session.start","language":"fr-CH","voice":"anna", ...}

No mapping table and no server-side session is involved. Every request stands on its own, and the code carries everything synthesis needs, the dialect included. All voices speak every supported language, so one voice can serve the whole conversation and the persona stays the same when the language changes.

Choosing the variety you answer in:

• Swiss German: de-CH with a dialect, or the compact form de-CH-zurich. The reply may be written in Standard German; it is spoken in the dialect.
• High German: de-CH-hochdeutsch for Swiss High German, or de, de-DE, de-AT.
• Anything the catalogue does not list: describe it in style (Text-to-speech 3.6).

If the language is known before the conversation starts (a language menu, the customer record) pass that single code instead of a candidate list.