Audio API (TTS & STT)

The audio API offers speech synthesis (POST /v1/audio/speech) and transcription (POST /v1/audio/transcriptions) in the OpenAI format. You can keep using existing OpenAI audio clients: point baseURL at us and pick one of our voices. Speech is generated and recognised in EU data centres.

Both endpoints require an API key with the matching scope: speech for TTS, transcribe for STT (see Authentication → Permissions).

There are four engines for speech synthesis. You pick one per request through the OpenAI-standard model field (supertonic-3 / cosyvoice-3 / voxtral-mini-tts / qwen3-tts) or through provider. If you set neither, the server derives the engine from the voice, otherwise the default engine applies: Mistral since 26 September 2026 (EU endpoint, France), Supertonic before that. To keep using Supertonic, set provider: "supertonic" or model: "supertonic-3", or pick a Supertonic voice (M1–M5/F1–F5). If Mistral does not speak the language (from language or, with auto, detected from the text), Qwen takes over (e.g. ru, ja, ko, zh), otherwise Supertonic (e.g. tr, uk, pl, ro). X-Voice-Provider tells you which engine spoke.

The language counts are those of each model card. We have checked (round-trip transcription) mainly German, plus English for the catalogue voices and Russian for qwen. There is no measurement of our own for the other languages.

Transcription (STT) runs on Mistral Voxtral through the EU endpoint of Mistral AI (France). Alternatively, Whisper large-v3 transcribes with 99 languages (model=whisper-large-v3, see below); that model is self-operated on rented GPUs in EU data centres (and additionally in Iceland or Norway, EEA).

AI disclosure: synthetically generated speech must be labelled as AI content (EU AI Act Art. 50). WAV, FLAC, MP3 and Opus output carries metadata for this, CosyVoice clips also an inaudible watermark (details: AI labelling). Telling your listeners is up to your application. Supertonic weights are under OpenRAIL-M.

POST /v1/audio/speech — text-to-speech

Produces spoken audio from text. The response is the raw audio body with no JSON wrapper, just like OpenAI's.

curl https://sovrgpt.com/api/v1/audio/speech \
  -H "Authorization: Bearer $SOVR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "supertonic-3",
    "input": "Guten Tag <breath> willkommen bei SovrGPT.",
    "voice": "F3",
    "response_format": "wav"
  }' --output hello.wav

Request body

Response

200 with audio bytes. Headers:

Content-Type: audio/wav        (or audio/flac, audio/mpeg …)
X-Voice-Provider: supertonic   (or: cosyvoice / mistral / qwen)
X-Voice: bib-m-40              (catalogue slug that spoke — or: default)
X-Voice-Language: en           (Supertonic/Qwen only: the language that was spoken)
x-sovrgpt-model-served: voxtral-mini-tts   (the model that spoke)
x-sovrgpt-model-requested: tts-1           (only if `model` differs from it)

Unlike chat, embeddings and rerank, the audio endpoints will not start rejecting an unknown model value. Check x-sovrgpt-model-served if you expect a particular engine.

Errors come as {"error": {"message", "type", "code"}}; for language_not_supported the error object also carries the list supported. When the speech service itself fails (upstream_error, service not configured), message is a fixed sentence. Branch on type and code, not on the wording. For a support request, the time of the request is enough.

GET /v1/audio/voices — the voice catalogue

Which values voice accepts, and whether this organisation may select them. Answers for any valid key, no scope required, like GET /v1/models.

curl https://sovrgpt.com/api/v1/audio/voices -H "Authorization: Bearer $SOVR_KEY"

