diff --git a/api-reference/jobs-voice-translate/reference.mdx b/api-reference/jobs-voice-translate/reference.mdx index ae8e97f0..a0eeb223 100644 --- a/api-reference/jobs-voice-translate/reference.mdx +++ b/api-reference/jobs-voice-translate/reference.mdx @@ -46,7 +46,7 @@ Source audio over 3 hours is rejected, even if the file is under 1 GB. For longe ## Supported Languages -Source and target languages match the [real-time Voice API](/docs/voice/supported-languages-formats-and-limits#supported-languages). `source_language` is optional; if omitted, the language is detected automatically. +Source and target languages match the [real-time Voice API](/docs/voice/supported-voice-languages). `source_language` is optional; if omitted, the language is detected automatically. ## Supported Output Formats diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 7286755e..c2827fbc 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -45,6 +45,10 @@ "name": "CorrectText", "description": "The `correct` endpoint fixes spelling and grammar errors without broader rephrasing. Use it when you want\na minimal-change correction pass rather than the broader rewriting performed by `rephrase`." }, + { + "name": "ManageSpokenTerms", + "description": "The *Spoken Terms* functions allow you to create, inspect, edit and delete Spoken Terms collections.\nSpoken Terms improve speech recognition in the Voice API: they ensure specific words and phrases,\nsuch as company names, acronyms, and product names, are transcribed correctly. A collection contains\none or more term lists, each holding terms for a single language, and is applied to a voice session\nvia the `spoken_terms_id` parameter." + }, { "name": "ManageMultilingualGlossaries", "description": "The *glossary* functions allow you to create, inspect, edit and delete glossaries.\nGlossaries created with the glossary function can be used in translate requests by specifying the\n`glossary_id` parameter. A glossary contains (several) dictionaries.\nA dictionary is a mapping of source phrases to target phrases for a single language pair.\nIf you encounter issues, please let us know at support@DeepL.com.\n\nCurrently you can create glossaries with any of the languages DeepL supports (with the exception of Thai).\n\nThe maximum size limit for a glossary is 10 MiB = 10485760 bytes and each source/target text,\nas well as the name of the glossary, is limited to 1024 UTF-8 bytes.\nA total of 1000 glossaries are allowed per account.\n\nWhen creating a dictionary with target language `EN`, `PT`, or `ZH`, it's not necessary to specify a variant\n(e.g. `EN-US`, `EN-GB`, `PT-PT`, `PT-BR`, or `ZH-HANS`).\nDictionaries with target language `EN` can be used in translations with either English variant.\nSimilarly `PT`, and `ZH` dictionaries can be used in translations with their corresponding variants.\n(When you provide the ID of a glossary to a translation, the appropriate dictionary is automatically applied. Currently glossaries can not yet be used with source language detection.)\n\nGlossaries created via the DeepL API are now unified with glossaries created via the DeepL website and DeepL apps.\nPlease only use the v3 glossary API in conjunction with multilingual or edited glossaries from the website." @@ -3358,7 +3362,7 @@ ], "summary": "Create Spoken Terms collection", "operationId": "createSpokenTerms", - "description": "Create a new Spoken Terms collection with one or more term lists. Each term list contains terms for a single language.", + "description": "Create a new Spoken Terms collection with one or more term lists. Each term list contains terms for a single language. The number of collections per account is limited by your plan.", "requestBody": { "required": true, "content": { @@ -8351,7 +8355,7 @@ "example": "en" }, "entries": { - "description": "Newline-separated list of terms. Maximum 300 characters total.", + "description": "Newline-separated list of terms, one term per line. Maximum 300 characters total.\n\nTerms are case-sensitive. Each term must be non-empty, must not contain C0 or C1 control characters (such as tabs or newlines within a term), and must not have leading or trailing whitespace. Duplicate terms within a list are not allowed (comparison is case-sensitive).\n", "type": "string", "maxLength": 300, "example": "DeepL\nAPI\nwebhook" @@ -8389,7 +8393,7 @@ "example": "en" }, "entries": { - "description": "Newline-separated list of terms. Maximum 300 characters total.", + "description": "Newline-separated list of terms, one term per line. Maximum 300 characters total.\n\nTerms are case-sensitive. Each term must be non-empty, must not contain C0 or C1 control characters (such as tabs or newlines within a term), and must not have leading or trailing whitespace. Duplicate terms within a list are not allowed (comparison is case-sensitive).\n", "type": "string", "maxLength": 300, "example": "DeepL\nAPI\nwebhook\nintegration" diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index cd743746..c31301c8 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -48,6 +48,13 @@ tags: description: |- The `correct` endpoint fixes spelling and grammar errors without broader rephrasing. Use it when you want a minimal-change correction pass rather than the broader rewriting performed by `rephrase`. +- name: ManageSpokenTerms + description: |- + The *Spoken Terms* functions allow you to create, inspect, edit and delete Spoken Terms collections. + Spoken Terms improve speech recognition in the Voice API: they ensure specific words and phrases, + such as company names, acronyms, and product names, are transcribed correctly. A collection contains + one or more term lists, each holding terms for a single language, and is applied to a voice session + via the `spoken_terms_id` parameter. - name: ManageMultilingualGlossaries description: |- The *glossary* functions allow you to create, inspect, edit and delete glossaries. @@ -2370,7 +2377,7 @@ paths: - ManageSpokenTerms summary: Create Spoken Terms collection operationId: createSpokenTerms - description: Create a new Spoken Terms collection with one or more term lists. Each term list contains terms for a single language. + description: Create a new Spoken Terms collection with one or more term lists. Each term list contains terms for a single language. The number of collections per account is limited by your plan. requestBody: required: true content: @@ -5950,7 +5957,10 @@ components: type: string example: en entries: - description: Newline-separated list of terms. Maximum 300 characters total. + description: | + Newline-separated list of terms, one term per line. Maximum 300 characters total. + + Terms are case-sensitive. Each term must be non-empty, must not contain C0 or C1 control characters (such as tabs or newlines within a term), and must not have leading or trailing whitespace. Duplicate terms within a list are not allowed (comparison is case-sensitive). type: string maxLength: 300 example: "DeepL\nAPI\nwebhook" @@ -5978,7 +5988,10 @@ components: type: string example: en entries: - description: Newline-separated list of terms. Maximum 300 characters total. + description: | + Newline-separated list of terms, one term per line. Maximum 300 characters total. + + Terms are case-sensitive. Each term must be non-empty, must not contain C0 or C1 control characters (such as tabs or newlines within a term), and must not have leading or trailing whitespace. Duplicate terms within a list are not allowed (comparison is case-sensitive). type: string maxLength: 300 example: "DeepL\nAPI\nwebhook\nintegration" diff --git a/api-reference/spoken-terms.mdx b/api-reference/spoken-terms.mdx deleted file mode 100644 index 43230a2f..00000000 --- a/api-reference/spoken-terms.mdx +++ /dev/null @@ -1,547 +0,0 @@ ---- -title: "Spoken Terms" -public: true -sidebarTitle: "Overview" -description: "Manage and use DeepL Spoken Terms" ---- - - - Spoken Terms are available for Voice API and select API Pro plans. Check your [plan limits](https://www.deepl.com/en/pro#api) to see if Spoken Terms are included. - - -## Overview - -The `spoken-terms` endpoints let you manage [DeepL Spoken Terms](https://support.deepl.com/hc/en-us/articles/27381969228956-About-spoken-terms) for voice translation. Spoken Terms are monolingual collections that ensure specific words or phrases are recognized correctly within a single language during speech recognition. A Spoken Terms collection contains one or more term lists, with each term list containing terms for a single language. - -## Creating Spoken Terms - -### Format - -Spoken Terms use a simple newline-separated format. Each line contains one term: - -``` -DeepL -API -webhook -``` - -Terms are case-sensitive and should not contain tabs or other control characters. - -### Create Spoken Terms collection - -`POST /v3/spoken-terms` - -To create a Spoken Terms collection, each request can optionally contain one or more term lists. Each term list contains terms for a single language. - -This example creates a Spoken Terms collection with English technical terms: - - - - The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. - - ```sh Example request: create spoken terms - curl -X POST 'https://api.deepl.com/v3/spoken-terms' \ - --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \ - --header 'Content-Type: application/json' \ - --data '{ - "name": "Technical Terms", - "term_lists": [ - { - "lang": "en", - "entries": "DeepL\nAPI\nwebhook" - } - ] - }' - ``` - - ```json Example response - { - "spoken_terms_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7", - "name": "Technical Terms", - "term_lists": [ - { - "lang": "en", - "entry_count": 3 - } - ], - "creation_time": "2025-08-03T14:16:18.329Z" - } - ``` - - - The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. - - ```http Example request: create spoken terms - POST /v3/spoken-terms HTTP/2 - Host: api.deepl.com - Authorization: DeepL-Auth-Key [yourAuthKey] - User-Agent: YourApp/1.2.3 - Content-Length: 1234 - Content-Type: application/json - - { - "name": "Technical Terms", - "term_lists": [ - { - "lang": "en", - "entries": "DeepL\nAPI\nwebhook" - } - ] - } - ``` - - - -## Using Spoken Terms - -To use Spoken Terms with the [Voice API](/api-reference/voice#customization), include the `spoken_terms_id` parameter in your voice session request. The specified terms will be recognized correctly during speech recognition for the specified language. - -## Retrieving Spoken Terms - -### List all Spoken Terms collections - -`GET /v3/spoken-terms` - -Use this endpoint to list all your Spoken Terms collections, basic information about each collection's term lists, and each collection's name and creation time. The response will not include the actual terms. - - - - The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. - - ```sh Example request: list spoken terms - curl -X GET 'https://api.deepl.com/v3/spoken-terms' \ - --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' - ``` - - ```json Example response - { - "spoken_terms": [ - { - "spoken_terms_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7", - "name": "Technical Terms", - "term_lists": [ - { - "lang": "en", - "entry_count": 3 - } - ], - "creation_time": "2025-08-03T14:16:18.329Z" - } - ] - } - ``` - - - The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. - - ```http Example request: list all spoken terms - GET /v3/spoken-terms HTTP/2 - Host: api.deepl.com - Authorization: DeepL-Auth-Key [yourAuthKey] - User-Agent: YourApp/1.2.3 - ``` - - ```json Example response - { - "spoken_terms": [ - { - "spoken_terms_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7", - "name": "Technical Terms", - "term_lists": [ - { - "lang": "en", - "entry_count": 3 - } - ], - "creation_time": "2025-08-03T14:16:18.329Z" - } - ] - } - ``` - - - -### Get Spoken Terms collection metadata - -`GET /v3/spoken-terms/{spoken_terms_id}` - -Use this endpoint to retrieve basic information about a Spoken Terms collection's term lists, plus the collection's name and creation time. - - - - The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. - - ```sh Example request: retrieve spoken terms details - curl -X GET 'https://api.deepl.com/v3/spoken-terms/{spoken_terms_id}' \ - --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' - ``` - - ```json Example response - { - "spoken_terms_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7", - "name": "Technical Terms", - "term_lists": [ - { - "lang": "en", - "entry_count": 3 - } - ], - "creation_time": "2025-08-03T14:16:18.329Z" - } - ``` - - - The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. - - ```http Example request: retrieve spoken terms details - GET /v3/spoken-terms/{spoken_terms_id} HTTP/2 - Host: api.deepl.com - Authorization: DeepL-Auth-Key [yourAuthKey] - User-Agent: YourApp/1.2.3 - ``` - - ```json Example response - { - "spoken_terms_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7", - "name": "Technical Terms", - "term_lists": [ - { - "lang": "en", - "entry_count": 3 - } - ], - "creation_time": "2025-08-03T14:16:18.329Z" - } - ``` - - - -### Get Spoken Terms entries - -`GET /v3/spoken-terms/{spoken_terms_id}/entries?lang={language}` - -Use this endpoint to retrieve the terms for a specific language from a Spoken Terms collection. - - - - The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. - - ```sh Example request: get spoken terms entries - curl -X GET 'https://api.deepl.com/v3/spoken-terms/{spoken_terms_id}/entries?lang=en' \ - --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' - ``` - - ```json Example response - { - "lang": "en", - "entries": "DeepL\nAPI\nwebhook" - } - ``` - - - The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. - - ```http Example request: get spoken terms entries - GET /v3/spoken-terms/{spoken_terms_id}/entries?lang=en HTTP/2 - Host: api.deepl.com - Authorization: DeepL-Auth-Key [yourAuthKey] - User-Agent: YourApp/1.2.3 - ``` - - ```json Example response - { - "lang": "en", - "entries": "DeepL\nAPI\nwebhook" - } - ``` - - - -## Editing Spoken Terms - -### Replace or create a term list - -`PUT /v3/spoken-terms/{spoken_terms_id}/term-lists` - -The `PUT` method creates a new term list in the collection, or replaces an existing one for the specified language. If the collection has no term list for the given language, add it with the entries provided. If a term list already exists for that language, replace it. - -Use this method to add a new language to your Spoken Terms collection or to completely replace the terms for an existing language. To merge terms with an existing list, use the `PATCH` method. - - - - The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. - - ```sh Example request: replace a term list - curl -X PUT 'https://api.deepl.com/v3/spoken-terms/{spoken_terms_id}/term-lists' \ - --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \ - --header 'Content-Type: application/json' \ - --data '{ - "lang": "en", - "entries": "DeepL\nAPI\nwebhook\nintegration" - }' - ``` - - ```json Example response - { - "lang": "en", - "entry_count": 4 - } - ``` - - - The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. - - ```http Example request: replace a term list - PUT /v3/spoken-terms/{spoken_terms_id}/term-lists HTTP/2 - Host: api.deepl.com - Authorization: DeepL-Auth-Key [yourAuthKey] - User-Agent: YourApp/1.2.3 - Content-Length: 210 - Content-Type: application/json - - {"lang": "en","entries": "DeepL\nAPI\nwebhook\nintegration"} - ``` - - ```json Example response - { - "lang": "en", - "entry_count": 4 - } - ``` - - - -### Update metadata or merge entries - -`PATCH /v3/spoken-terms/{spoken_terms_id}` - -While the `PUT` method operates on a single term list, `PATCH` affects an element of the entire Spoken Terms collection. This could be metadata like the collection's name, or a term list for a particular language. - -This method returns the collection's name and metadata about each of its term lists. - -This example changes a Spoken Terms collection's name: - - - - The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. - - ```sh Example request: update collection name - curl -X PATCH 'https://api.deepl.com/v3/spoken-terms/{spoken_terms_id}' \ - --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \ - --header 'Content-Type: application/json' \ - --data '{ - "name": "Updated Technical Terms" - }' - ``` - - ```json Example response - { - "spoken_terms_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7", - "name": "Updated Technical Terms", - "term_lists": [ - { - "lang": "en", - "entry_count": 3 - } - ], - "creation_time": "2025-08-03T14:16:18.329Z" - } - ``` - - - The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. - - ```http Example request: update collection name - PATCH /v3/spoken-terms/{spoken_terms_id} HTTP/2 - Host: api.deepl.com - Authorization: DeepL-Auth-Key [yourAuthKey] - User-Agent: YourApp/1.2.3 - Content-Length: 147 - Content-Type: application/json - - {"name": "Updated Technical Terms"} - ``` - - ```json Example response - { - "spoken_terms_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7", - "name": "Updated Technical Terms", - "term_lists": [ - { - "lang": "en", - "entry_count": 3 - } - ], - "creation_time": "2025-08-03T14:16:18.329Z" - } - ``` - - - -You can also use `PATCH` to merge new terms into an existing term list. If the collection already has a term list for the specified language, the new entries will be merged with the existing list. - -This example adds new terms to the English term list: - - - - The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. - - ```sh Example request: merge terms - curl -X PATCH 'https://api.deepl.com/v3/spoken-terms/{spoken_terms_id}' \ - --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \ - --header 'Content-Type: application/json' \ - --data '{ - "term_lists": [ - { - "lang": "en", - "entries": "authentication\nendpoint" - } - ] - }' - ``` - - ```json Example response - { - "spoken_terms_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7", - "name": "Technical Terms", - "term_lists": [ - { - "lang": "en", - "entry_count": 5 - } - ], - "creation_time": "2025-08-03T14:16:18.329Z" - } - ``` - - - The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. - - ```http Example request: merge terms - PATCH /v3/spoken-terms/{spoken_terms_id} HTTP/2 - Host: api.deepl.com - Authorization: DeepL-Auth-Key [yourAuthKey] - User-Agent: YourApp/1.2.3 - Content-Length: 147 - Content-Type: application/json - - {"term_lists": [{"lang": "en","entries": "authentication\nendpoint"}]} - ``` - - ```json Example response - { - "spoken_terms_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7", - "name": "Technical Terms", - "term_lists": [ - { - "lang": "en", - "entry_count": 5 - } - ], - "creation_time": "2025-08-03T14:16:18.329Z" - } - ``` - - - -## Deleting Spoken Terms - -### Delete a Spoken Terms collection - -`DELETE /v3/spoken-terms/{spoken_terms_id}` - -This method deletes the specified Spoken Terms collection in its entirety. - - - - The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. - - ```sh Example request: delete spoken terms - curl -X DELETE 'https://api.deepl.com/v3/spoken-terms/{spoken_terms_id}' \ - --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' - ``` - - ```text Example response - 204 No Content - ``` - - - The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. - - ```http Example request: delete spoken terms - DELETE /v3/spoken-terms/{spoken_terms_id} HTTP/2 - Host: api.deepl.com - Authorization: DeepL-Auth-Key [yourAuthKey] - User-Agent: YourApp/1.2.3 - ``` - - ```text Example response - 204 No Content - ``` - - - -### Delete a term list - -`DELETE /v3/spoken-terms/{spoken_terms_id}/term-lists?lang={language}` - -Use this method to delete a term list for a specific language from the Spoken Terms collection. - - - - The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. - - ```sh Example request: delete a term list - curl -X DELETE 'https://api.deepl.com/v3/spoken-terms/{spoken_terms_id}/term-lists?lang=en' \ - --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' - ``` - - ```text Example response - 204 No Content - ``` - - - The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. - - ```http Example request: delete a term list - DELETE /v3/spoken-terms/{spoken_terms_id}/term-lists?lang=en HTTP/2 - Host: api.deepl.com - Authorization: DeepL-Auth-Key [yourAuthKey] - User-Agent: YourApp/1.2.3 - ``` - - ```text Example response - 204 No Content - ``` - - - -## Notes on usage - -### Languages supported - -Spoken Terms are available for all [DeepL Voice languages](https://support.deepl.com/hc/en-us/articles/26625846174364-DeepL-Voice-languages). Visit the Voice languages page for the complete list of supported languages and their availability. - -### Comparison with glossaries - -| Feature | Glossaries | Spoken Terms | -| ------- | ---------- | ------------ | -| **Purpose** | Translate specific terms between languages | Ensure recognition of specific terms within a language | -| **Direction** | Bidirectional (en→de, de→en) | Monolingual (en→en) | -| **Format** | TSV with source and target columns | Single-column, newline-separated | -| **Entry structure** | `source_term\ttarget_term` | `term` | - -## Restrictions - -### Size - -Each term list has a limit of 300 characters per language. The total number of Spoken Terms collections you can create is limited by your plan. - -The name of the collection can contain up to 1024 UTF-8 bytes. Names using only ASCII characters can be up to 1024 characters long; names with multi-byte characters hold fewer. - -### Content - -- Duplicate terms within a list are not allowed (case-sensitive). -- Terms must not be empty. -- Terms must not contain C0 or C1 control characters (including tabs `\t` or newlines `\n`). -- Terms must not contain leading or trailing whitespace. diff --git a/docs.json b/docs.json index d239fdba..6ab5aa0b 100644 --- a/docs.json +++ b/docs.json @@ -148,7 +148,8 @@ "docs/voice/real-time-voice-quickstart", "docs/voice/understanding-voice-sessions", "docs/voice/message-encoding", - "docs/voice/supported-languages-formats-and-limits" + "docs/voice/supported-voice-languages", + "docs/voice/voice-api-requirements" ] }, { @@ -172,6 +173,13 @@ "docs/customize/custom-instructions" ] }, + { + "group": "Spoken Terms", + "pages": [ + "docs/customize/improving-transcription-with-spoken-terms", + "docs/customize/spoken-terms-requirements" + ] + }, { "group": "Translation Memories", "pages": [ @@ -259,7 +267,6 @@ { "group": "Spoken Terms", "pages": [ - "api-reference/spoken-terms", "api-reference/spoken-terms/create-spoken-terms-collection", "api-reference/spoken-terms/list-all-spoken-terms", "api-reference/spoken-terms/retrieve-spoken-terms-details", @@ -721,6 +728,14 @@ "source": "/api-reference/translation-memory", "destination": "/docs/customize/using-translation-memories" }, + { + "source": "/api-reference/spoken-terms", + "destination": "/api-reference/spoken-terms/create-spoken-terms-collection" + }, + { + "source": "/docs/voice/supported-languages-formats-and-limits", + "destination": "/docs/voice/supported-voice-languages" + }, { "source": "/docs/best-practices/working-with-context", "destination": "/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter" diff --git a/docs/customize/improving-transcription-with-spoken-terms.mdx b/docs/customize/improving-transcription-with-spoken-terms.mdx new file mode 100644 index 00000000..f5c6b3e7 --- /dev/null +++ b/docs/customize/improving-transcription-with-spoken-terms.mdx @@ -0,0 +1,140 @@ +--- +title: "Improving Transcription with Spoken Terms" +description: "Keep company names, acronyms, and product terminology transcribed correctly in Voice API sessions by creating and maintaining a Spoken Terms collection." +covers: [Spoken Terms] +public: true +--- + +In Voice API sessions, Spoken Terms ensure that the vocabulary that matters to you, such as company names, acronyms, product names, and people's names, is transcribed with the exact spelling you choose. You provide the words, and speech recognition uses your spelling whenever they're spoken. Unlike [glossaries](/docs/customize/managing-glossaries), Spoken Terms are monolingual. They affect how speech is recognized, not how the recognized text is translated. + +This guide shows you how to set up Spoken Terms via the API and keep them current as your vocabulary grows. You can also manage them in [DeepL Home](https://www.deepl.com/en/voice/spoken-terms). + + +Spoken Terms are available on all plans that include the DeepL Voice API. The number of collections you can create depends on your [plan](https://www.deepl.com/en/pro#api). + + +## Collect domain-specific terms + +Review your calls for domain- and company-specific words you want transcribed with complete accuracy. Collect them in a **term list**: the terms, written exactly as you want them to appear in your transcripts (terms are case-sensitive). In the next step, you'll send this list to the DeepL API. + +```text +DeepL +API +webhook +``` + +Each term list holds at most 300 characters in total (see [Spoken Terms Requirements](/docs/customize/spoken-terms-requirements) for all size and content rules), so spend the budget on the terms that matter most rather than your full vocabulary. + +## Create a collection + +Term lists are stored in a **Spoken Terms collection**, which can hold one term list for each language. Create a collection with [`POST /v3/spoken-terms`](/api-reference/spoken-terms/create-spoken-terms-collection): + +```sh Example request +curl -X POST https://api.deepl.com/v3/spoken-terms \ + --header "Authorization: DeepL-Auth-Key $API_KEY" \ + --header "Content-Type: application/json" \ + --data '{ + "name": "Technical Terms", + "term_lists": [ + { + "lang": "en", + "entries": "DeepL\nAPI\nwebhook" + } + ] +}' +``` + +```json Example response +{ + "spoken_terms_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7", + "name": "Technical Terms", + "term_lists": [ + { + "lang": "en", + "entry_count": 3 + } + ], + "creation_time": "2025-08-03T14:16:18.329Z" +} +``` + +Store the `spoken_terms_id`; every voice session that should use these terms passes it. + +## Start a voice session with your terms + +Include the `spoken_terms_id` when you [create a voice session](/api-reference/voice/request-session). The terms for the session's source language are then recognized correctly in the transcription: + +```sh Example request +curl -X POST https://api.deepl.com/v3/voice/realtime \ + --header "Authorization: DeepL-Auth-Key $API_KEY" \ + --header "Content-Type: application/json" \ + --data '{ + "source_media_content_type": "audio/pcm; encoding=s16le; rate=16000", + "source_language": "en", + "target_languages": ["de"], + "spoken_terms_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7" +}' +``` + +See the [Real-Time Voice Quickstart](/docs/voice/real-time-voice-quickstart) for an example of the full Voice API session flow. + +To also control how your terms are **translated**, pass a `glossary_id` in the same session. Spoken Terms control how speech is recognized, and glossaries control how it's translated. + +Spoken Terms are available for all [DeepL Voice languages](https://support.deepl.com/hc/en-us/articles/26625846174364-DeepL-Voice-languages). To check a language programmatically, call [`GET /v3/languages?resource=voice`](/docs/languages/using-the-languages-api) and look for the `spoken_terms` feature key on the source language. + +## Add terms as your vocabulary grows + +To add terms without resending the existing ones, [`PATCH` the collection](/api-reference/spoken-terms/edit-spoken-terms-details); entries you pass for a language are merged into its existing term list: + +```sh Example request +curl -X PATCH https://api.deepl.com/v3/spoken-terms/def3a26b-3e84-45b3-84ae-0c0aaf3525f7 \ + --header "Authorization: DeepL-Auth-Key $API_KEY" \ + --header "Content-Type: application/json" \ + --data '{ + "term_lists": [ + { + "lang": "en", + "entries": "authentication\nendpoint" + } + ] +}' +``` + +```json Example response +{ + "spoken_terms_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7", + "name": "Technical Terms", + "term_lists": [ + { + "lang": "en", + "entry_count": 5 + } + ], + "creation_time": "2025-08-03T14:16:18.329Z" +} +``` + +Running sessions aren't affected; the updated terms apply to sessions started after the change. + +## Replace a language's terms + +To rebuild a language's term list from scratch, for example from an updated product catalog, [`PUT` the term list](/api-reference/spoken-terms/replace-or-create-term-list) with the new entries. Unlike `PATCH`, which adds to the existing list, `PUT` replaces the list entirely (or creates it, if the language is new to the collection): + +```sh Example request +curl -X PUT https://api.deepl.com/v3/spoken-terms/def3a26b-3e84-45b3-84ae-0c0aaf3525f7/term-lists \ + --header "Authorization: DeepL-Auth-Key $API_KEY" \ + --header "Content-Type: application/json" \ + --data '{ + "lang": "en", + "entries": "DeepL\nAPI\nwebhook\nintegration" +}' +``` + +```json Example response +{ + "lang": "en", + "entry_count": 4 +} +``` + +See the [Spoken Terms reference](/api-reference/spoken-terms/create-spoken-terms-collection) for full details on managing collections. Size and content rules are collected in [Spoken Terms Requirements](/docs/customize/spoken-terms-requirements). diff --git a/docs/customize/overview.mdx b/docs/customize/overview.mdx index d052ee53..9964c7e5 100644 --- a/docs/customize/overview.mdx +++ b/docs/customize/overview.mdx @@ -5,7 +5,9 @@ description: "Tailor DeepL translations to your domain with glossaries, style ru public: true --- -DeepL's customization features let you control terminology, style, and consistency across your translations. They complement each other, and you can combine them in a single request: +DeepL's customization features let you control terminology, style, and consistency across your translations. + +## What each feature does | Feature | What it controls | How it's applied | | :---- | :---- | :---- | @@ -13,19 +15,17 @@ DeepL's customization features let you control terminology, style, and consisten | [Style rules](/docs/customize/using-style-rules) | Formatting conventions (dates, numbers, punctuation) plus stored custom instructions | Stored on your account; passed per request via `style_id` | | [Custom instructions](/docs/customize/custom-instructions) | Tone, phrasing, and domain-specific behavior via natural-language directives | Inline per request via `custom_instructions`, or stored in a style rule list | | [Translation memories](/docs/customize/using-translation-memories) | Reuse of your previously approved translations for matching segments | Stored on your account; passed per request via `translation_memory_id` | +| [Spoken terms](/docs/customize/improving-transcription-with-spoken-terms) | Recognition of specific terms during Voice API speech transcription | Stored on your account; passed per voice session via `spoken_terms_id` | -All of these work with both [text translation](/docs/translate/translate-text-quickstart) and [document translation](/docs/translate/translate-documents-quickstart), and with all `model_type` values. +Glossaries, style rules, custom instructions, and translation memories work with both [text translation](/docs/translate/translate-text-quickstart) and [document translation](/docs/translate/translate-documents-quickstart), support all `model_type` values, and can be combined in a single request. Spoken terms apply to [Voice API](/docs/voice/overview) sessions, where they can be combined with glossaries. Glossaries and style rules are unique to each of DeepL's global data centers and are not shared between them. Clients using [regional endpoints](/docs/getting-started/regional-endpoints) can't access glossaries or style rules created in the UI at this time. -## Start here +## Feature guides - - A hands-on tutorial: build a glossary and apply it to keep customer-facing terminology consistent. - Create, edit, retrieve, and delete glossaries with the v3 endpoints, and use them in translations. @@ -38,8 +38,8 @@ Glossaries and style rules are unique to each of DeepL's global data centers and Retrieve your translation memories and control the matching threshold in translation requests. - - Create customizations with root language codes and apply them to variants like pt-BR or fr-CA. + + Keep company terms, acronyms, and names transcribed correctly in Voice API sessions. diff --git a/docs/customize/spoken-terms-requirements.mdx b/docs/customize/spoken-terms-requirements.mdx new file mode 100644 index 00000000..3b4cfa6b --- /dev/null +++ b/docs/customize/spoken-terms-requirements.mdx @@ -0,0 +1,27 @@ +--- +title: "Spoken Terms Requirements" +description: "Size limits and content rules for Spoken Terms collections and term lists." +public: true +--- + +## Size limits + +| Item | Limit | +| :---- | :---- | +| Characters per term list | 300 total | +| Collection name | 1024 UTF-8 bytes | +| Collections per account | Limited by your [plan](https://www.deepl.com/en/pro#api) | + +Names using only ASCII characters can be up to 1024 characters long; names with multi-byte characters hold fewer. + +## Content rules + +- Terms are case-sensitive +- Duplicate terms within a list are not allowed (comparison is case-sensitive) +- Terms must not be empty +- Terms must not contain C0 or C1 control characters (including tabs `\t` or newlines `\n` within a term) +- Terms must not contain leading or trailing whitespace + +## Availability + +Spoken Terms are available on all plans that include the DeepL Voice API, for all [DeepL Voice languages](https://support.deepl.com/hc/en-us/articles/26625846174364-DeepL-Voice-languages). To check a language programmatically, call [`GET /v3/languages?resource=voice`](/api-reference/languages/retrieve-languages-by-resource) and look for the `spoken_terms` feature key on the source language. diff --git a/docs/resources/roadmap-and-release-notes.mdx b/docs/resources/roadmap-and-release-notes.mdx index 5f926913..5d82f3b7 100644 --- a/docs/resources/roadmap-and-release-notes.mdx +++ b/docs/resources/roadmap-and-release-notes.mdx @@ -22,7 +22,7 @@ rss: true ## July 17 - Voice API Speech Output Generally Available - **Speech-to-speech** (translated speech output) moves out of closed beta and is now **generally available**. -- See [understanding voice sessions](/docs/voice/understanding-voice-sessions#translated-speech) for how translated speech works and the [supported languages table](/docs/voice/supported-languages-formats-and-limits#supported-languages) for language availability. +- See [understanding voice sessions](/docs/voice/understanding-voice-sessions#translated-speech) for how translated speech works and the [supported languages table](/docs/voice/supported-voice-languages) for language availability. ## July 16 - Combined Status Page - DeepL now publishes a single [status page](https://status.deepl.com) covering all services, with a dedicated [API view](https://status.deepl.com/?tab=api) for real-time API status and incidents. @@ -41,12 +41,12 @@ rss: true ## July 2 - New Voice API Languages: Hindi, Malay, and Tamil - The Voice API now supports `hi` (Hindi), `ms` (Malay), and `ta` (Tamil) in beta. Translation is provided by DeepL; transcription and translated speech are provided by external service partners. - These languages are marked `"external": true` in the [`GET /v3/languages?resource=voice`](/docs/languages/using-the-languages-api) response. Because they are beta and external, call with `include=beta&include=external` to see them. -- See the [supported languages table](/docs/voice/supported-languages-formats-and-limits#supported-languages) for the full list. +- See the [supported languages table](/docs/voice/supported-voice-languages) for the full list. ## June 29 - Spoken Terms API Management -- New [`/v3/spoken-terms`](/api-reference/spoken-terms) endpoints provide full API management for Spoken Terms collections, which improve transcription accuracy for company-specific terminology, acronyms, and proper names in the Voice API. +- New [`/v3/spoken-terms`](/docs/customize/improving-transcription-with-spoken-terms) endpoints provide full API management for Spoken Terms collections, which improve transcription accuracy for company-specific terminology, acronyms, and proper names in the Voice API. - Create, list, retrieve, update, and delete Spoken Terms collections programmatically. Each collection contains one or more term lists, with each term list holding terms for a single language. - Key endpoints: - [`POST /v3/spoken-terms`](/api-reference/spoken-terms/create-spoken-terms-collection) - Create a new collection with term lists diff --git a/docs/voice/overview.mdx b/docs/voice/overview.mdx index 935d7bfe..6b94a9b9 100644 --- a/docs/voice/overview.mdx +++ b/docs/voice/overview.mdx @@ -29,8 +29,11 @@ The DeepL Voice API transcribes and translates spoken audio in real time over a Choose between JSON and MessagePack for WebSocket messages. - - Check language availability, supported audio codecs and containers, and session limits. + + Check transcription, translation, and translated speech availability per language. + + + Check supported audio codecs and containers, chunk sizes, and session limits. Full request, message, and response schemas for the Voice API endpoints. @@ -41,7 +44,7 @@ The DeepL Voice API transcribes and translates spoken audio in real time over a Two optional features let you tailor transcription and translation to your domain: -* beta **Spoken terms**: improve transcription of frequently used terms such as company-specific terminology, acronyms, product names, and team member names. Manage them in [DeepL Home](https://www.deepl.com/en/voice/spoken-terms); management via API is coming soon. +* beta **Spoken terms**: improve transcription of frequently used terms such as company-specific terminology, acronyms, product names, and team member names. Manage them in [DeepL Home](https://www.deepl.com/en/voice/spoken-terms) or via the API; see [Improving Transcription with Spoken Terms](/docs/customize/improving-transcription-with-spoken-terms). * **Glossaries**: enforce specific translations for terms in the target language. Manage them in [DeepL Home](https://www.deepl.com/en/glossary) or programmatically with the [Glossaries API](/docs/customize/managing-glossaries). ## Code examples diff --git a/docs/voice/real-time-voice-quickstart.mdx b/docs/voice/real-time-voice-quickstart.mdx index cd2f2387..5b75ecb1 100644 --- a/docs/voice/real-time-voice-quickstart.mdx +++ b/docs/voice/real-time-voice-quickstart.mdx @@ -138,7 +138,7 @@ if __name__ == "__main__": pass ``` -Run it and speak in any [supported source language](/docs/voice/supported-languages-formats-and-limits#supported-languages). Each sentence prints once it's final, first the transcript, then each translation. Press Ctrl+C when you're done: the script stops recording, waits for the remaining results, and exits cleanly. +Run it and speak in any [supported source language](/docs/voice/supported-voice-languages). Each sentence prints once it's final, first the transcript, then each translation. Press Ctrl+C when you're done: the script stops recording, waits for the remaining results, and exits cleanly. ```text ❯ python live_translation.py @@ -244,7 +244,7 @@ async def send_file_audio(ws, path: str, stop: asyncio.Event) -> None: await ws.send(json.dumps({"end_of_source_media": {}})) ``` -Any recording of speech in a [supported format](/docs/voice/supported-languages-formats-and-limits#supported-audio-formats) works, for example an MP3 of a podcast episode. +Any recording of speech in a [supported format](/docs/voice/voice-api-requirements#supported-audio-formats) works, for example an MP3 of a podcast episode. Don't send audio faster than 2x real-time. Uploading a file as fast as the network allows triggers rate limits and terminates the session. diff --git a/docs/voice/supported-languages-formats-and-limits.mdx b/docs/voice/supported-languages-formats-and-limits.mdx deleted file mode 100644 index 6df73d12..00000000 --- a/docs/voice/supported-languages-formats-and-limits.mdx +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: "Supported Languages, Formats, and Limits" -description: "Reference for DeepL Voice API language availability, supported audio codecs and containers, and session limits." ---- - -## Supported languages - -Translation is always provided by DeepL. For some languages, transcription and translated speech are provided by external service partners. All source languages can be translated into any target language. - - -{/* BEGIN GENERATED voice-language-matrix (run: node scripts/update-language-docs.mjs) */} -| **Language** | **Transcription** | **Translation** | Translated Speech | -| :--- | :---: | :---: | :---: | -| Arabic | ⎋ | ✓ | ⎋ | -| Bengali | ⎋ | ✓ | — | -| Bulgarian | ⎋ | ✓ | ⎋ | -| Chinese (Simplified/Traditional) | ✓ | ✓ | ✓ | -| Croatian | ⎋ | ✓ | — | -| Czech | ✓ | ✓ | ⎋ | -| Danish | ⎋ | ✓ | ⎋ | -| Dutch | ✓ | ✓ | ✓ | -| English (American/British) | ✓ | ✓ | ✓ | -| Estonian | ⎋ | ✓ | — | -| Finnish | ⎋ | ✓ | ⎋ | -| French | ✓ | ✓ | ✓ | -| German | ✓ | ✓ | ✓ | -| Greek | ⎋ | ✓ | ⎋ | -| Hebrew | ⎋ | ✓ | — | -| Hindi beta | ⎋ | ✓ | ⎋ | -| Hungarian | ⎋ | ✓ | ⎋ | -| Indonesian | ✓ | ✓ | ⎋ | -| Irish | ⎋ | ✓ | — | -| Italian | ✓ | ✓ | ✓ | -| Japanese | ✓ | ✓ | ✓ | -| Korean | ✓ | ✓ | ✓ | -| Latvian | ⎋ | ✓ | — | -| Lithuanian | ⎋ | ✓ | — | -| Malay beta | ⎋ | ✓ | ⎋ | -| Maltese | ⎋ | ✓ | — | -| Norwegian (bokmål) | ⎋ | ✓ | ⎋ | -| Polish | ✓ | ✓ | ✓ | -| Portuguese (Brazil/Portugal) | ✓ | ✓ | ✓ | -| Romanian | ✓ | ✓ | ⎋ | -| Russian | ✓ | ✓ | ✓ | -| Slovak | ⎋ | ✓ | ⎋ | -| Slovenian | ⎋ | ✓ | — | -| Spanish | ✓ | ✓ | ✓ | -| Swedish | ✓ | ✓ | ✓ | -| Tagalog | ⎋ | ✓ | — | -| Tamil beta | ⎋ | ✓ | ⎋ | -| Thai | ⎋ | ✓ | — | -| Turkish | ✓ | ✓ | ✓ | -| Ukrainian | ✓ | ✓ | ⎋ | -| Vietnamese | ⎋ | ✓ | ⎋ | -{/* END GENERATED voice-language-matrix */} - -✓ provided by DeepL / ⎋ provided by an external service partner / — not available - - - - Transcription provided by external service partners (marked with ⎋) cannot yet auto-detect the source language, - which you must therefore specify explicitly. - - -To retrieve supported languages and feature availability programmatically, call [`GET /v3/languages?resource=voice`](/docs/languages/using-the-languages-api) and check for the `transcription` and `translated_speech` feature keys. The `external` flag on these features indicates if they are provided by an external service partner. - -## Supported audio formats - -The API supports common combinations of streaming codecs and containers with a single-channel (mono) audio stream. - -| **Audio Codec** | **Audio Container** | **Recommended Bitrate** | -| :--------------------------- | :---------------------------------- | :--------------------------------------------------- | -| **PCM** | **-** | **256 kbps (16kHz), default recommendation** | -| **OPUS** | **Matroska / MPEG-TS / Ogg / WebM** | **32 kbps, recommended for low bandwidth scenarios** | -| AAC | Matroska / MPEG-TS | 96 kbps | -| FLAC | FLAC / Matroska / Ogg | 256 kbps (16kHz) | -| MP3 | MPEG / Matroska | 128 kbps | - -For the detailed list of supported input audio formats, see [Source Media Content Type](/api-reference/voice/request-session#body-source-media-content-type). For supported output audio formats, see [Target Media Content Type](/api-reference/voice/request-session#body-target-media-content-type). - -## Session limits - -* Maximum 5 translation targets per session (including translated speech targets) -* Maximum 1 translated speech target per session -* Audio chunk size: should not exceed 100 kilobytes or 1 second duration -* Recommended chunk duration: 50-250 milliseconds for low latency -* Audio stream speed: maximum 2x real-time -* Timeout: if no data is received for 30 seconds, the session is terminated -* Maximum connection duration: after 1 hour, the connection is closed. Establish a new connection by [reconnecting](/api-reference/voice/reconnect-session) to the session -* Using any given token more than once to establish a WebSocket connection terminates the associated session immediately for security reasons - -If you need more translation targets or translated speech targets than these limits allow, open multiple concurrent sessions over the same source audio. diff --git a/docs/voice/supported-voice-languages.mdx b/docs/voice/supported-voice-languages.mdx new file mode 100644 index 00000000..acf76d49 --- /dev/null +++ b/docs/voice/supported-voice-languages.mdx @@ -0,0 +1,65 @@ +--- +title: "Supported Voice Languages" +description: "Language availability for the DeepL Voice API: transcription, translation, and translated speech support per language." +--- + +Translation is always provided by DeepL. For some languages, transcription and translated speech are provided by external service partners. All source languages can be translated into any target language. + + +{/* BEGIN GENERATED voice-language-matrix (run: node scripts/update-language-docs.mjs) */} +| **Language** | **Transcription** | **Translation** | **Translated Speech** | +| :--- | :---: | :---: | :---: | +| Arabic | ⎋ | ✓ | ⎋ | +| Bengali | ⎋ | ✓ | — | +| Bulgarian | ⎋ | ✓ | ⎋ | +| Chinese (Simplified/Traditional) | ✓ | ✓ | ✓ | +| Croatian | ⎋ | ✓ | — | +| Czech | ✓ | ✓ | ⎋ | +| Danish | ⎋ | ✓ | ⎋ | +| Dutch | ✓ | ✓ | ✓ | +| English (American/British) | ✓ | ✓ | ✓ | +| Estonian | ⎋ | ✓ | — | +| Finnish | ⎋ | ✓ | ⎋ | +| French | ✓ | ✓ | ✓ | +| German | ✓ | ✓ | ✓ | +| Greek | ⎋ | ✓ | ⎋ | +| Hebrew | ⎋ | ✓ | — | +| Hindi beta | ⎋ | ✓ | ⎋ | +| Hungarian | ⎋ | ✓ | ⎋ | +| Indonesian | ✓ | ✓ | ⎋ | +| Irish | ⎋ | ✓ | — | +| Italian | ✓ | ✓ | ✓ | +| Japanese | ✓ | ✓ | ✓ | +| Korean | ✓ | ✓ | ✓ | +| Latvian | ⎋ | ✓ | — | +| Lithuanian | ⎋ | ✓ | — | +| Malay beta | ⎋ | ✓ | ⎋ | +| Maltese | ⎋ | ✓ | — | +| Norwegian (bokmål) | ⎋ | ✓ | ⎋ | +| Polish | ✓ | ✓ | ✓ | +| Portuguese (Brazil/Portugal) | ✓ | ✓ | ✓ | +| Romanian | ✓ | ✓ | ⎋ | +| Russian | ✓ | ✓ | ✓ | +| Slovak | ⎋ | ✓ | ⎋ | +| Slovenian | ⎋ | ✓ | — | +| Spanish | ✓ | ✓ | ✓ | +| Swedish | ✓ | ✓ | ✓ | +| Tagalog | ⎋ | ✓ | — | +| Tamil beta | ⎋ | ✓ | ⎋ | +| Thai | ⎋ | ✓ | — | +| Turkish | ✓ | ✓ | ✓ | +| Ukrainian | ✓ | ✓ | ⎋ | +| Vietnamese | ⎋ | ✓ | ⎋ | +{/* END GENERATED voice-language-matrix */} + +✓ provided by DeepL / ⎋ provided by an external service partner / — not available + + + + Transcription provided by external service partners (marked with ⎋) cannot yet auto-detect the source language, + which you must therefore specify explicitly. + + +To retrieve supported languages and feature availability programmatically, call [`GET /v3/languages?resource=voice`](/docs/languages/using-the-languages-api) and check for the `transcription` and `translated_speech` feature keys. The `external` flag on these features indicates if they are provided by an external service partner. + +For audio format support and session limits, see [Voice API Requirements](/docs/voice/voice-api-requirements). diff --git a/docs/voice/understanding-voice-sessions.mdx b/docs/voice/understanding-voice-sessions.mdx index 8fb78881..ff4107a3 100644 --- a/docs/voice/understanding-voice-sessions.mdx +++ b/docs/voice/understanding-voice-sessions.mdx @@ -48,7 +48,7 @@ Two security properties follow from the token design: * Each token and streaming URL is valid for one-time use. Using a token more than once to open a WebSocket connection terminates the session immediately. * Only the latest token can request a reconnection. Presenting an outdated token invalidates the session. -Requesting a reconnection token while a connection is still active disconnects that connection, so only reconnect after the existing connection has closed. Connections also have a maximum duration; when it's reached, reconnect the same way to continue the session. See [session limits](/docs/voice/supported-languages-formats-and-limits#session-limits) for the exact values. +Requesting a reconnection token while a connection is still active disconnects that connection, so only reconnect after the existing connection has closed. Connections also have a maximum duration; when it's reached, reconnect the same way to continue the session. See [session limits](/docs/voice/voice-api-requirements#session-limits) for the exact values. ## How audio and results flow diff --git a/docs/voice/voice-api-requirements.mdx b/docs/voice/voice-api-requirements.mdx new file mode 100644 index 00000000..15f2a6ac --- /dev/null +++ b/docs/voice/voice-api-requirements.mdx @@ -0,0 +1,33 @@ +--- +title: "Voice API Requirements" +description: "Audio format requirements and session limits for the DeepL Voice API: supported codecs and containers, chunk sizes, and connection rules." +--- + +## Supported audio formats + +The API supports common combinations of streaming codecs and containers with a single-channel (mono) audio stream. + +| **Audio Codec** | **Audio Container** | **Recommended Bitrate** | +| :--------------------------- | :---------------------------------- | :--------------------------------------------------- | +| **PCM** | **-** | **256 kbps (16kHz), default recommendation** | +| **OPUS** | **Matroska / MPEG-TS / Ogg / WebM** | **32 kbps, recommended for low bandwidth scenarios** | +| AAC | Matroska / MPEG-TS | 96 kbps | +| FLAC | FLAC / Matroska / Ogg | 256 kbps (16kHz) | +| MP3 | MPEG / Matroska | 128 kbps | + +For the detailed list of supported input audio formats, see [Source Media Content Type](/api-reference/voice/request-session#body-source-media-content-type). For supported output audio formats, see [Target Media Content Type](/api-reference/voice/request-session#body-target-media-content-type). + +## Session limits + +* Maximum 5 translation targets per session (including translated speech targets) +* Maximum 1 translated speech target per session +* Audio chunk size: should not exceed 100 kilobytes or 1 second duration +* Recommended chunk duration: 50-250 milliseconds for low latency +* Audio stream speed: maximum 2x real-time +* Timeout: if no data is received for 30 seconds, the session is terminated +* Maximum connection duration: after 1 hour, the connection is closed. Establish a new connection by [reconnecting](/api-reference/voice/reconnect-session) to the session +* Using any given token more than once to establish a WebSocket connection terminates the associated session immediately for security reasons + +If you need more translation targets or translated speech targets than these limits allow, open multiple concurrent sessions over the same source audio. + +For language availability, see [Supported Voice Languages](/docs/voice/supported-voice-languages). diff --git a/scripts/generate-voice-languages.mjs b/scripts/generate-voice-languages.mjs index b15a9e12..567cc9b8 100644 --- a/scripts/generate-voice-languages.mjs +++ b/scripts/generate-voice-languages.mjs @@ -1,6 +1,6 @@ #!/usr/bin/env node // Regenerates the Voice API language tables from GET /v3/languages?resource=voice: -// the support matrix in docs/voice/supported-languages-formats-and-limits.mdx and +// the support matrix in docs/voice/supported-voice-languages.mdx and // the input/target lists in api-reference/voice/deepl-voice-api-service-specification-updates.mdx. // // Usage: node scripts/generate-voice-languages.mjs [--dry-run] @@ -39,11 +39,11 @@ export async function update({ authKey, dryRun = false }) { return `| ${name} | ${mark(l.features.transcription)} | ✓ | ${mark(l.features.translated_speech)} |`; }); const matrix = [ - '| **Language** | **Transcription** | **Translation** | Translated Speech |', + '| **Language** | **Transcription** | **Translation** | **Translated Speech** |', '| :--- | :---: | :---: | :---: |', ...rows, ].join('\n'); - await replaceBlock('docs/voice/supported-languages-formats-and-limits.mdx', 'voice-language-matrix', matrix, { dryRun }); + await replaceBlock('docs/voice/supported-voice-languages.mdx', 'voice-language-matrix', matrix, { dryRun }); const item = (l) => `
  • \`${l.lang}\` (${l.name})
    • `; await replaceBlock( diff --git a/standards/ia.yaml b/standards/ia.yaml index 9597e790..b5cdb052 100644 --- a/standards/ia.yaml +++ b/standards/ia.yaml @@ -33,6 +33,7 @@ families: narrative_home: own groups: - {name: Customize, tags: [ManageGlossaries, ManageMultilingualGlossaries, TranslationMemories]} + - {name: Spoken Terms, tags: [ManageSpokenTerms]} # Style rules live under Customize but have no OpenAPI tag yet. Voice: