DEdeepl
VoiceAPI

Get Streaming URL

Changed on

Create a real-time voice session and return the WebSocket URL and ephemeral token used to stream audio. Session options such as languages, message format, and media types are fixed at creation time. Invalid options are rejected with HTTP 400 before a session is created.

post/v3/voice/realtime

Request

  • Base URL
    https://api.deepl.com
  • URL
    https://api.deepl.com/v3/voice/realtime
  • Auth
    API key in header Authorization

Headers

X-DeepL-Reporting-Tagstring

An optional custom reporting tag used to attribute this request's usage to a team, project, customer, or other category of your choosing. Values are limited to 100 characters. See How to use custom reporting tags for validation rules, naming guidance, and how to retrieve usage by tag.

Request body

message_format'json' | 'msgpack'

Message encoding format for WebSocket communication. Determines how messages are serialized and transmitted. Using json, messages are JSON-encoded and sent as TEXT WebSocket frames. All binary fields (such as audio data) are base64-encoded strings. Using msgpack, messages are MessagePack-encoded and sent as BINARY WebSocket frames. All binary fields (such as audio data) contain raw binary data.

For more details, see Message Encoding.

source_media_content_type'audio/auto' | 'audio/flac' | 'audio/mpeg' | 'audio/ogg' | 'audio/webm' | 'audio/x-matroska' | 'audio/ogg;codecs=flac' | 'audio/ogg;codecs=opus' | 'audio/pcm;encoding=alaw;rate=8000' | 'audio/pcm;encoding=ulaw;rate=8000' | 'audio/pcm;encoding=s16le;rate=8000' | 'audio/pcm;encoding=s16le;rate=16000' | 'audio/pcm;encoding=s16le;rate=44100' | 'audio/pcm;encoding=s16le;rate=48000' | 'audio/webm;codecs=opus' | 'audio/x-matroska;codecs=aac' | 'audio/x-matroska;codecs=flac' | 'audio/x-matroska;codecs=mp3' | 'audio/x-matroska;codecs=opus' required

The audio format for streaming, which specifies container, codec, and encoding parameters. See the table below for supported formats. If audio/auto is specified, the server will auto-detect the container and codec for all supported combinations, except PCM. That requires explicit encoding parameters. All formats need to be single channel audio.

Content TypeContainerCodec
audio/autoAuto-detect: FLAC / Matroska / MPEG / Ogg / WebMAuto-detect AAC / FLAC / MP3 / OPUS
audio/flacFLAC (flac)FLAC
audio/mpegMPEG (mp3/m4a)MP3
audio/oggOgg (ogg/oga)Auto-detect FLAC / OPUS
audio/webmWebM (webm)OPUS
audio/x-matroskaMatroska (mkv/mka)Auto-detect: AAC / FLAC / MP3 / OPUS
audio/ogg;codecs=flacOgg (ogg/oga)FLAC
audio/ogg;codecs=opusOgg (ogg/oga)OPUS
audio/pcm;encoding=alaw;rate=8000-PCM A-Law 8000 Hz (G.711)
audio/pcm;encoding=ulaw;rate=8000-PCM µ-Law 8000 Hz (G.711)
audio/pcm;encoding=s16le;rate=8000-PCM signed 16-bit little-endian 8000 Hz
audio/pcm;encoding=s16le;rate=16000-PCM signed 16-bit little-endian 16000 Hz
audio/pcm;encoding=s16le;rate=44100-PCM signed 16-bit little-endian 44100 Hz
audio/pcm;encoding=s16le;rate=48000-PCM signed 16-bit little-endian 48000 Hz
audio/webm;codecs=opusWebM (webm)OPUS
audio/x-matroska;codecs=aacMatroska (mkv/mka)AAC
audio/x-matroska;codecs=flacMatroska (mkv/mka)FLAC
audio/x-matroska;codecs=mp3Matroska (mkv/mka)MP3
audio/x-matroska;codecs=opusMatroska (mkv/mka)OPUS

We recommend the following bitrates as good tradeoff between quality and bandwidth:

  • AAC: 96 kbps
  • FLAC: 256 kbps (16000 Hz)
  • MP3: 128 kbps
  • OPUS: 32 kbps (recommendation for low bandwidth scenarios)
  • PCM: 256 kbps (16000 Hz, default recommendation)
source_language'ar' | 'bg' | 'bn' | 'ca' | 'cs' | 'da' | 'de' | 'el' | 'en' | 'es' | 'et' | 'fi' | 'fr' | 'ga' | 'gl' | 'he' | 'hi' | 'hr' | 'hu' | 'id' | 'it' | 'ja' | 'ko' | 'lt' | 'lv' | 'ms' | 'mt' | 'nb' | 'nl' | 'pl' | 'pt' | 'ro' | 'ru' | 'sk' | 'sl' | 'sv' | 'ta' | 'th' | 'tl' | 'tr' | 'uk' | 'vi' | 'zh'

The source language of the audio stream. It can be left empty or must be one of the supported Voice API source languages and comply with IETF BCP 47 language tags. Note: Some source transcription languages are provided through external service partners. See the supported languages table for details.

source_language_mode'auto' | 'fixed'

Controls how the source_language value is used.

  • auto: Treats source language as a hint; server can override
  • fixed: Treats source language as mandatory; server must use this language
target_languagesstring[]

List of target languages for translation. The stream will emit translations for each language. Language identifiers must comply with IETF BCP 47. See the supported languages table for details.

target_media_languagesstring[]

List of target languages for which to generate synthesized audio. Languages specified here will automatically be added to target_languages if not already present, ensuring you receive both text translation and audio synthesis for these languages. If omitted, only text transcription and translation will be provided (no audio synthesis). Language identifiers must comply with IETF BCP 47. Note: Some translated audio languages are provided through external service partners. See the supported languages table for details.

target_media_content_type'audio/flac' | 'video/mp2t;codecs=aac' | 'video/mp2t;codecs=opus' | 'audio/ogg' | 'audio/ogg;codecs=flac' | 'audio/ogg;codecs=opus' | 'audio/opus' | 'audio/pcm;encoding=alaw;rate=8000' | 'audio/pcm;encoding=ulaw;rate=8000' | 'audio/pcm;encoding=s16le;rate=16000' | 'audio/pcm;encoding=s16le;rate=24000' | 'audio/webm' | 'audio/webm;codecs=opus' | 'audio/x-matroska;codecs=aac' | 'audio/x-matroska;codecs=flac' | 'audio/x-matroska;codecs=opus'

The audio format for synthesized target media streaming. Specifies container, codec, and encoding parameters for the audio returned in target_media_chunk messages. If not specified, defaults to audio/webm;codecs=opus. Only applies when target_media_languages is specified.

Content TypeContainerCodec
audio/flacFLAC (flac)FLAC 24000 Hz
video/mp2t;codecs=aacMPEG Transport Stream (Audio only)AAC 70 kbit/s
video/mp2t;codecs=opusMPEG Transport Stream (Audio only)OPUS 32 kbit/s
audio/oggOgg (ogg/oga)OPUS 32 kbit/s
audio/ogg;codecs=flacOgg (ogg/oga)FLAC 24000 Hz
audio/ogg;codecs=opusOgg (ogg/oga)OPUS 32 kbit/s
audio/opus-OPUS 32 kbit/s
audio/pcm;encoding=alaw;rate=8000-PCM A-Law 8000 Hz (G.711)
audio/pcm;encoding=ulaw;rate=8000-PCM µ-Law 8000 Hz (G.711)
audio/pcm;encoding=s16le;rate=16000-PCM signed 16-bit little-endian 16000 Hz
audio/pcm;encoding=s16le;rate=24000-PCM signed 16-bit little-endian 24000 Hz
audio/webmWebM (webm)OPUS 32 kbit/s
audio/webm;codecs=opusWebM (webm)OPUS 32 kbit/s
audio/x-matroska;codecs=aacMatroska (mkv/mka)AAC 70 kbit/s
audio/x-matroska;codecs=flacMatroska (mkv/mka)FLAC 24000 Hz
audio/x-matroska;codecs=opusMatroska (mkv/mka)OPUS 32 kbit/s

We recommend the following formats as good tradeoffs between quality and bandwidth:

  • OPUS (WebM): 32 kbps, recommended for low bandwidth scenarios (default)
  • PCM 24kHz: 384 kbps, high quality
target_media_voice'male' | 'female' | 'match'

Target audio voice selection for synthesized speech. The default voice is language dependent. Use match for speaker match, which produces translated speech with a voice close to the speaker's voice. Speaker match is only available for target languages whose translated speech is provided by DeepL, not for languages provided through external service partners. See the supported languages table for details. Requesting match for a target language that does not support it is not an error: the session is created and that language's translated speech uses a preset voice instead.

spoken_terms_idstring uuid

(beta) The ID of a Spoken Terms collection used to inform transcription.

glossary_idstring

Specify the glossary to use for the target transcripts (translations). For new integrations we recommend the more general glossary_ids.

Cannot be used together with glossary_ids.

glossary_idsstring[]

Specify the glossaries to use for the target transcripts (translations), as an array of glossary IDs ordered by priority (highest first). Each glossary's matching terms are applied to the translation; where entries conflict, the higher-priority glossary wins. Unknown glossary IDs are ignored.

In realtime Voice, glossary terms are matched against the streaming source transcription, which affects how and when terms are applied. See Glossaries in realtime Voice.

Cannot be used together with glossary_id. Requests that exceed the session limit, contain duplicates, or combine glossary_ids with glossary_id are rejected with a 400 Bad Request before a session is created.

formality'default' | 'formal' | 'more' | 'informal' | 'less'

Sets whether the translated text should lean towards formal or informal language. Possible options are:

  • default - use the default formality for the target language
  • formal/more - for a more formal language
  • informal/less - for a more informal language

Example request

{
  "message_format": "json",
  "source_media_content_type": "audio/ogg;codecs=opus",
  "source_language": "en",
  "source_language_mode": "fixed",
  "target_languages": [
    "de",
    "fr",
    "es"
  ],
  "target_media_languages": [
    "de"
  ],
  "target_media_content_type": "audio/webm;codecs=opus",
  "target_media_voice": "female",
  "spoken_terms_id": "7c4f1080-cfe2-41d4-8269-0e6ec15a0354",
  "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
  "glossary_ids": [
    "def3a26b-3e84-45b3-84ae-0c0aaf3525f7"
  ],
  "formality": "formal"
}

Response

Successfully obtained streaming URL and token.

streaming_urlstring required

The WebSocket URL to use for establishing the stream connection.

tokenstring required

A unique ephemeral token for authentication with the streaming endpoint. Pass this as a query parameter when connecting to the streaming URL. This token is ephemeral and valid for a short time and one-time use only.

session_idstring

Internal use only. A unique identifier for the requested stream.

Example response

{
  "streaming_url": "wss://api.deepl.com/v3/voice/realtime/connect",
  "token": "VGhpcyBpcyBhIGZha2UgdG9rZW4K",
  "session_id": "4f911080-cfe2-41d4-8269-0e6ec15a0354"
}

Changes

  • c7c91cfac5c0Revision changes
    • info

      added the new optional header request parameter X-DeepL-Reporting-Tag

    • info

      added the new optional request property

    • info

      added the new ca enum value to the request property

    • info

      added the new ca enum value to the request property /

    • info

      added the new ca enum value to the request property /

    • info

      added the new es-419 enum value to the request property /

    • info

      added the new es-419 enum value to the request property /

    • info

      added the new fr-CA enum value to the request property /

    • info

      added the new fr-CA enum value to the request property /

    • info

      added the new fr-FR enum value to the request property /

    • info

      added the new fr-FR enum value to the request property /

    • info

      added the new gl enum value to the request property

    • info

      added the new gl enum value to the request property /

    • info

      added the new gl enum value to the request property /

    • info

      added the new he enum value to the request property /

    • info

      added the new hr enum value to the request property /

    • info

      added the new match enum value to the request property

    • info

      added the new sl enum value to the request property /

    • info

      added the new th enum value to the request property /

    • info

      added the new tl enum value to the request property /

    • info

      added the media type application/json for the response with the status

    • info

      added the media type application/json for the response with the status