{
  "object": "list",
  "data": [
    {
      "object": "voice",
      "slug": "bib-m-40",
      "label": "Männlich, Anfang 40",
      "origin": "designed",
      "gender": "m",
      "age_group": "Anfang 40",
      "description": "Warm und rund, weicher Stimmansatz, ruhige Satzmelodie.",
      "primary_language": "de",
      "languages": ["de", "en", "fr", "es", "it", "pt", "nl", "hi", "ar"],
      "samples": { "de": "/api/voice/samples/bib-m-40?lang=de", "en": "/api/voice/samples/bib-m-40?lang=en" },
      "scope": "platform",
      "sample_url": null,
      "provider": "mistral",
      "model": "voxtral-mini-tts",
      "selectable": true,
      "available": true
    },
    {
      "object": "voice",
      "slug": "rooom-f-01",
      "label": "Beraterin (vorläufig)",
      "origin": "designed",
      "gender": "f",
      "age_group": "30–35",
      "primary_language": "de",
      "languages": ["de", "en", "fr", "es", "it", "pt", "ru", "ja", "ko", "zh"],
      "provider": "qwen",
      "model": "qwen3-tts",
      "selectable": true,
      "available": true,
      "status": "preliminary",
      "status_note": "vorläufig — die Hörfreigabe steht aus; Klang und Kennung können sich noch ändern."
    }
  ],
  "languages": ["de", "en", "fr", "es", "it", "pt", "nl", "hi", "ar"],
  "languages_by_provider": {
    "mistral": ["de", "en", "fr", "es", "it", "pt", "nl", "hi", "ar"],
    "supertonic": ["en", "ko", "ja", "ar", "bg", "cs", "da", "de", "el", "es", "…"],
    "cosyvoice": ["zh", "en", "ja", "ko", "de", "es", "fr", "it", "ru"],
    "qwen": ["de", "en", "fr", "es", "it", "pt", "ru", "ja", "ko", "zh"]
  },
  "access": { "selectable": true, "via": "tier", "tier": "pro", "hint": null }
}

(Shortened: data contains every catalogue voice plus the fixed voices of the engines, i.e. M1–M5/F1–F5 from Supertonic, de-thorsten from CosyVoice and the four rooom-* voices from Qwen.)

• provider / model: which engine speaks the voice. A catalogue voice pins mistral, a rooom-* voice pins qwen.
• selectable: whether this organisation may pick the voice. Catalogue voices depend on the plan (see access); the fixed engine voices do not.
• available: whether the engine is set up in this environment. It says nothing about whether a worker is running right now (cold start: see below).
• status: "preliminary": the voice is preliminary. The four rooom-* voices are still waiting for listening approval; until then their sound and identifier may change. For production use that needs a fixed voice, that is a reason to wait.
• languages stays the list of the Mistral voices for compatibility; languages_by_provider lists the languages per engine.
• origin: designed = generated from a written description, fictional (belongs to no person); preset = the provider's stock voice; cloned = from a recording.
• languages per voice: the languages of its engine according to the model card. For the catalogue voices these are the nine Mistral languages. The designed voices were designed for German. We checked German and English for the catalogue voices (round-trip transcription word for word, no onset click); in the other languages the provider states that a colouring of the source language remains audible.
• access.selectable: false means POST /v1/audio/speech answers 403 voice_not_in_plan for catalogue voices. via names the reason for access (tier from Starter, entitlement via the “Voices” entitlement).
• samples are public and play without a key (fixed sample sentence, MP3).
• scope: platform = available to every organisation with voice selection; org = a voice you designed yourself, visible to your organisation only. Org voices carry no public samples, because the sample route is reachable without signing in. Instead they carry a signed sample_url valid for one hour.

Example with a catalogue voice (provider is then redundant):

curl -X POST https://sovrgpt.com/api/v1/audio/speech   -H "Authorization: Bearer $SOVR_KEY" -H "Content-Type: application/json"   -d '{"input":"Hello, this is a designed voice speaking.","voice":"bib-f-35","response_format":"mp3"}'   -o hello.mp3

Design your own voice

Have a fictional voice generated from a description, stored as a reference clip and adopted into the catalogue. Every design endpoint needs the speech scope and a key whose creator is an owner or admin of the organisation. The exception is the options endpoint: like GET /v1/models, it only needs a valid key, and access.designable tells you whether this key may design.

Ordering

curl -X POST https://sovrgpt.com/api/v1/audio/voices/designs \
  -H "Authorization: Bearer $SOVR_KEY" -H "Content-Type: application/json" \
  -d '{
        "language": "en",
        "gender": "f",
        "age_years": 52,
        "timbre": "warm",
        "character": "calm",
        "tempo": "even",
        "use_case": "narration",
        "free_text": "slightly smoky, fundamental around 200 hertz",
        "label": "Narrator, calm",
        "slug": "narrator-calm",
        "auto_adopt": false
      }'

{
  "object": "voice_design",
  "id": "9f1c…",
  "status": "pending",
  "scope": "org",
  "target_hz": 203,
  "band_hz": [185, 255],
  "auto_adopt": false,
  "measurements": { "f0_hz": null, "in_band": null, "attempts_used": null, "seconds": null },
  "sample_url": null,
  "cost_micro_eur": 0,
  "voice_slug": null,
  "error": null
}

gender is required, plus one of age_years (16–90) or age_group. Everything else is optional. Whatever you leave out is drawn at random per job, so two identical orders can yield different voices. The valid trait ids come from design-options; an unknown id answers 400 invalid_request_error and names the allowed ones.

Professional fields: instruct replaces the generated description entirely (max. 2000 characters), target_hz pins the register (60–400).

Fetching

curl https://sovrgpt.com/api/v1/audio/voices/designs/9f1c… \
  -H "Authorization: Bearer $SOVR_KEY"

The call also drives the job: it asks the worker, downloads a finished clip and completes the job. Poll it every few seconds until status is no longer pending. A job that is not finished after 20 minutes is set to failed.

{
  "object": "voice_design",
  "id": "9f1c…",
  "status": "ready",
  "measurements": {
    "f0_hz": 208.4, "p25_hz": 196, "p75_hz": 221,
    "voiced_windows": 340, "in_band": true, "attempts_used": 2, "seconds": 19.5
  },
  "sample_url": "https://…signed… (valid for 1 h)",
  "duration_ms": 42000,
  "cost_micro_eur": 7583,
  "voice": null
}

in_band: false means none of the draws hit the ordered register and the best one was kept. That is not an error, but a good reason to listen before adopting.

States: pending → ready → adopted, plus discarded and failed.

Adopting

curl -X POST https://sovrgpt.com/api/v1/audio/voices/designs/9f1c…/adopt \
  -H "Authorization: Bearer $SOVR_KEY" -H "Content-Type: application/json" \
  -d '{"slug":"narrator-calm","label":"Narrator, calm"}'

Answers with the finished catalogue entry (scope: "org"). The voice is immediately available in GET /v1/audio/voices and as voice in POST /v1/audio/speech.

To do it in one go, set auto_adopt: true when ordering: the job then moves from ready straight to adopted without anyone having to hear the sample. That is the path for unattended integrations; the app deliberately does not offer it.

Proposal from a description

curl -X POST https://sovrgpt.com/api/v1/audio/voices/designs/suggest \
  -H "Authorization: Bearer $SOVR_KEY" -H "Content-Type: application/json" \
  -d '{"text":"calm, a bit older, like a narrator in an audiobook"}'

Returns trait ids, age_years, gender, a display name, a rationale and up to three hints. It is a proposal you can pass straight into POST …/designs or adjust first. The call designs nothing and starts no worker.

Limits and error codes

Per organisation 10 adopted voices and 3 designs running at once (the current values are in design-options.limits).

Billed is the pure synthesis time of the design (duration_ms), not the cold start. It shows as cost_micro_eur on the job and as a usage line (voice-design:qwen3-tts).

CosyVoice: German with emotion, tags and your own voice

For expressive German with emphasis, laughter, breathing and voice cloning, pick the cosyvoice provider. Full capabilities: Models → Voice.

Inline tags (directly inside input): [laughter], [breath], <laughter>…</laughter> (spoken while laughing), <strong>…</strong> (emphasis).

# German with tags and emphasis
curl https://sovrgpt.com/api/v1/audio/speech \
  -H "Authorization: Bearer $SOVR_KEY" -H "Content-Type: application/json" \
  -d '{
    "provider": "cosyvoice",
    "voice": "de-thorsten",
    "input": "Und dann [breath] öffnete ich die Tür. [laughter] Das war <strong>unglaublich</strong>."
  }' --output tags.wav

Emotion in natural language via emotion (or instruction):

curl https://sovrgpt.com/api/v1/audio/speech \
  -H "Authorization: Bearer $SOVR_KEY" -H "Content-Type: application/json" \
  -d '{
    "provider": "cosyvoice",
    "voice": "de-thorsten",
    "input": "Diese Zeiten sind für immer vorbei.",
    "emotion": "Sprich sehr traurig, leise und langsam."
  }' --output sad.wav

Your own voice (zero-shot cloning): pass a reference clip of 10–20 seconds as base64, plus its transcript as prompt_text for the best quality:

REF=$(base64 -w0 my_voice.wav)
curl https://sovrgpt.com/api/v1/audio/speech \
  -H "Authorization: Bearer $SOVR_KEY" -H "Content-Type: application/json" \
  -d "{
    \"provider\": \"cosyvoice\",
    \"input\": \"A new sentence, spoken in my cloned voice.\",
    \"reference_audio_b64\": \"$REF\",
    \"prompt_text\": \"<verbatim transcript of the reference clip>\"
  }" --output cloned.wav

Built-in voice: de-thorsten (German, male, calm; CC0). Your own voices at any time via reference_audio_b64 (zero-shot, no training).

Cold start: the CosyVoice GPU worker scales to zero. Warm it delivers in about 6 seconds; a cold worker can take minutes. You then get a 503 saying “warming up”; resend after about a minute. Mistral (the default) and Supertonic have no cold start.

Choosing the language

The default engine Mistral has no language parameter: the language follows the text. Supertonic and Qwen speak the language you name in language. Without it, German applies (English for voice: "default-en"); the text alone does not change that. With "language": "auto" we detect the language from the text (script and common function words). If detection is unsure, for example with very short or mixed text, German applies.

curl https://sovrgpt.com/api/v1/audio/speech \
  -H "Authorization: Bearer $SOVR_KEY" -H "Content-Type: application/json" \
  -d '{"model":"supertonic-3","voice":"F3","language":"fr","input":"Bonjour, je vous lis la réponse."}' \
  --output bonjour.wav

The response header X-Voice-Language tells you which language was spoken. A code the engine does not know is rejected (Supertonic 400, Qwen 422, each with the list supported), not silently replaced by German. Mistral and CosyVoice have no language parameter; they speak the language of the text.

Qwen3-TTS: our own voices without Mistral (preliminary)

With provider: "qwen" (or model: "qwen3-tts", or a rooom-* voice), Qwen3-TTS (0.6B, Apache 2.0) speaks. We run the model ourselves on rented GPUs in EU data centres (and additionally in Iceland or Norway, EEA); the text goes to no third-party speech service such as Mistral.

The voices are designed and fictional; they belong to no real person. Without voice, rooom-f-01 speaks.

curl https://sovrgpt.com/api/v1/audio/speech \
  -H "Authorization: Bearer $SOVR_KEY" -H "Content-Type: application/json" \
  -d '{"provider":"qwen","voice":"rooom-m-01","language":"en","input":"Good morning, here is your summary."}' \
  --output qwen.wav

• Languages: de en fr es it pt ru ja ko zh. Without language, de applies. Other codes yield 422 language_not_supported, Polish for example.
• Length: at most 2,000 characters per request, otherwise 400 text_too_long. Split longer texts into paragraphs.
• Output: always WAV, 24 kHz, mono, with AI labelling in the metadata. No watermark, no voice cloning (reference_audio_b64 yields 400), no emotion tags.
• Cold start: the worker scales to zero. We measured 50 s to the first sound when the image is already on the machine, and about ten minutes on the very first start on a new machine. We wait up to 240 s. If it takes longer you get 503; resend after about a minute. If all speech streams are taken you get 429 with Retry-After: 1.

