Merge branch 'dvc-930-acl-2319-add-voice-tts-docu' into 'main'

[ACL-2319,DVC-930,DVC-1018,DVC-1109] Add doc for speech to speech feature

See merge request deepl/clapi-track/api-docs-mirror!231

Author: sj-dl

api-reference/openapi.yaml

@@ -3,7 +3,7 @@ info:
   title: DeepL API Documentation
   description: |-
     The DeepL API provides programmatic access to DeepL’s language AI technology.
-    
+
     Note: this OpenAPI spec is embedded into our API documentation and has shortened descriptions.
   termsOfService: https://www.deepl.com/pro-license
   contact:
@@ -2329,6 +2329,8 @@ paths:
               required:
                 - source_media_content_type
               properties:
+                message_format:
+                  $ref: '#/components/schemas/VoiceMessageFormat'
                 source_media_content_type:
                   $ref: '#/components/schemas/VoiceSourceMediaContentType'
                 source_language:
@@ -2337,8 +2339,12 @@ paths:
                   $ref: '#/components/schemas/VoiceSourceLanguageMode'
                 target_languages:
                   $ref: '#/components/schemas/VoiceTargetLanguages'
-                message_format:
-                  $ref: '#/components/schemas/VoiceMessageFormat'
+                target_media_languages:
+                  $ref: '#/components/schemas/VoiceTargetMediaLanguages'
+                target_media_content_type:
+                  $ref: '#/components/schemas/VoiceTargetMediaContentType'
+                target_media_voice:
+                  $ref: '#/components/schemas/VoiceTargetMediaVoice'
                 glossary_id:
                   $ref: '#/components/schemas/GlossaryId'
                 formality:
@@ -2362,6 +2368,39 @@ paths:
                   message_format: 'msgpack'
                   glossary_id: 'def3a26b-3e84-45b3-84ae-0c0aaf3525f7'
                   formality: 'formal'
+              with_tts:
+                summary: With translated audio (default format)
+                value:
+                  source_media_content_type: 'audio/ogg;codecs=opus'
+                  source_language: 'en'
+                  target_languages: ['de', 'fr', 'es']
+                  target_media_languages: ['de', 'fr']
+                  target_media_content_type: 'audio/webm;codecs=opus'
+                  target_media_voice: 'female'
+              with_tts_short_form:
+                summary: With translated audio using short-form MIME types
+                value:
+                  source_media_content_type: 'audio/webm'
+                  source_language: 'en'
+                  target_languages: ['de', 'es']
+                  target_media_languages: ['de', 'es']
+                  target_media_content_type: 'audio/ogg'
+              with_tts_high_quality:
+                summary: With translated audio using high-quality PCM
+                value:
+                  source_media_content_type: 'audio/pcm;encoding=s16le;rate=16000'
+                  source_language: 'en'
+                  target_languages: ['de']
+                  target_media_languages: ['de']
+                  target_media_content_type: 'audio/pcm;encoding=s16le;rate=24000'
+              with_tts_raw_opus:
+                summary: With translated audio using raw Opus
+                value:
+                  source_media_content_type: 'audio/pcm;encoding=s16le;rate=16000'
+                  source_language: 'en'
+                  target_languages: ['de']
+                  target_media_languages: ['de']
+                  target_media_content_type: 'audio/opus'
       responses:
         200:
           description: Successfully obtained streaming URL and token.