POST /v1/audio/transcriptions — speech-to-text

Transcribes an uploaded audio file (multipart/form-data).

curl https://sovrgpt.com/api/v1/audio/transcriptions \
  -H "Authorization: Bearer $SOVR_KEY" \
  -F file=@recording.webm \
  -F language=de \
  -F response_format=json

Form fields

Large files: POST /v1/audio/uploads

The 4.5 MiB is a limit of our platform and cannot be raised in code. So you place the audio past our function: you fetch a signed address, upload straight to it, and at transcription time you only name the identifier.

# 1. Fetch a ticket — same key, same `transcribe` scope
curl -s -X POST https://sovrgpt.com/api/v1/audio/uploads \
  -H "Authorization: Bearer $SOVR_KEY" \
  -H "content-type: application/json" \
  -d '{"mime":"audio/ogg","size":18234012}'

{
  "upload_id": "0f1c…",
  "upload_url": "https://…/storage/v1/object/upload/sign/api-audio/…",
  "token": "…",
  "content_type": "audio/ogg",
  "max_bytes": 104857600
}

# 2. Upload the bytes directly — NOT to us
curl -s -X PUT "$upload_url" \
  -H "content-type: audio/ogg" \
  --data-binary @recording.ogg

# 3. Transcribe, with no file in the body
curl -s -X POST https://sovrgpt.com/api/v1/audio/transcriptions \
  -H "Authorization: Bearer $SOVR_KEY" \
  -H "content-type: application/json" \
  -d '{"upload_id":"0f1c…","language":"de","response_format":"verbose_json","timestamp_granularities":"segment"}'

Response

{ "text": "Hallo, dies ist ein Test." }

With response_format=verbose_json and timestamp_granularities:

{
  "text": "Die Bundeswehr braucht eine souveräne Plattform. Der letzte Satz ist genau der, den wir prüfen wollen.",
  "language": "de",
  "duration": 7,
  "segments": [
    { "text": "Die Bundeswehr braucht eine souveräne Plattform.", "start": 0.5, "end": 3.3, "speakerId": null },
    { "text": "Der letzte Satz ist genau der, den wir prüfen wollen.", "start": 3.6, "end": 6.9, "speakerId": null }
  ]
}

segments appears in the response only if timestamp_granularities was set; an empty field would be indistinguishable from “nothing recognised”. The timestamps always refer to the unformatted text. format_text is a second model pass with its own wording, and there are no timestamps for it. speakerId is currently always null.

Every successful response carries x-sovrgpt-model-served (voxtral-mini-transcribe or whisper-large-v3). If your model differs, for example whisper-1, it is echoed in x-sovrgpt-model-requested.

format_text — a transcript with structure

A raw transcript has punctuation and capitalisation, but no paragraphs, no lists and no blank line after the salutation. With format_text=1 a second pass therefore runs over a model with audio understanding, which adds that structure. Both passes start at the same time, so the response time is that of the slower one.

curl https://sovrgpt.com/api/v1/audio/transcriptions \
  -H "Authorization: Bearer $SOVR_KEY" \
  -F file=@dictation.webm \
  -F format_text=1 \
  -F response_format=verbose_json

{
  "text": "Sehr geehrte Frau Dr. Schmitt,\n\nvielen Dank …\n\n1. Die Übertragung …\n2. Die Antwortzeiten …\n\nMit freundlichen Grüßen\nMax Mustermann",
  "text_raw": "Sehr geehrte Frau Dr. Schmitt, vielen Dank … Erstens die Übertragung …",
  "language": null,
  "duration": 101,
  "formatting": { "applied": true, "verdict": "ok", "coverage": 0.996 }
}

The exact wording is protected. A model asked to format can also rephrase or shorten, and the result still looks flawless. So we check every formatted version against the raw transcript before returning it:

text_raw is always included when format_text=1, even if the formatting was applied. A client that depends on the literal text reads text_raw and ignores text. format_text is off by default; existing integrations get exactly the same bytes as before.

Whisper large-v3 — 99 languages, self-operated

With model=whisper-large-v3, Whisper large-v3 transcribes instead of Voxtral. The model is self-operated on rented GPUs in EU data centres (and additionally in Iceland or Norway, EEA); the audio goes to no external speech service.

curl https://sovrgpt.com/api/v1/audio/transcriptions \
  -H "Authorization: Bearer $SOVR_KEY" \
  -F model=whisper-large-v3 \
  -F file=@interview.ogg \
  -F response_format=vtt

• 99 languages plus Cantonese (yue). Without language, Whisper detects the language itself and verbose_json reports it in language; language=auto means the same. Region suffixes such as de-DE are cut to de, and spellings Whisper writes differently are mapped (nb/nb-NO → no, jv → jw, fil → tl, the legacy codes iw, in, ji → he, id, yi). An unknown code returns 400.
• Response formats: json, text, verbose_json, srt, vtt. With Whisper, verbose_json always contains segments in Whisper's shape (id, start, end, text, avg_logprob, no_speech_prob …); an empty field here really means “no speech detected”. timestamp_granularities=word adds words; both levels at once are allowed.
• duration is the end of the last recognised segment, not the length of the file. Trailing silence does not count. Billing uses this duration.
• context_bias becomes the prompt for Whisper when you send no prompt of your own.
• format_text is not available with Whisper (400). The formatting pass runs at a different provider; if you choose Whisper so the audio stays with the self-operated model, it must not be sent there without asking.
• The default stays Voxtral. Even model=whisper-1, which OpenAI clients often hard-code, goes to Voxtral.
• Large files via upload_id (up to 100 MiB): the worker then reads the audio itself through a short-lived address from our storage. The ticket is deleted afterwards as always.

SDK example (OpenAI client)

from openai import OpenAI

client = OpenAI(base_url="https://sovrgpt.com/api/v1", api_key=SOVR_KEY)

# Text-to-speech (Supertonic, fast)
client.audio.speech.create(
    model="supertonic-3", voice="F3", response_format="wav",
    input="Hallo Welt <sigh> das war ein langer Tag.",
).stream_to_file("hello.wav")

# Text-to-speech (CosyVoice, German + emotion)
# model="cosyvoice-3" picks the engine; emotion (a SovrGPT extension) via extra_body
client.audio.speech.create(
    model="cosyvoice-3", voice="de-thorsten", response_format="wav",
    input="Was für ein wunderbarer Tag!",
    extra_body={"emotion": "Sprich fröhlich und aufgeregt."},
).stream_to_file("happy.wav")

# Speech-to-text
with open("recording.webm", "rb") as f:
    tr = client.audio.transcriptions.create(
        model="voxtral-mini-transcribe", file=f, language="de",
    )
print(tr.text)

# Speech-to-text with Whisper large-v3 (99 languages, language is detected)
with open("interview.ogg", "rb") as f:
    tr = client.audio.transcriptions.create(
        model="whisper-large-v3", file=f, response_format="verbose_json",
    )
print(tr.language, tr.text)

In the chat

In the chat, speech works without the API: the microphone icon in the input field dictates (STT), and the speaker button on any assistant answer reads it aloud (TTS). Each user picks the voice under Settings → Voices (from Starter or via entitlement); samples under Voices. See also Models → Voice.

Answers are read aloud in the language of the answer: it is detected from the answer text (language: "auto"; code blocks and links do not count). If the text is too short or mixed for that, the interface language applies, otherwise German.

In the chat, the default voice (currently Mistral, Supertonic for other languages), a chosen catalogue voice or a chosen Supertonic voice reads aloud, all without a cold start. CosyVoice and Qwen3-TTS run on GPU workers that scale to zero, so they are only available through POST /v1/audio/speech.