@@ -4697,12 +4736,21 @@ components:
         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](/api-reference/voice#message-encoding).
       type: string
       enum:
         - json
         - msgpack
       default: json
       example: json
+    VoiceTargetMediaVoice:
+      description: (EAP) Target audio voice selection for synthesized speech. The default voice is language dependent.
+      type: string
+      enum:
+      - male
+      - female
+      example: female
     VoiceSourceMediaContentType:
       type: string
       description: "
@@ -4723,10 +4771,10 @@ components:
         | `audio/ogg;codecs=opus`               | Ogg (ogg/oga)                                     | OPUS                                      |\n
         | `audio/pcm;encoding=alaw;rate=8000`   | -                                                 | PCM A-Law 8000 Hz (G.711)                 |\n
         | `audio/pcm;encoding=ulaw;rate=8000`   | -                                                 | PCM µ-Law 8000 Hz (G.711)                 |\n
-        | `audio/pcm;encoding=s16le;rate=8000`  | -                                                 | PCM signed 16-bit little-endian, 8000 Hz  |\n
-        | `audio/pcm;encoding=s16le;rate=16000` | -                                                 | PCM signed 16-bit little-endian, 16000 Hz |\n
-        | `audio/pcm;encoding=s16le;rate=44100` | -                                                 | PCM signed 16-bit little-endian, 44100 Hz |\n
-        | `audio/pcm;encoding=s16le;rate=48000` | -                                                 | PCM signed 16-bit little-endian, 48000 Hz |\n
+        | `audio/pcm;encoding=s16le;rate=8000`  | -                                                 | PCM signed 16-bit little-endian 8000 Hz   |\n
+        | `audio/pcm;encoding=s16le;rate=16000` | -                                                 | PCM signed 16-bit little-endian 16000 Hz  |\n
+        | `audio/pcm;encoding=s16le;rate=44100` | -                                                 | PCM signed 16-bit little-endian 44100 Hz  |\n
+        | `audio/pcm;encoding=s16le;rate=48000` | -                                                 | PCM signed 16-bit little-endian 48000 Hz  |\n
         | `audio/webm;codecs=opus`              | WebM (webm)                                       | OPUS                                      |\n
         | `audio/x-matroska;codecs=aac`         | Matroska (mkv/mka)                                | AAC                                       |\n
         | `audio/x-matroska;codecs=flac`        | Matroska (mkv/mka)                                | FLAC                                      |\n
@@ -4768,24 +4816,47 @@ components:
       description: >
         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](/api-reference/voice#show-supported-languages) for details.
       enum:
-        - de
+        - ar
+        - bg
+        - bn
         - cs
+        - da
+        - de
+        - el
         - en
         - es
+        - et
+        - fi
         - fr
+        - ga
+        - he
+        - hr
+        - hu
         - id
         - it
         - ja
         - ko
+        - lt
+        - lv
+        - mt
+        - nb
         - nl
         - pl
         - pt
         - ro
         - ru
+        - sk
+        - sl
         - sv
+        - th
+        - tl
         - tr
         - uk
+        - vi
         - zh
       default:
       example: en
@@ -4805,11 +4876,13 @@ components:
       description: >
         List of target languages for translation. The stream will emit translations for each language.
         The maximum allowed target languages per stream is 5. Language identifiers must comply with IETF BCP 47.
+        See the [supported languages table](/api-reference/voice#show-supported-languages) for details.
       items:
         type: string
         enum:
           - ar
           - bg
+          - bn
           - cs
           - da
           - de
@@ -4821,14 +4894,17 @@ components:
           - et
           - fi
           - fr
+          - ga
           - he
+          - hr
           - hu
           - id
           - it
           - ja
           - ko
           - lt
           - lv
+          - mt
           - nb
           - nl
           - pl
@@ -4841,6 +4917,7 @@ components:
           - sl
           - sv
           - th
+          - tl
           - tr
           - uk
           - vi
@@ -4851,6 +4928,106 @@ components:
       maxItems: 5
       default: []
       example: ["de", "fr", "es"]
+    VoiceTargetMediaLanguages:
+      type: array
+      description: >
+        (EAP) 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).
+        The maximum allowed target media languages per stream is 5.
+        Language identifiers must comply with IETF BCP 47.
+
+        Note: Some translated audio languages are provided through external service partners.
+        See the [supported languages table](/api-reference/voice#show-supported-languages) for details.
+      items:
+        type: string
+        enum:
+          - ar
+          - bg
+          - cs
+          - da
+          - de
+          - el
+          - en
+          - en-GB
+          - en-US
+          - es
+          - fi
+          - fr
+          - hu
+          - id
+          - it
+          - ja
+          - ko
+          - nb
+          - nl
+          - pl
+          - pt
+          - pt-BR
+          - pt-PT
+          - ro
+          - ru
+          - sk
+          - sv
+          - tr
+          - uk
+          - vi
+          - zh
+          - zh-HANS
+          - zh-HANT
+      maxItems: 5
+      default: []
+      example: ["de", "en-GB"]
+    VoiceTargetMediaContentType:
+      type: string
+      description: "
+        (EAP) The audio format for synthesized target media streaming.\n
+        Specifies container, codec, and encoding parameters for the audio returned in target_media_chunk messages.\n
+        If not specified, defaults to audio/webm;codecs=opus.\n
+        Only applies when target_media_languages is specified.\n
+        \n
+        | Content Type | Container | Codec |\n
+        | :--- | :--- | :--- |\n
+        | `audio/flac` | FLAC (flac) | FLAC 24000 Hz |\n
+        | `video/mp2t;codecs=aac` | MPEG Transport Stream (Audio only) | AAC 70 kbit/s |\n
+        | `video/mp2t;codecs=opus` | MPEG Transport Stream (Audio only) | OPUS 32 kbit/s |\n
+        | `audio/ogg` | Ogg (ogg/oga) | OPUS 32 kbit/s |\n
+        | `audio/ogg;codecs=flac` | Ogg (ogg/oga) | FLAC 24000 Hz |\n
+        | `audio/ogg;codecs=opus` | Ogg (ogg/oga) | OPUS 32 kbit/s |\n
+        | `audio/opus` | - | OPUS 32 kbit/s |\n
+        | `audio/pcm;encoding=alaw;rate=8000` | - | PCM A-Law 8000 Hz (G.711) |\n
+        | `audio/pcm;encoding=ulaw;rate=8000` | - | PCM µ-Law 8000 Hz (G.711) |\n
+        | `audio/pcm;encoding=s16le;rate=16000` | - | PCM signed 16-bit little-endian 16000 Hz |\n
+        | `audio/pcm;encoding=s16le;rate=24000` | - | PCM signed 16-bit little-endian 24000 Hz |\n
+        | `audio/webm` | WebM (webm) | OPUS 32 kbit/s  |\n
+        | `audio/webm;codecs=opus` | WebM (webm) | OPUS 32 kbit/s |\n
+        | `audio/x-matroska;codecs=aac` | Matroska (mkv/mka) | AAC 70 kbit/s |\n
+        | `audio/x-matroska;codecs=flac` | Matroska (mkv/mka) | FLAC 24000 Hz |\n
+        | `audio/x-matroska;codecs=opus` | Matroska (mkv/mka) | OPUS 32 kbit/s |\n
+        \n
+        We recommend the following formats as good tradeoffs between quality and bandwidth:\n
+        - OPUS (WebM): 32 kbps, recommended for low bandwidth scenarios (default)\n
+        - PCM 24kHz: 384 kbps, high quality"
+      enum:
+        - 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
+      default: audio/webm;codecs=opus
+      example: audio/webm;codecs=opus
     VoiceStreamingResponse:
       type: object
       required: