diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..7f97a17a --- /dev/null +++ b/.gitattributes @@ -0,0 +1,6 @@ +# Normalize line endings to LF on commit, regardless of contributor OS. +# Set globally on your system with: +# git config --global core.autocrlf false +# git config --global core.eol lf + +* text=auto eol=lf diff --git a/.github/workflows/update_openapi_json.yml b/.github/workflows/update_openapi_json.yml new file mode 100644 index 00000000..d9bd4ce1 --- /dev/null +++ b/.github/workflows/update_openapi_json.yml @@ -0,0 +1,31 @@ +name: Update OpenAPI JSON files from YAML sources + +on: + pull_request: + branches: ["main"] + paths: + - "api-reference/openapi.yaml" + - "api-reference/voice/voice.asyncapi.yaml" + +jobs: + convert_yaml_to_json: + name: Convert YAML specs to JSON + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + ref: ${{ github.head_ref }} + + - uses: mikefarah/yq@v4.44.3 + + - name: Convert openapi.yaml to JSON + run: yq -o=json '.' api-reference/openapi.yaml > api-reference/openapi.json + + - name: Convert voice.asyncapi.yaml to JSON + run: yq -o=json '.' api-reference/voice/voice.asyncapi.yaml > api-reference/voice/voice.asyncapi.json + + - name: Commit updated JSON files + uses: stefanzweifel/git-auto-commit-action@v5 + with: + commit_message: "chore: update OpenAPI JSON files from YAML sources" + file_pattern: "api-reference/openapi.json api-reference/voice/voice.asyncapi.json" diff --git a/.mintignore b/.mintignore index 34472b6f..8d1cc48b 100644 --- a/.mintignore +++ b/.mintignore @@ -1 +1,3 @@ reviews/* +api-reference/openapi.json +api-reference/voice/voice.asyncapi.json diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..620b807b --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,340 @@ +# Changelog +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +The major and minor version numbers reflect changes to the DeepL API +(backward-incompatible and backward-compatible, respectively). The patch version +number is used only for corrections to the OpenAPI specification, for example: +typos, schema fixes, or adding examples. + +## [Unreleased] +### Added +* Add new OpenAPI spec `jobs-voice-translate.openapi.yaml` for the async voice translation API (`POST /v1/jobs/voice/translate`, `GET /v1/jobs/voice/translate/{job_id}`) +* Document `X-Trace-ID` response header returned by all API endpoints for request tracking and debugging +* Add new parameters to the text translation API: `enable_beta_languages` and `custom_instructions` +* Add new CRUD endpoints for `/v3/style_rules` +* Add new endpoint `GET /v3/translation_memories` for listing translation memories +* Add new parameters `translation_memory_id` and `translation_memory_threshold` to `/v2/translate` +* Add `format: uuid` to `StyleId` schema + +### Fixed +* Fixes/development changes to the voice API. + * Changed the voice paths in the `voice.asyncapi.*` files to use `/v3/voice/*` + * Renamed `SourceDataChunk` and `EndOfSourceData` to `SourceMediaChunk` and `EndOfSourceMedia` + * +* Fixes the usage endpoint response object name. Should be `key_usages` and `key_and_day_usages` instead of `grouped_usage` +* Add all supported languages to Translate API `source_lang` and `target_lang` specs +* Merge redundant `SourceLanguageText` and `TargetLanguageText` schemas into `SourceLanguage` and `TargetLanguage` to eliminate duplication + +### Deprecated +* Removed the `openapi_gitbook.yaml` file due to redundancy. Please use `openapi.yaml` going forward + +## [3.10.0] - 2025-01-27 +### Added +* Add `speech_to_text_milliseconds` field to developer key usage limits in `/v2/admin/developer-keys/limits` endpoint and `ApiKey` response schema + +## [3.9.0] - 2025-12-11 +### Added +* Add `speech_to_text_milliseconds` field to usage reports and analytics components +* Add `speech_to_text_milliseconds_count` and `speech_to_text_milliseconds_limit` fields to `/v2/usage` response for API Pro users +* Add `billing_unit`, `api_key_unit_count`, and `account_unit_count` fields to product usage items in `/v2/usage` response + +## [3.8.0] - 2025-11-26 +### Fixed +* Fixes/development changes to the voice API. Note that this API is under active develpoment and not yet stable. + * Change voice path to be `/v3/voice/realtime` and `/v3/voice/realtime/connect` + * Renamed voice parameter from `media_content_type` to `source_media_content_type` + * Allow more `formality` values on voice endpoints + +## [3.7.0] - 2025-11-10 +### Added +* Add new endpoints `/v1/voice/realtime` (REST) and `/v1/voice/realtime/connect` (WebSocket) which enable real-time voice transcription and translation via WebSocket streaming +* Adds AsyncAPI specification - `voice.asyncapi.yaml` and `voice.asyncapi.json` - documenting the Voice WebSocket streaming protocol + +## [3.6.1] - 2025-11-06 +### Changed +* Hebrew (`HE`), Thai (`TH`), and Vietnamese (`VI`) are now included in the `/v2/languages` endpoint response as they now support document translation in addition to text translation + +## [3.6.0] - 2025-10-29 +### Added +* Add new parameter `tag_handling_version` to `/v2/translate` + +## [3.5.0] - 2025-10-27 +### Added +* Add new endpoint `v2/admin/analytics` which enables admins to retrieve usage statistics across their organization + +## [3.4.2] - 2025-10-06 +### Added +* Latin American Spanish (`ES-419`) is now supported as a target language option for +Document translation. `/v2/languages` now includes `ES-419` as a valid target language +option. + +## [3.4.1] - 2025-07-31 +### Added +* Add note for boolean values about how to input for URL-encoded forms + + +## [3.4.0] - 2025-07-16 +### Added +* Add new endpoints `/v2/admin/developer-keys` which enables management of developer +keys within an organization. + +## [3.3.1] - 2025-07-16 +### Fixed +* Added `application/x-www-form-urlencoded` Content-Type to the `replaceDictionary` + endpoint. + * Thanks to [danielesser](https://github.com/danielesser) for the report in + [#35](https://github.com/DeepLcom/openapi/issues/35). + +## [3.3.0] - 2025-06-25 +### Fixed +* Updated the possible error responses for the /v2 and /v3 glossary endpoints + including: + * Removing any errors that are not valid responses for the API + * Updating the `QuotaExceededGlossaries` description as it is returned when + the glossary creation limit has been reached + +## [3.2.0] - 2025-06-03 +### Added +* Added updated language support for document translation: + * Target language variant: Chinese (traditional) (`ZH-HANT`) + * Source and target language: Arabic (`AR`) +* Added updated language support for text translation for Hebrew (`HE`), Thai + (`TH`), and Vietnamese (`VI`). These languages are only supported for text + translation, document translation support is coming soon. +* Added updated source and target for glossaries. All languages supported for + text translation are now supported for glossaries now including: + Arabic (`AR`), Bulgarian (`BG`), Czech (`CS`), Greek (`EL`), Estonian (`ET`), + Hebrew (`HE`), Hungarian (`HU`), Indonesian (`ID`), Lithuanian (`LT`), + Latvian (`LV`), Slovak (`SK`), Slovenian (`SL`), Thai (`TH`), Turkish (`TR`), + Ukrainian (`UK`), and Vietnamese (`VI`). + +## [3.1.1] - 2025-05-23 +### Fixed +* Fixed incorrect placement of UsageResponse schema. + + +## [3.1.0] - 2024-05-20 +### Changed +* `/v2/usage`: Now returns a detailed response for API Pro users, including per-product usage and billing period information. For API users not on the Pro plan, the response remains unchanged and only includes `character_count` and `character_limit`. + + +## [3.1.0] - 2024-05-20 +### Fixed +* Fixed new server URLs to avoid double slash in paths + + +## [3.0.1] - 2025-04-24 +### Fixed +* Fixed new server URLs to avoid double slash in paths + + +## [3.0.0] - 2025-04-24 +### Added +* Add new endpoints `/v3/glossaries` which enables management of new, editable and multilingual glossaries + * This required renaming some existing components in the spec, hence the major version upgrade. All + functionality is backwards compatible. +* Moved `/v2/` and `/v3/` from the Server URL into the endpoint paths, as we support multiple versions now + + +## [2.18.0] - 2025-01-16 +### Added +* Add new endpoint `/write/rephrase` which enables text corrections and adjustments in selected languages + + +## [2.17.0] - 2024-11-15 +### Added +* `/translate`: add `model_type` request parameter to request the model type + (`quality_optimized`, `latency_optimized`, or `prefer_latency_optimized`) to + use for translation, and the `model_type_used` response parameter indicating + the model type that used. + + +## [2.16.0] - 2024-07-25 +### Added +* Add supported target language variant for text translation: Chinese + (traditional) (`ZH-HANT`). Traditional Chinese is currently supported only for + text translation; document translation support is coming soon. +### Changed +* The Chinese language codes returned in the `/languages` response for target + languages were changed. While previously only `ZH` "Chinese (simplified)" was + included, `ZH-HANS` "Chinese (simplified)" is now listed too. + Both language codes are supported for text and document translation. +### Deprecated +* The target language code `ZH` is deprecated; instead `ZH-HANS` or `ZH-HANT` + should be used. + + +## [2.15.0] - 2024-07-03 +### Added +* Add supported glossary language: Romanian (`ro`). + + +## [2.14.1] - 2024-06-18 +### Changed +* Text translation `context` parameter is now generally available (was alpha). + + +## [2.14.0] - 2024-05-08 +### Added +* Added supported glossary languages: Danish (`'da'`), Norwegian (bokmål) (`'nb'`), and Swedish (`'sv'`). + + +## [2.13.0] - 2024-03-14 +### Deprecated +* Remove all properties from `/usage` except for `character_count` and `character_limit`; + these are the only two properties included in the API response for the v2 API. +### Fixed +* Fixed some minor issues in specs that were violating OpenAPI specification. + * Thanks to [hoemoon](https://github.com/hoemoon) in [#8](https://github.com/DeepLcom/openapi/pull/8). + + +## [2.12.0] - 2024-02-29 +### Added +* Add supported glossary language: Korean (KO). +* Add supported language for text translation: Arabic (AR). Arabic is + currently supported only for text translation; document translation + support for Arabic is coming soon. + + +## [2.11.0] - 2023-08-03 +### Added +* Add supported glossary languages: Portuguese (PT), Russian (RU), and Chinese (ZH). + + +## [2.10.0] - 2023-07-13 +### Added +* Add JSON-format request bodies to all endpoints except document upload. + + +## [2.9.2] - 2023-06-20 +### Added +* Japanese (JA) now supports formality. + + +## [2.9.1] - 2023-05-26 +### Fixed +* Fix typo in `/glossaries/{glossary_id}` example and spec version number. + * Thanks to [cluttrdev](https://github.com/cluttrdev) for the suggestion + in [#2](https://github.com/DeepLcom/openapi/issues/2). +* Move `description` parameter outside of `allOf` parameter. + * Thanks to [mikakruschel](https://github.com/mikakruschel) for the suggestion + in [#1](https://github.com/DeepLcom/openapi/issues/1). + + +## [2.9.0] +### Added +* Transitive glossaries are now supported, bringing the number of supported + glossary pairs from 8 to 28. +### Changed +* Supported XLIFF version 2.1 is now explicitly stated. + + +## [2.8.0] +### Added +* Add Korean and Norwegian (Bokmål) languages. + + +## [2.7.0] +### Added +* Add XLIFF to supported document types. + + +## [2.6.0] +### Changed +* HTML handling is no longer in Beta. +* Removed limit on text parameters (was 50). + + +## [2.5.0] +### Added +* Add support for EN (English) ←→ NL (Dutch) glossaries. + + +## [2.4.0] +### Added +* Add formality options prefer_less and prefer_more. +* Add note to readme about Swagger UI simulator and CORS restrictions. + + +## [2.3.1] +### Fixed +* Source and target language were mixed up in glossary example. +* Fix createGlossary example: remove punctuation. + + +## [2.3.0] +### Added +* Add Ukrainian source and target languages. +### Changed +* Add request body size limit to translateText description. +### Fixed +* Add "Simplified" label to ZH (Chinese) target language. +* Fix a typo in an example. +* Markdown fixes. + + +## [2.2.0] +### Added +* Add support for EN (English) ←→ PL (Polish) glossaries. +### Fixed +* EN (English) ←→ IT (Italian) was missing from the list of supported glossary + language pairs in the JSON OpenAPI spec. + + +## [2.1.0] +### Added +* Add CSV entries format for creating glossaries. +### Changed +* Rename some tags, reword some descriptions and label default values in + descriptions. +* Add note about glossaries being immutable, and a workaround for modifying + glossaries. + + +## [2.0.0] +Initial release of the OpenAPI specification. + +[Unreleased]: https://github.com/DeepLcom/openapi/compare/v3.9.0...HEAD +[3.9.0]: https://github.com/DeepLcom/openapi/compare/v3.8.0...v3.9.0 +[3.8.0]: https://github.com/DeepLcom/openapi/compare/v3.7.0...v3.8.0 +[3.7.0]: https://github.com/DeepLcom/openapi/compare/v3.6.1...v3.7.0 +[3.6.1]: https://github.com/DeepLcom/openapi/compare/v3.6.0...v3.6.1 +[3.6.0]: https://github.com/DeepLcom/openapi/compare/v3.5.0...v3.6.0 +[3.5.0]: https://github.com/DeepLcom/openapi/compare/v3.4.2...v3.5.0 +[3.4.2]: https://github.com/DeepLcom/openapi/compare/v3.4.1...v3.4.2 +[3.4.1]: https://github.com/DeepLcom/openapi/compare/v3.4.0...v3.4.1 +[3.4.0]: https://github.com/DeepLcom/openapi/compare/v3.3.1...v3.4.0 +[3.3.1]: https://github.com/DeepLcom/openapi/compare/v3.3.0...v3.3.1 +[3.3.0]: https://github.com/DeepLcom/openapi/compare/v3.2.0...v3.3.0 +[3.2.0]: https://github.com/DeepLcom/openapi/compare/v3.1.1...v3.2.0 +[3.1.1]: https://github.com/DeepLcom/openapi/compare/v3.1.0...v3.1.1 +[3.1.0]: https://github.com/DeepLcom/openapi/compare/v3.0.2...v3.1.0 +[3.0.2]: https://github.com/DeepLcom/openapi/compare/v3.0.1...v3.0.2 +[3.0.1]: https://github.com/DeepLcom/openapi/compare/v3.0.0...v3.0.1 +[3.0.0]: https://github.com/DeepLcom/openapi/compare/v2.18.0...v3.0.0 +[2.18.0]: https://github.com/DeepLcom/openapi/compare/v2.17.0...v2.18.0 +[2.17.0]: https://github.com/DeepLcom/openapi/compare/v2.16.0...v2.17.0 +[2.16.0]: https://github.com/DeepLcom/openapi/compare/v2.15.0...v2.16.0 +[2.15.0]: https://github.com/DeepLcom/openapi/compare/v2.14.1...v2.15.0 +[2.14.1]: https://github.com/DeepLcom/openapi/compare/v2.14.0...v2.14.1 +[2.14.0]: https://github.com/DeepLcom/openapi/compare/v2.13.0...v2.14.0 +[2.13.0]: https://github.com/DeepLcom/openapi/compare/v2.12.0...v2.13.0 +[2.12.0]: https://github.com/DeepLcom/openapi/compare/v2.11.0...v2.12.0 +[2.11.0]: https://github.com/DeepLcom/openapi/compare/v2.10.0...v2.11.0 +[2.10.0]: https://github.com/DeepLcom/openapi/compare/v2.9.2...v2.10.0 +[2.9.2]: https://github.com/DeepLcom/openapi/compare/v2.9.1...v2.9.2 +[2.9.1]: https://github.com/DeepLcom/openapi/compare/v2.9.0...v2.9.1 +[2.9.0]: https://github.com/DeepLcom/openapi/compare/v2.8.0...v2.9.0 +[2.8.0]: https://github.com/DeepLcom/openapi/compare/v2.7.0...v2.8.0 +[2.7.0]: https://github.com/DeepLcom/openapi/compare/v2.6.0...v2.7.0 +[2.6.0]: https://github.com/DeepLcom/openapi/compare/v2.5.0...v2.6.0 +[2.5.0]: https://github.com/DeepLcom/openapi/compare/v2.4.0...v2.5.0 +[2.4.0]: https://github.com/DeepLcom/openapi/compare/v2.3.1...v2.4.0 +[2.3.1]: https://github.com/DeepLcom/openapi/compare/v2.3.0...v2.3.1 +[2.3.0]: https://github.com/DeepLcom/openapi/compare/v2.2.0...v2.3.0 +[2.2.0]: https://github.com/DeepLcom/openapi/compare/v2.1.0...v2.2.0 +[2.1.0]: https://github.com/DeepLcom/openapi/compare/v2.0.0...v2.1.0 +[2.0.0]: https://github.com/DeepLcom/openapi/releases/tag/v2.0.0 diff --git a/LICENSE b/LICENSE new file mode 100644 index 00000000..906c2248 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright 2022 DeepL SE (https://www.deepl.com) + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 2aa499e3..572e260a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,38 @@ # DeepL Developer Docs -This repo is home to the [DeepL Developer Docs](https://developers.deepl.com/). +This repo is home to the [DeepL Developer Docs](https://developers.deepl.com/) +and the authoritative [OpenAPI specification](https://openapis.org/) of the +[DeepL API](https://www.deepl.com/pro-api). + +## OpenAPI specification + +This project contains an [OpenAPI specification](https://openapis.org/) of the [DeepL API](https://www.deepl.com/pro-api), in YAML and JSON formats. + +| File | Purpose | +|---|---| +| [`api-reference/openapi.yaml`](api-reference/openapi.yaml) | Main REST API spec (source of truth) | +| [`api-reference/openapi.json`](api-reference/openapi.json) | Same content, JSON format (auto-generated) | +| [`api-reference/voice/voice.asyncapi.yaml`](api-reference/voice/voice.asyncapi.yaml) | AsyncAPI spec for the streaming voice API (source of truth) | +| [`api-reference/voice/voice.asyncapi.json`](api-reference/voice/voice.asyncapi.json) | Same content, JSON format (auto-generated) | + +You can use this specification to explore the API in tools like [Postman](https://www.postman.com/), or to auto-generate documentation, SDKs, and code libraries using tools such as [Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/DeepLcom/api-docs/main/api-reference/openapi.yaml) or [OpenAPI Generator](https://openapi-generator.tech/). + +Note that Swagger's "Try it out" in-browser simulator creates valid Curl requests, the requests will fail due to [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) restrictions. + +[Changelog](CHANGELOG.md) + +If you encounter issues while using this OpenAPI specification or have feature requests, please [create an issue](https://github.com/DeepLcom/api-docs/issues). + +### Regenerating the JSON files + +The JSON files are auto-generated from the YAML sources. **Don't edit them by hand.** + +A GitHub Actions workflow regenerates them on any PR that touches the YAML sources and commits the result back to the PR branch. To preview locally: + +```bash +yq -o=json '.' api-reference/openapi.yaml > api-reference/openapi.json +yq -o=json '.' api-reference/voice/voice.asyncapi.yaml > api-reference/voice/voice.asyncapi.json +``` ## Development diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000..91d4617e --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,58 @@ +To report security concerns or vulnerabilities within this project, please email +us at [security@deepl.com](mailto:security@deepl.com). + +You can send us PGP-encrypted email using the following PGP public key: + +``` +-----BEGIN PGP PUBLIC KEY BLOCK----- + +mQINBF7WSmABEADzRUp22VY7bVfUWScKLi9o8BRSEL4u3aPn9WOQoRLQH0j3dNNQ +FQlwTPn/Ez6qreEl8mX0aE+eLCEykXqsrU/UaTSTslF+H6UQyuGLXkRm8Lblt93I +OEhL069fC7rm+/zJq72+hishBF8DXqa+WtFd8VfK3i211vRhU/teKeAKT0xiuN/5 +EQl1Bn7jR7mmQtNbPBhCsAlaC/tNUQ3Lyj6LYnnco7ums5Q/gCvfs2HM3mXJyvnG +1MC2IrECPowTt04W3V1uXuMcm766orTG/AmtBIbPmOzao4sfqwRVHGvc8zcr1az9 +0nVyEJXx1eUVRDU1GAQuMjEkGgwvTd+nt6sHpn8C+9hMYJhon9veDSupViBuvNRC +p1PnpSLYYy7tA7DPXMhP3cMXe+Z4bYzgwi3xjOwh6SDyB4OFIxtGyuMrLGfZnd6A +hDH4H9zHPpciD5MxcOaqlKdgABQALvc6MvJ1Guf1ckGTbfHz1brtR1LPMK8rrnNu +kwQzgkogYV6YAnt8LPXMPa2Vgy8TAiby7GPaATPeSWdNHtkuYGhWNVbnb60kEWiJ +/RgHFZYfRT1dEcKoQEcDJ7AV14urEFIAfmhlsT8h7iJYUQMa45BakUubi3aWwcme +ya+5WXvp2xU14VMfrscApA0e1v0VcTNVwlKambs/lwims0/xiSaXJS6gVwARAQAB +tCNEZWVwTCBTZWN1cml0eSA8c2VjdXJpdHlAZGVlcGwuY29tPokCTgQTAQgAOBYh +BGvTAPE3gtThLDZ9+ey96Y7yK41BBQJe1kpgAhsDBQsJCAcCBhUKCQgLAgQWAgMB +Ah4BAheAAAoJEOy96Y7yK41BHVIP/04R08g4N32c47edY6z3sl3DAf+/6UI4Bc4S +Jg5L4JcfrsKaDd55plps8nj31VXrxVBO0NrO6HLC50SXbYVrANyo0occ2mIoU8c2 +tNbYCUmJ3QjlUwDjHWlMV2J9FcfZkv7z+2TDY6DF8MKqCMi8j7Pnj0hlY0JytciH +SGES1q8+//8tG9z6b6vvxBFfJI+iNXvcbn6uU1WRvGoBqq2A13fXuwTXiNNphsvu +kHqBHSxnf/EAmcmBX0tm6yaWDdwy+rrcDNwXiqqvK6DFWEE7+/9t2FhlgzvuCOfx +dQVMZL8WH2rr6OPQLDgtGxEUFmD+srmqbVn5NKdY6lQ/BEaraozDkuqJEb0/L/kb +Dv+buz8rmKze0XPlrt1XTQ5ZDQp8AMAaPp1UsizVhasZgxxuUa+g5mMbJr7TSNJN +CIqidnh1MEyIr3IccOAr2F51hn6keKIdVnO4dWrWNMTfk00dw3fPGFhNTniITTF2 +s3oJ8cy2NMNkVMP5XL3bulpgkKN+hXa4IHkTfWRv7hfYJ/3i3yTRNRjYGRoVp7eM +iADumKaZy5Szl458txuI+p9DGAEvkSJoF7ptwedSvVZ/FZukS5mwYisRV9shzsXF +3jpcGZ1B3qS68r9ySqnPEWR6oT8p63fpMNVMjz5r4YEbvU0A62OhUk52drLM6SgC +mdOZcmnHuQINBF7WSmABEADc6L/wSexm4l1GWZSQpJ35ldlu7jjWQGguQeeG2900 +aEI3UcftMCWg+apwf4h4Yj2YjzUncYAM6RenGvXgZUYQe3OHb8uqpkSmYHUdB/Uq +I4NPO3e8RMDo9YohPKCpZ7jV70X8F9GOUkUgfp29CjrMOYgSLwkSyWotsQ9KtkEH +Sx/h+gviIERe0dkiN9lCsReNigoWLleH4qBSZGPxqF4tzANJ6D2tnAv+6KUQvho3 +CdijBiia4o16p9M0altSqsZCEX1Y5BKmWIh9fvvS2uB7SdzS0gcASzlekMGCjG10 +dNji+uSNdHExlbl0kUpEL1TuY2hxPBa6lc1hckI3dGng0jIFlio4s8DG3Utmrj3C +KQFxnjqtO+uaJ8HdNo8ObtEp/v9TpsHWUchBTrBP4XN5KwqkljF8XVBA6ceh8H38 +7/RVWRcWp6h30ROm1DTnAGxJk02fbjpnEO0EvudxKTlnAJXV6z+Tm3yYaR4gQYa3 +/zfLZgz0z0MqNUsGephZGPzfUX7Lsz6HGUoo7I1KST6xD2QodJYOhHIEOgsqskk+ +cgeXp45X5JLlCQaBLQoL8ut6CTcop1/6U+JZtrm6DdXTZfq57sqfDI+gkG8WljRY +yhsCL+xWiwDjtt/8kpk+W75EQmwPuctoS85Rm6hEpffewdQtb2XCEWpbta6hE1r1 +kQARAQABiQI2BBgBCAAgFiEEa9MA8TeC1OEsNn357L3pjvIrjUEFAl7WSmACGwwA +CgkQ7L3pjvIrjUHFvg/9GnIW9SM/nYJpi1xZVWWGwQ+/kTceD50bv8kyvNaia/9m +HG6n83xHNTRBYnt8NtTqHvW0y20Cp3gUs2WxboDgCIb3+srI2ipwiaDJcq+rVr0f +XkCe5MryioKRbTFQ8OgvKh9GK/tYtqZakn7Q9596ajUjHOQV1+Uw/jywLYRlcbqI +zbxyNVWitxPs3Z7jUDAvhPOIOmhLFc+QxSYrs1W4ZEGnZ3+9utqzlEiMusy9Rq0T +/W/wrG6SckebjhrwWZJmy/hkW6V6LUX4++vCVV5+zwsvgEortCV8bhvLfqQDr/WN +fnmbNZtXJbyhTYbcYReOLeKidxO2lZEemnX6iOt5xCdoMcYU23xDT9+tE7Eh6Nfw +einZemBwfku5vxxPF73pOoQUCRq9tgvUrEq+3BqkqidhnFUOPi0J5726q1PBG65x +5o+SQyvB3NA3al3mEH65z3V3/g0UHnhGcEMwVOXBkffgdKNhWYw59qhSVQnkiq0U +MG10g/RL7VdiISAFPTDmKWUaEDYosinKqOMHwcaVdJq9ssvPf89et6yP/ZkbLIHs +2y3oiPonh2RMxi2OedlDz+Jp/A2o3qHmwNvBx/meGB0praGUonFVZTAA1EMS39Bi +NhG/L8giTyzA0mMkTJAPXtUVlRe5rEjORgYJsgRqZxEfpsJC9OkvYS4ayO0eCEs= +=jVHt +-----END PGP PUBLIC KEY BLOCK----- +``` \ No newline at end of file diff --git a/api-reference/openapi.json b/api-reference/openapi.json new file mode 100644 index 00000000..e782eaca --- /dev/null +++ b/api-reference/openapi.json @@ -0,0 +1,7311 @@ +{ + "openapi": "3.0.3", + "info": { + "title": "DeepL API Documentation", + "description": "The DeepL API provides programmatic access to DeepL’s language AI technology.\n\nNote: this OpenAPI spec is embedded into our API documentation and has shortened descriptions.", + "termsOfService": "https://www.deepl.com/pro-license", + "contact": { + "name": "DeepL - Contact us", + "url": "https://www.deepl.com/contact-us" + }, + "version": "3.9.0" + }, + "externalDocs": { + "description": "DeepL Pro - Plans and pricing", + "url": "https://www.deepl.com/pro#developer" + }, + "servers": [ + { + "url": "https://api.deepl.com", + "description": "DeepL API Pro" + }, + { + "url": "https://api-free.deepl.com", + "description": "DeepL API Free" + } + ], + "tags": [ + { + "name": "beta", + "description": "Experimental features that are under testing and not yet intended for production use." + }, + { + "name": "TranslateText", + "description": "The text-translation API currently consists of a single endpoint, `translate`, which is described below." + }, + { + "name": "TranslateDocuments", + "description": "The document translation API allows you to translate whole documents and supports the following file types and extensions:\n * `docx` - Microsoft Word Document\n * `pptx` - Microsoft PowerPoint Document\n * `xlsx` - Microsoft Excel Document\n * `pdf` - Portable Document Format\n * `htm / html` - HTML Document\n * `txt` - Plain Text Document\n * `xlf / xliff` - XLIFF Document, version 2.1\n * `srt` - SRT Document\n * `jpeg` / `jpg` / `png` - Image (currently in beta)" + }, + { + "name": "RephraseText", + "description": "The `rephrase` endpoint is used to make corrections and adjustments to texts based on style or tone." + }, + { + "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." + }, + { + "name": "ManageGlossaries", + "description": "Please note that this is the spec for the (old) v2 glossary endpoint.\nWe recommend users switch to the newer v3 glossary endpoints, which support editability and multilinguality.\n\nThe *glossary* functions allow you to create, inspect, and delete glossaries.\nGlossaries created with the glossary function can be used in translate requests by specifying the\n`glossary_id` parameter.\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)." + }, + { + "name": "MetaInformation", + "description": "Information about API usage and value ranges" + }, + { + "name": "TranslationMemories", + "description": "The translation memory endpoints allow you to interact with your account's translation memories, used to store\nand reuse previously created translations. Translation memories can be used in text translation requests by\nspecifying the `translation_memory_id` parameter to denote a specific translation memory and the\n`translation_memory_threshold` which defines the minimum matching percentage required for a translation memory\nsegment to be applied (recommended to be 75% or higher)." + }, + { + "name": "VoiceAPI", + "description": "The Voice API provides real-time voice transcription and translation services.\nUse a two-step flow: first request a streaming URL via REST, then establish a WebSocket connection for streaming audio and receiving transcriptions." + } + ], + "x-hideTryItPanel": true, + "x-codeSamples": false, + "paths": { + "/v2/admin/analytics": { + "get": { + "tags": [ + "AdminApi" + ], + "summary": "Get usage statistics as an admin", + "operationId": "adminGetAnalytics", + "description": "Retrieve usage statistics for the organization within a specified date range.\nOptionally group the results by API key or by API key and day.", + "parameters": [ + { + "name": "start_date", + "in": "query", + "required": true, + "description": "Start date for the usage report (ISO 8601 date format).", + "schema": { + "type": "string", + "format": "date" + }, + "example": "2025-09-29" + }, + { + "name": "end_date", + "in": "query", + "required": true, + "description": "End date for the usage report (ISO 8601 date format).", + "schema": { + "type": "string", + "format": "date" + }, + "example": "2025-10-01" + }, + { + "name": "group_by", + "in": "query", + "required": false, + "description": "Optional parameter to group usage statistics. Possible values:\n * `key` - Group by API key\n * `key_and_day` - Group by API key and usage date", + "schema": { + "type": "string", + "enum": [ + "key", + "key_and_day" + ] + }, + "example": "key_and_day" + } + ], + "responses": { + "200": { + "description": "The usage statistics for the specified date range.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AdminUsageReport" + }, + "examples": { + "withGrouping": { + "summary": "Usage report grouped by key and day", + "value": { + "usage_report": { + "total_usage": { + "total_characters": 9619, + "text_translation_characters": 4892, + "document_translation_characters": 0, + "text_improvement_characters": 4727, + "speech_to_text_minutes": 107.46 + }, + "group_by": "key_and_day", + "start_date": "2025-09-29T00:00:00", + "end_date": "2025-10-01T00:00:00", + "key_and_day_usages": [ + { + "api_key": "dc88****3a2c", + "api_key_label": "Staging API Key", + "usage_date": "2025-09-29T00:00:00Z", + "usage": { + "total_characters": 315, + "text_translation_characters": 159, + "document_translation_characters": 0, + "text_improvement_characters": 156, + "speech_to_text_minutes": 11.94 + } + } + ] + } + } + }, + "withoutGrouping": { + "summary": "Usage report without grouping", + "value": { + "usage_report": { + "total_usage": { + "total_characters": 9619, + "text_translation_characters": 4892, + "document_translation_characters": 0, + "text_improvement_characters": 4727, + "speech_to_text_minutes": 107.46 + }, + "start_date": "2025-09-29T00:00:00", + "end_date": "2025-10-01T00:00:00" + } + } + } + } + } + } + }, + "400": { + "description": "Bad request. Please check error message and your parameters.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "Error message describing the issue." + } + } + }, + "examples": { + "dateRangeExceeded": { + "summary": "Date range exceeds maximum allowed", + "value": { + "message": "Bad request. Reason: Date range cannot exceed 366 days" + } + }, + "invalidGroupBy": { + "summary": "Invalid group_by parameter value", + "value": { + "message": "Value for 'group_by' not supported. Allowed: '', 'key', 'key_and_day'." + } + } + } + } + } + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/v2/admin/developer-keys": { + "post": { + "tags": [ + "AdminApi" + ], + "summary": "Create a developer key as an admin", + "operationId": "adminCreateDeveloperKey", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "label": { + "$ref": "#/components/schemas/ApiKeyLabel" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The create function returns a JSON representation of the created API key.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiKey" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + }, + "security": [ + { + "auth_header": [] + } + ] + }, + "get": { + "tags": [ + "AdminApi" + ], + "summary": "Get all developer keys as an admin", + "operationId": "adminGetDeveloperKeys", + "responses": { + "200": { + "description": "The get function returns a JSON representation of all developer API keys in the organization.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ApiKey" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/v2/admin/developer-keys/deactivate": { + "put": { + "tags": [ + "AdminApi" + ], + "summary": "Deactivate a developer key as an admin", + "operationId": "adminDeactivateDeveloperKey", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "key_id" + ], + "properties": { + "key_id": { + "$ref": "#/components/schemas/ApiKeyId" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The deactivate function returns a JSON representation of the deactivated API key.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiKey" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/v2/admin/developer-keys/label": { + "put": { + "tags": [ + "AdminApi" + ], + "summary": "Rename a developer key as an admin", + "operationId": "adminRenameDeveloperKey", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "key_id", + "label" + ], + "properties": { + "key_id": { + "$ref": "#/components/schemas/ApiKeyId" + }, + "label": { + "type": "string", + "description": "API key label.", + "example": "developer key prod" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The set label function returns a JSON representation of the renamed API key.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiKey" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/v2/admin/developer-keys/limits": { + "put": { + "tags": [ + "AdminApi" + ], + "summary": "Set developer key usage limits as an admin", + "operationId": "adminSetDeveloperKeyUsageLimits", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "key_id" + ], + "properties": { + "key_id": { + "$ref": "#/components/schemas/ApiKeyId" + }, + "characters": { + "$ref": "#/components/schemas/ApiKeyUsageCharacters" + }, + "speech_to_text_milliseconds": { + "$ref": "#/components/schemas/ApiKeyUsageSpeechToTextMilliseconds" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The set usage limits function returns a JSON representation of the modified API key.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiKey" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/v2/translate": { + "post": { + "tags": [ + "TranslateText" + ], + "summary": "Request Translation", + "operationId": "translateText", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "text", + "target_lang" + ], + "properties": { + "text": { + "description": "Text to be translated. Only UTF-8-encoded plain text is supported. The parameter may be specified\nmany times in a single request, within the request size limit (128KiB). Translations are returned\nin the same order as they are requested. Each text in the array is translated independently — texts\ndo not share context with each other.", + "type": "array", + "items": { + "type": "string", + "example": "Hello, World!" + } + }, + "source_lang": { + "$ref": "#/components/schemas/SourceLanguage" + }, + "target_lang": { + "$ref": "#/components/schemas/TargetLanguage" + }, + "context": { + "$ref": "#/components/schemas/Context" + }, + "show_billed_characters": { + "$ref": "#/components/schemas/ShowBilledCharacters" + }, + "split_sentences": { + "$ref": "#/components/schemas/SplitSentencesOption" + }, + "preserve_formatting": { + "$ref": "#/components/schemas/PreserveFormattingOption" + }, + "formality": { + "$ref": "#/components/schemas/Formality" + }, + "model_type": { + "$ref": "#/components/schemas/ModelType" + }, + "glossary_id": { + "description": "Specify the glossary to use for the translation. **Important:** This requires the `source_lang`\nparameter to be set. The language pair of the glossary has to match the language pair of the\nrequest.", + "type": "string", + "example": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7" + }, + "style_id": { + "description": "Specify the [style rule list](/api-reference/style-rules) to use for the translation. \n\n**Important:** The target language has to match the language of the style rule list. \n\n**Note:** Any request with the `style_id` parameter enabled will use `quality_optimized` models. Requests combining `style_id` and `model_type: latency_optimized` will be rejected.", + "type": "string", + "example": "7ff9bfd6-cd85-4190-8503-d6215a321519" + }, + "translation_memory_id": { + "$ref": "#/components/schemas/TranslationMemoryId" + }, + "translation_memory_threshold": { + "$ref": "#/components/schemas/TranslationMemoryThreshold" + }, + "custom_instructions": { + "description": "Specify a list of instructions to customize the translation behavior. Up to 10 custom instructions can be specified, each with a maximum of 300 characters.\n\n**Important:** The target language must be `de`, `en`, `es`, `fr`, `it`, `ja`, `ko`, `zh` or any variants of these languages.\n\n**Note:** Any request with the `custom_instructions` parameter enabled will default to use the `quality_optimized` model type. Requests combining `custom_instructions` and `model_type: latency_optimized` will be rejected.", + "type": "array", + "items": { + "type": "string", + "example": "Use a friendly, diplomatic tone" + } + }, + "tag_handling": { + "$ref": "#/components/schemas/TagHandlingOption" + }, + "tag_handling_version": { + "$ref": "#/components/schemas/TagHandlingVersionOption" + }, + "outline_detection": { + "$ref": "#/components/schemas/OutlineDetectionOption" + }, + "enable_beta_languages": { + "description": "No languages are currently in beta. This parameter is maintained for backward compatibility and has no effect.", + "type": "boolean", + "default": false + }, + "non_splitting_tags": { + "description": "Comma-separated list of XML tags which never split sentences.", + "type": "array", + "items": { + "type": "string", + "example": "non_splitting_tag" + } + }, + "splitting_tags": { + "description": "Comma-separated list of XML tags which always cause splits.", + "type": "array", + "items": { + "type": "string", + "example": "splitting_tag" + } + }, + "ignore_tags": { + "description": "Comma-separated list of XML tags that indicate text not to be translated.", + "type": "array", + "items": { + "type": "string", + "example": "ignore_tag" + } + } + } + } + }, + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "required": [ + "text", + "target_lang" + ], + "properties": { + "text": { + "description": "Text to be translated. Only UTF-8-encoded plain text is supported. The parameter may be specified many times in a single request, within the request size limit (128KiB). Translations are returned in the same order as they are requested. Each text in the array is translated independently — texts do not share context with each other.", + "type": "array", + "items": { + "type": "string", + "example": "Hello, World!" + } + }, + "source_lang": { + "$ref": "#/components/schemas/SourceLanguage" + }, + "target_lang": { + "$ref": "#/components/schemas/TargetLanguage" + }, + "context": { + "$ref": "#/components/schemas/Context" + }, + "show_billed_characters": { + "$ref": "#/components/schemas/ShowBilledCharacters" + }, + "split_sentences": { + "$ref": "#/components/schemas/SplitSentencesOption" + }, + "preserve_formatting": { + "$ref": "#/components/schemas/PreserveFormattingOptionStr" + }, + "formality": { + "$ref": "#/components/schemas/Formality" + }, + "model_type": { + "$ref": "#/components/schemas/ModelType" + }, + "glossary_id": { + "description": "Specify the glossary to use for the translation. **Important:** This requires the `source_lang`\nparameter to be set. The language pair of the glossary has to match the language pair of the\nrequest.", + "type": "string", + "example": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7" + }, + "translation_memory_id": { + "$ref": "#/components/schemas/TranslationMemoryId" + }, + "translation_memory_threshold": { + "$ref": "#/components/schemas/TranslationMemoryThreshold" + }, + "tag_handling": { + "$ref": "#/components/schemas/TagHandlingOption" + }, + "outline_detection": { + "$ref": "#/components/schemas/OutlineDetectionOptionStr" + }, + "enable_beta_languages": { + "description": "No languages are currently in Beta. This parameter is maintained for backward compatibility and has no effect. Previously enabled 81 languages that are now part of the standard language list. See the [full list](/docs/getting-started/supported-languages).", + "type": "boolean", + "default": false + }, + "non_splitting_tags": { + "description": "Comma-separated list of XML tags which never split sentences.", + "type": "array", + "items": { + "type": "string", + "example": "non_splitting_tag" + } + }, + "splitting_tags": { + "description": "Comma-separated list of XML tags which always cause splits.", + "type": "array", + "items": { + "type": "string", + "example": "splitting_tag" + } + }, + "ignore_tags": { + "description": "Comma-separated list of XML tags that indicate text not to be translated.", + "type": "array", + "items": { + "type": "string", + "example": "ignore_tag" + } + } + } + }, + "encoding": { + "text": { + "style": "form", + "explode": true + } + } + } + } + }, + "responses": { + "200": { + "description": "The translate function returns a JSON representation of the translations in the order the text parameters have been specified.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "translations": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "properties": { + "detected_source_language": { + "description": "The language detected in the source text. It reflects the value of the `source_lang` parameter, when specified.", + "type": "string", + "example": "EN" + }, + "text": { + "description": "The translated text.", + "type": "string", + "example": "Hallo, Welt!" + }, + "billed_characters": { + "description": "Number of characters counted by DeepL for billing purposes. Only present if the show_billed_characters parameter is set to true.", + "type": "integer", + "example": 42 + }, + "model_type_used": { + "description": "Indicates the translation model used. Only present if model_type parameter is included in the request.", + "type": "string", + "example": "quality_optimized" + } + } + } + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "414": { + "$ref": "#/components/responses/URITooLong" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "504": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/v2/document": { + "post": { + "tags": [ + "TranslateDocuments" + ], + "summary": "Upload and Translate a Document", + "operationId": "translateDocument", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "examples": { + "Basic": { + "summary": "Basic Document Translation", + "value": { + "target_lang": "DE", + "file": "@document.docx" + } + }, + "Glossary": { + "summary": "Using a Glossary", + "value": { + "source_lang": "EN", + "target_lang": "DE", + "file": "@document.docx", + "glossary_id": "[yourGlossaryId]" + } + } + }, + "schema": { + "type": "object", + "required": [ + "target_lang", + "file" + ], + "properties": { + "source_lang": { + "$ref": "#/components/schemas/SourceLanguage" + }, + "target_lang": { + "$ref": "#/components/schemas/TargetLanguage" + }, + "file": { + "type": "string", + "format": "binary", + "description": "The document file to be translated. The file name should be included in this part's content disposition. As an alternative, the filename parameter can be used. The following file types and extensions are supported:\n * `docx` - Microsoft Word Document\n * `pptx` - Microsoft PowerPoint Document\n * `xlsx` - Microsoft Excel Document\n * `pdf` - Portable Document Format\n * `htm / html` - HTML Document\n * `txt` - Plain Text Document\n * `xlf / xliff` - XLIFF Document, version 2.1\n * `srt` - SRT Document\n * `jpeg` / `jpg` / `png` - Image (currently in beta)" + }, + "filename": { + "type": "string", + "description": "The name of the uploaded file. Can be used as an alternative to including the file name in the file part's content disposition." + }, + "output_format": { + "type": "string", + "description": "File extension of desired format of translated file, for example: `docx`. If unspecified, by default the translated file will be in the same format as the input file.\n" + }, + "formality": { + "$ref": "#/components/schemas/Formality" + }, + "glossary_id": { + "$ref": "#/components/schemas/GlossaryId" + }, + "enable_beta_languages": { + "description": "No languages are currently in Beta. This parameter is maintained for backward compatibility and has no effect. Previously enabled 81 languages that are now part of the standard language list. See the [full list](/docs/getting-started/supported-languages).", + "type": "boolean", + "default": false + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The document function returns a JSON object containing the ID and encryption key assigned to the uploaded document. Once received by the server, uploaded documents are immediately encrypted using a uniquely generated encryption key. This key is not persistently stored on the server. Therefore, it must be stored by the client and sent back to the server with every subsequent request that refers to this particular document.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "document_id": { + "description": "A unique ID assigned to the uploaded document and the translation process. Must be used when referring to this particular document in subsequent API requests.", + "type": "string", + "example": "04DE5AD98A02647D83285A36021911C6" + }, + "document_key": { + "description": "A unique key that is used to encrypt the uploaded document as well as the resulting translation on the server side. Must be provided with every subsequent API request regarding this particular document.", + "type": "string", + "example": "0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A" + } + } + }, + "example": { + "document_id": "04DE5AD98A02647D83285A36021911C6", + "document_key": "0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "504": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/v2/document/{document_id}": { + "post": { + "tags": [ + "TranslateDocuments" + ], + "summary": "Check Document Status", + "operationId": "getDocumentStatus", + "parameters": [ + { + "$ref": "#/components/parameters/DocumentID" + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "$ref": "#/components/schemas/DocumentKey" + }, + "examples": { + "basic": { + "summary": "Basic", + "value": { + "document_key": "0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A" + } + } + } + }, + "application/json": { + "schema": { + "$ref": "#/components/schemas/DocumentKey" + } + } + } + }, + "responses": { + "200": { + "description": "The document status request returns a JSON object containing the document ID that was used in the request as well as string indicating the current status of the translation process. While the translation is running, the estimated number of seconds remaining until the process is done is also included in the response.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "document_id", + "status" + ], + "properties": { + "document_id": { + "description": "A unique ID assigned to the uploaded document and the requested translation process. The same ID that was used when requesting the translation status.", + "type": "string", + "example": "04DE5AD98A02647D83285A36021911C6" + }, + "status": { + "description": "A short description of the state the document translation process is currently in. Possible values are:\n * `queued` - the translation job is waiting in line to be processed\n * `translating` - the translation is currently ongoing\n * `done` - the translation is done and the translated document is ready for download\n * `error` - an irrecoverable error occurred while translating the document", + "type": "string", + "example": "done", + "enum": [ + "queued", + "translating", + "done", + "error" + ] + }, + "seconds_remaining": { + "description": "Estimated number of seconds until the translation is done.\nThis parameter is only included while `status` is `\"translating\"`.", + "type": "integer" + }, + "billed_characters": { + "description": "The number of characters billed to your account. The characters will only be billed after a successful download request.", + "type": "integer", + "example": 1337 + }, + "error_message": { + "description": "A short description of the error, if available.\nNote that the content is subject to change.\nThis parameter may be included if an error occurred during translation.", + "type": "string", + "example": "Only available if document status is error" + } + } + }, + "examples": { + "translating": { + "summary": "Translating", + "value": { + "document_id": "04DE5AD98A02647D83285A36021911C6", + "status": "translating", + "seconds_remaining": 20 + } + }, + "done": { + "summary": "Done", + "value": { + "document_id": "04DE5AD98A02647D83285A36021911C6", + "status": "done", + "billed_characters": 1337 + } + }, + "queued": { + "summary": "Queued", + "value": { + "document_id": "04DE5AD98A02647D83285A36021911C6", + "status": "queued" + } + }, + "error": { + "summary": "Error", + "value": { + "document_id": "04DE5AD98A02647D83285A36021911C6", + "status": "error", + "message": "Source and target language are equal." + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "504": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/v2/document/{document_id}/result": { + "post": { + "tags": [ + "TranslateDocuments" + ], + "summary": "Download Translated Document", + "operationId": "downloadDocument", + "parameters": [ + { + "$ref": "#/components/parameters/DocumentID" + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "$ref": "#/components/schemas/DocumentKey" + }, + "examples": { + "basic": { + "summary": "Basic", + "value": { + "document_key": "0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A" + } + } + } + }, + "application/json": { + "schema": { + "$ref": "#/components/schemas/DocumentKey" + } + } + } + }, + "responses": { + "200": { + "description": "The document is provided as a download. There is no other data included in the response besides the document data. The content type used in the response corresponds to the document type.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary" + }, + "examples": { + "OK": { + "summary": "OK", + "description": "binary document data" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound404DocTransDownload" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable503DocTransDownload" + }, + "504": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/v2/glossary-language-pairs": { + "get": { + "tags": [ + "ManageGlossaries" + ], + "summary": "List Language Pairs Supported by Glossaries", + "description": "Retrieve the list of language pairs supported by the glossary feature.", + "operationId": "listGlossaryLanguages", + "responses": { + "200": { + "description": "A JSON object containing the language pairs in its `supported_languages` property.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "supported_languages": { + "type": "array", + "description": "The list of supported languages", + "items": { + "type": "object", + "required": [ + "source_lang", + "target_lang" + ], + "properties": { + "source_lang": { + "description": "The language in which the source texts in the glossary are specified.", + "type": "string", + "example": "en" + }, + "target_lang": { + "description": "The language in which the target texts in the glossary are specified.", + "type": "string", + "example": "de" + } + } + } + } + } + }, + "example": { + "supported_languages": [ + { + "source_lang": "de", + "target_lang": "en" + }, + { + "source_lang": "en", + "target_lang": "de" + } + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestGlossaries" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/ForbiddenGlossaries" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "415": { + "$ref": "#/components/responses/UnsupportedMediaTypeGlossaries" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceededGlossaries" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/v3/glossaries": { + "post": { + "tags": [ + "ManageMultilingualGlossaries" + ], + "summary": "Create a Glossary", + "operationId": "createMultilingualGlossary", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateMultilingualGlossaryParameters" + }, + "examples": { + "Basic": { + "value": { + "name": "My Glossary", + "dictionaries": [ + { + "source_lang": "en", + "target_lang": "de", + "entries": "Hello\tGuten Tag", + "entries_format": "tsv" + }, + { + "source_lang": "de", + "target_lang": "en", + "entries": "Guten Tag\tHello", + "entries_format": "tsv" + } + ] + } + } + } + }, + "application/x-www-form-urlencoded": { + "schema": { + "$ref": "#/components/schemas/CreateMultilingualGlossaryParameters" + } + } + } + }, + "responses": { + "201": { + "description": "The function for creating a glossary returns a JSON object containing the ID of the newly created glossary and a boolean flag that indicates if the created glossary can already be used in translate requests.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MultilingualGlossary" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestGlossaries" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/ForbiddenGlossaries" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "415": { + "$ref": "#/components/responses/UnsupportedMediaTypeGlossaries" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceededGlossaries" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + }, + "get": { + "tags": [ + "ManageMultilingualGlossaries" + ], + "summary": "List all Glossaries", + "operationId": "listMultilingualGlossaries", + "description": "List all glossaries and their meta-information, but not the glossary entries.", + "responses": { + "200": { + "description": "JSON object containing a the glossaries.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "glossaries": { + "type": "array", + "items": { + "$ref": "#/components/schemas/MultilingualGlossary" + } + } + } + }, + "example": { + "glossaries": [ + { + "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7", + "name": "My Glossary", + "dictionaries": [ + { + "source_lang": "EN", + "target_lang": "DE", + "entry_count": 1 + }, + { + "source_lang": "DE", + "target_lang": "EN", + "entry_count": 2 + } + ], + "creation_time": "2021-08-03T14:16:18.329Z" + } + ] + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/ForbiddenGlossaries" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "415": { + "$ref": "#/components/responses/UnsupportedMediaTypeGlossaries" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceededGlossaries" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/v3/glossaries/{glossary_id}": { + "get": { + "tags": [ + "ManageMultilingualGlossaries" + ], + "summary": "Retrieve Glossary Details", + "description": "Retrieve meta information for a single glossary, omitting the glossary entries.", + "operationId": "getMultilingualGlossary", + "parameters": [ + { + "$ref": "#/components/parameters/GlossaryID" + } + ], + "responses": { + "200": { + "description": "JSON object containing the glossary meta-information.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MultilingualGlossary" + }, + "example": { + "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7", + "name": "My Glossary", + "dictionaries": [ + { + "source_lang": "EN", + "target_lang": "DE", + "entry_count": 1 + }, + { + "source_lang": "DE", + "target_lang": "EN", + "entry_count": 2 + } + ], + "creation_time": "2021-08-03T14:16:18.429Z" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/ForbiddenGlossaries" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "415": { + "$ref": "#/components/responses/UnsupportedMediaTypeGlossaries" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceededGlossaries" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + }, + "patch": { + "tags": [ + "ManageMultilingualGlossaries" + ], + "summary": "Edit glossary details", + "description": "Edit glossary details, such as name or a dictionary for a source and target language.", + "operationId": "patchMultilingualGlossary", + "parameters": [ + { + "$ref": "#/components/parameters/GlossaryID" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PatchMultilingualGlossaryParameters" + }, + "examples": { + "Basic": { + "value": { + "name": "My Glossary", + "dictionaries": [ + { + "source_lang": "en", + "target_lang": "de", + "entries": "Hello\tGuten Tag", + "entries_format": "tsv" + } + ] + } + } + } + }, + "application/x-www-form-urlencoded": { + "schema": { + "$ref": "#/components/schemas/PatchMultilingualGlossaryParameters" + } + } + } + }, + "responses": { + "200": { + "description": "JSON object containing the glossary meta-information.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MultilingualGlossary" + }, + "example": { + "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7", + "name": "My Glossary", + "dictionaries": [ + { + "source_lang": "EN", + "target_lang": "DE", + "creation_time": "2021-08-03T14:16:18.329Z", + "entry_count": 1 + }, + { + "source_lang": "DE", + "target_lang": "EN", + "creation_time": "2021-08-03T14:16:18.429Z", + "entry_count": 2 + } + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestGlossaries" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/ForbiddenGlossaries" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "415": { + "$ref": "#/components/responses/UnsupportedMediaTypeGlossaries" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceededGlossaries" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + }, + "delete": { + "tags": [ + "ManageMultilingualGlossaries" + ], + "summary": "Delete a Glossary", + "description": "Deletes the specified glossary.", + "operationId": "deleteMultilingualGlossary", + "parameters": [ + { + "$ref": "#/components/parameters/GlossaryID" + } + ], + "responses": { + "204": { + "description": "Returns no content upon success." + }, + "400": { + "$ref": "#/components/responses/BadRequestGlossaries" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/ForbiddenGlossaries" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "415": { + "$ref": "#/components/responses/UnsupportedMediaTypeGlossaries" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceededGlossaries" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/v3/glossaries/{glossary_id}/entries": { + "get": { + "tags": [ + "ManageMultilingualGlossaries" + ], + "summary": "Retrieve Glossary Entries", + "operationId": "getMultilingualGlossaryEntries", + "description": "List the entries of a single glossary in tsv format.", + "parameters": [ + { + "$ref": "#/components/parameters/GlossaryID" + }, + { + "name": "source_lang", + "in": "query", + "required": true, + "schema": { + "$ref": "#/components/schemas/GlossarySourceLanguage" + } + }, + { + "name": "target_lang", + "in": "query", + "required": true, + "schema": { + "$ref": "#/components/schemas/GlossaryTargetLanguage" + } + } + ], + "responses": { + "200": { + "description": "The entries in tsv, wrapped in a JSON object.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GlossaryDictionary" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestGlossaries" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/ForbiddenGlossaries" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "415": { + "$ref": "#/components/responses/UnsupportedMediaTypeGlossaries" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceededGlossaries" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/v3/glossaries/{glossary_id}/dictionaries": { + "delete": { + "tags": [ + "ManageMultilingualGlossaries" + ], + "summary": "Deletes the dictionary associated with the given language pair with the given glossary ID.", + "operationId": "deleteDictionary", + "parameters": [ + { + "$ref": "#/components/parameters/GlossaryID" + }, + { + "name": "source_lang", + "in": "query", + "required": true, + "schema": { + "$ref": "#/components/schemas/GlossarySourceLanguage" + } + }, + { + "name": "target_lang", + "in": "query", + "required": true, + "schema": { + "$ref": "#/components/schemas/GlossaryTargetLanguage" + } + } + ], + "responses": { + "204": { + "description": "Returns no content upon success." + }, + "400": { + "$ref": "#/components/responses/BadRequestGlossaries" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/ForbiddenGlossaries" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "415": { + "$ref": "#/components/responses/UnsupportedMediaTypeGlossaries" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceededGlossaries" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + }, + "put": { + "tags": [ + "ManageMultilingualGlossaries" + ], + "summary": "Replaces or creates a dictionary in the glossary with the specified entries.", + "operationId": "replaceDictionary", + "parameters": [ + { + "$ref": "#/components/parameters/GlossaryID" + } + ], + "requestBody": { + "description": "The dictionary to insert into (or overwrite in) the multilingual glossary.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MultilingualGlossaryEntries" + } + } + } + }, + "responses": { + "200": { + "description": "JSON object containing the dictionary meta-information.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MultilingualGlossaryEntriesInformation" + }, + "example": { + "source_lang": "EN", + "target_lang": "DE", + "entry_count": 1 + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestGlossaries" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/ForbiddenGlossaries" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "415": { + "$ref": "#/components/responses/UnsupportedMediaTypeGlossaries" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceededGlossaries" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/v2/glossaries": { + "post": { + "tags": [ + "ManageGlossaries" + ], + "summary": "Create a Glossary", + "operationId": "createGlossary", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateGlossaryParameters" + }, + "examples": { + "Basic": { + "value": { + "name": "My Glossary", + "source_lang": "en", + "target_lang": "de", + "entries": "Hello\tGuten Tag", + "entries_format": "tsv" + } + } + } + }, + "application/x-www-form-urlencoded": { + "schema": { + "$ref": "#/components/schemas/CreateGlossaryParameters" + } + } + } + }, + "responses": { + "201": { + "description": "The function for creating a glossary returns a JSON object containing the ID of the newly created glossary and a boolean flag that indicates if the created glossary can already be used in translate requests.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MonolingualGlossary" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestGlossaries" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/ForbiddenGlossaries" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "415": { + "$ref": "#/components/responses/UnsupportedMediaTypeGlossaries" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + }, + "get": { + "tags": [ + "ManageGlossaries" + ], + "summary": "List all Glossaries", + "operationId": "listGlossaries", + "description": "List all glossaries and their meta-information, but not the glossary entries.", + "responses": { + "200": { + "description": "JSON object containing a the glossaries.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "glossaries": { + "type": "array", + "items": { + "$ref": "#/components/schemas/MonolingualGlossary" + } + } + } + }, + "example": { + "glossaries": [ + { + "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7", + "name": "My Glossary", + "ready": true, + "source_lang": "EN", + "target_lang": "DE", + "creation_time": "2021-08-03T14:16:18.329Z", + "entry_count": 1 + } + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestGlossaries" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/ForbiddenGlossaries" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "415": { + "$ref": "#/components/responses/UnsupportedMediaTypeGlossaries" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/v2/glossaries/{glossary_id}": { + "get": { + "tags": [ + "ManageGlossaries" + ], + "summary": "Retrieve Glossary Details", + "description": "Retrieve meta information for a single glossary, omitting the glossary entries.", + "operationId": "getGlossary", + "parameters": [ + { + "$ref": "#/components/parameters/GlossaryID" + } + ], + "responses": { + "200": { + "description": "JSON object containing the glossary meta-information.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MonolingualGlossary" + }, + "example": { + "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7", + "name": "My Glossary", + "ready": true, + "source_lang": "EN", + "target_lang": "DE", + "creation_time": "2021-08-03T14:16:18.329Z", + "entry_count": 1 + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestGlossaries" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/ForbiddenGlossaries" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "415": { + "$ref": "#/components/responses/UnsupportedMediaTypeGlossaries" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + }, + "delete": { + "tags": [ + "ManageGlossaries" + ], + "summary": "Delete a Glossary", + "description": "Deletes the specified glossary.", + "operationId": "deleteGlossary", + "parameters": [ + { + "$ref": "#/components/parameters/GlossaryID" + } + ], + "responses": { + "204": { + "description": "Returns no content upon success." + }, + "400": { + "$ref": "#/components/responses/BadRequestGlossaries" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/ForbiddenGlossaries" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "415": { + "$ref": "#/components/responses/UnsupportedMediaTypeGlossaries" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/v2/glossaries/{glossary_id}/entries": { + "get": { + "tags": [ + "ManageGlossaries" + ], + "summary": "Retrieve Glossary Entries", + "operationId": "getGlossaryEntries", + "description": "List the entries of a single glossary in the format specified by the `Accept` header.", + "parameters": [ + { + "$ref": "#/components/parameters/GlossaryID" + }, + { + "name": "Accept", + "in": "header", + "schema": { + "type": "string", + "enum": [ + "text/tab-separated-values" + ], + "default": "text/tab-separated-values" + }, + "description": "The requested format of the returned glossary entries. Currently, supports only `text/tab-separated-values`.", + "examples": { + "tsv": { + "summary": "Tab-separated Values", + "value": { + "in": "header", + "Accept": "text/tab-separated-values" + } + } + } + } + ], + "responses": { + "200": { + "description": "The entries in the requested format.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "text/tab-separated-values": { + "example": "Hello!\tGuten Tag!" + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestGlossaries" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/ForbiddenGlossaries" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "415": { + "$ref": "#/components/responses/UnsupportedMediaTypeGlossaries" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/v2/write/rephrase": { + "post": { + "tags": [ + "RephraseText" + ], + "summary": "Request text improvement", + "operationId": "rephraseText", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "text" + ], + "properties": { + "text": { + "description": "Text to be improved. Only UTF-8-encoded plain text is supported. Improvements are returned in the same order as they are requested.", + "type": "array", + "items": { + "type": "string", + "example": "this is a example sentence to imprve" + } + }, + "target_lang": { + "$ref": "#/components/schemas/TargetLanguageWrite" + }, + "writing_style": { + "$ref": "#/components/schemas/WritingStyle" + }, + "tone": { + "$ref": "#/components/schemas/WritingTone" + } + } + } + }, + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "required": [ + "text" + ], + "properties": { + "text": { + "description": "Text to be improved. Only UTF-8-encoded plain text is supported. Improvements are returned in the same order as they are requested.", + "type": "array", + "items": { + "type": "string", + "example": "this is a example sentence to imprve" + } + }, + "target_lang": { + "$ref": "#/components/schemas/TargetLanguageWrite" + }, + "writing_style": { + "$ref": "#/components/schemas/WritingStyle" + }, + "tone": { + "$ref": "#/components/schemas/WritingTone" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Successful text improvement.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "improvements": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "properties": { + "detected_source_language": { + "description": "The language detected in the source text.", + "type": "string", + "example": "en" + }, + "text": { + "description": "The improved text.", + "type": "string", + "example": "This is a sample sentence to improve." + } + } + } + } + } + } + } + } + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/v2/usage": { + "get": { + "tags": [ + "MetaInformation" + ], + "summary": "Check Usage and Limits", + "operationId": "getUsage", + "responses": { + "200": { + "description": "The account's usage and limits.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsageResponse" + }, + "examples": { + "free": { + "summary": "Response for API users not on the Pro plan", + "value": { + "character_count": 180118, + "character_limit": 1250000 + } + }, + "pro": { + "summary": "Response for API Pro users", + "value": { + "character_count": 5947223, + "character_limit": 1000000000000, + "products": [ + { + "product_type": "write", + "billing_unit": "characters", + "api_key_unit_count": 0, + "account_unit_count": 5643, + "api_key_character_count": 0, + "character_count": 5643 + }, + { + "product_type": "translate", + "billing_unit": "characters", + "api_key_unit_count": 636, + "account_unit_count": 5941580, + "api_key_character_count": 636, + "character_count": 5941580 + }, + { + "product_type": "speech_to_text", + "billing_unit": "milliseconds", + "api_key_unit_count": 1800000, + "account_unit_count": 1800000, + "api_key_character_count": 0, + "character_count": 0 + } + ], + "api_key_character_count": 636, + "api_key_character_limit": 1000000000000, + "speech_to_text_milliseconds_count": 1800000, + "speech_to_text_milliseconds_limit": 36000000, + "start_time": "2025-05-13T09:18:42Z", + "end_time": "2025-06-13T09:18:42Z" + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "504": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/v2/languages": { + "get": { + "tags": [ + "MetaInformation" + ], + "summary": "Retrieve Supported Languages", + "operationId": "getLanguages", + "parameters": [ + { + "name": "type", + "in": "query", + "schema": { + "type": "string", + "enum": [ + "source", + "target" + ], + "default": "source" + }, + "description": "Supported values are \"source\" or \"target\". If type parameter is not included, defaults to \"source\".", + "examples": { + "target": { + "summary": "Target Languages", + "value": { + "in": "query", + "type": "target" + } + } + } + } + ], + "responses": { + "200": { + "description": "JSON array where each item represents a supported language.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object", + "required": [ + "language", + "name" + ], + "properties": { + "language": { + "description": "The language code of the given language.", + "type": "string", + "example": "DE" + }, + "name": { + "description": "Name of the language in English.", + "type": "string", + "example": "German" + }, + "supports_formality": { + "description": "Denotes formality support in case of a target language listing.", + "type": "boolean", + "example": true + } + } + } + }, + "example": [ + { + "language": "AR", + "name": "Arabic" + }, + { + "language": "BG", + "name": "Bulgarian" + }, + { + "language": "CS", + "name": "Czech" + }, + { + "language": "DA", + "name": "Danish" + }, + { + "language": "DE", + "name": "German" + }, + { + "language": "EL", + "name": "Greek" + }, + { + "language": "EN", + "name": "English" + }, + { + "language": "ES", + "name": "Spanish" + }, + { + "language": "ET", + "name": "Estonian" + }, + { + "language": "FI", + "name": "Finnish" + }, + { + "language": "FR", + "name": "French" + }, + { + "language": "HE", + "name": "Hebrew" + }, + { + "language": "HU", + "name": "Hungarian" + }, + { + "language": "ID", + "name": "Indonesian" + }, + { + "language": "IT", + "name": "Italian" + }, + { + "language": "JA", + "name": "Japanese" + }, + { + "language": "KO", + "name": "Korean" + }, + { + "language": "LT", + "name": "Lithuanian" + }, + { + "language": "LV", + "name": "Latvian" + }, + { + "language": "NB", + "name": "Norwegian" + }, + { + "language": "NL", + "name": "Dutch" + }, + { + "language": "PL", + "name": "Polish" + }, + { + "language": "PT", + "name": "Portuguese" + }, + { + "language": "RO", + "name": "Romanian" + }, + { + "language": "RU", + "name": "Russian" + }, + { + "language": "SK", + "name": "Slovak" + }, + { + "language": "SL", + "name": "Slovenian" + }, + { + "language": "SV", + "name": "Swedish" + }, + { + "language": "TH", + "name": "Thai" + }, + { + "language": "TR", + "name": "Turkish" + }, + { + "language": "UK", + "name": "Ukrainian" + }, + { + "language": "VI", + "name": "Vietnamese" + }, + { + "language": "ZH", + "name": "Chinese" + } + ] + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "504": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/v3/languages/products": { + "get": { + "tags": [ + "MetaInformation", + "beta" + ], + "x-beta": true, + "summary": "Retrieve Language Products", + "operationId": "getLanguageProducts", + "description": "Returns all DeepL API products, including the API endpoints they expose, and the features they support.\n\nFor each feature, the response indicates which languages must support it for the feature to be\navailable — source only (`required_on_source`), target only (`required_on_target`), or both.\nThis allows clients to determine feature availability for a language pair by checking the\nappropriate language's `features` array returned by `GET /v3/languages`.", + "responses": { + "200": { + "description": "JSON array where each item represents a DeepL API product.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "endpoints", + "features" + ], + "properties": { + "name": { + "description": "The product identifier.", + "type": "string", + "enum": [ + "translate_text", + "translate_document", + "glossary", + "voice", + "write", + "style_rules" + ], + "example": "translate_text" + }, + "endpoints": { + "description": "API endpoints associated with this product.", + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "v2/translate" + ] + }, + "features": { + "description": "Features supported by this product. Each feature indicates which languages\nmust support it for the feature to be available — source, target, or both.", + "type": "array", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "description": "The feature identifier, corresponding to values in the `features` array returned by `GET /v3/languages`.", + "type": "string", + "enum": [ + "formality", + "custom_instructions", + "tag_handling", + "glossary", + "writing_style", + "tone" + ] + }, + "required_on_source": { + "description": "If `true`, the source language must support this feature for it to be available. Defaults to `false` if absent.", + "type": "boolean" + }, + "required_on_target": { + "description": "If `true`, the target language must support this feature for it to be available. Defaults to `false` if absent.", + "type": "boolean" + } + } + } + } + } + } + }, + "example": [ + { + "name": "translate_text", + "endpoints": [ + "v2/translate" + ], + "features": [ + { + "name": "formality", + "required_on_target": true + }, + { + "name": "custom_instructions", + "required_on_target": true + }, + { + "name": "tag_handling", + "required_on_source": true, + "required_on_target": true + }, + { + "name": "glossary", + "required_on_source": true, + "required_on_target": true + } + ] + }, + { + "name": "voice", + "endpoints": [ + "v3/voice/realtime" + ], + "features": [ + { + "name": "glossary", + "required_on_source": true, + "required_on_target": true + } + ] + }, + { + "name": "style_rules", + "endpoints": [ + "v3/style_rules" + ], + "features": [] + } + ] + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/v3/languages": { + "get": { + "tags": [ + "MetaInformation", + "beta" + ], + "x-beta": true, + "summary": "Retrieve Languages", + "operationId": "getLanguages", + "description": "Returns languages supported by the specified DeepL API product. Each language indicates whether it can\nbe used as a source language, a target language, or both, along with the features it supports for that\nproduct.", + "parameters": [ + { + "name": "product", + "in": "query", + "required": true, + "schema": { + "type": "string", + "enum": [ + "translate_text", + "translate_document", + "glossary", + "voice", + "write", + "style_rules" + ] + }, + "example": "translate_text", + "description": "The product to retrieve languages for. Supported values: `translate_text`, `translate_document`,\n`glossary`, `voice`, `write`, `style_rules`." + } + ], + "responses": { + "200": { + "description": "JSON array where each item represents a supported language.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object", + "required": [ + "lang", + "name", + "usable_as_source", + "usable_as_target", + "features" + ], + "properties": { + "lang": { + "description": "The language code (BCP 47).", + "type": "string", + "example": "de" + }, + "name": { + "description": "Name of the language in English.", + "type": "string", + "example": "German" + }, + "usable_as_source": { + "description": "Whether this language can be used as a source language with the specified product.", + "type": "boolean" + }, + "usable_as_target": { + "description": "Whether this language can be used as a target language with the specified product.", + "type": "boolean" + }, + "features": { + "description": "Features supported for this language with the specified product. Always present;\nempty array if no optional features are supported. Consult `/v3/languages/products`\nto determine whether a feature must be present on the source language, target language,\nor both for a given product.", + "type": "array", + "items": { + "type": "string", + "enum": [ + "formality", + "custom_instructions", + "tag_handling", + "glossary", + "writing_style", + "tone" + ] + }, + "example": [ + "formality", + "tag_handling", + "glossary" + ] + } + } + } + }, + "examples": { + "translateTextLanguages": { + "summary": "Languages for text translation", + "value": [ + { + "lang": "de", + "name": "German", + "usable_as_source": true, + "usable_as_target": true, + "features": [ + "formality", + "tag_handling", + "glossary" + ] + }, + { + "lang": "en", + "name": "English", + "usable_as_source": true, + "usable_as_target": false, + "features": [ + "tag_handling", + "glossary" + ] + }, + { + "lang": "en-US", + "name": "English (American)", + "usable_as_source": false, + "usable_as_target": true, + "features": [ + "tag_handling", + "glossary" + ] + } + ] + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/v3/translation_memories": { + "get": { + "tags": [ + "TranslationMemories" + ], + "summary": "List translation memories", + "operationId": "listTranslationMemories", + "description": "Retrieve a list of translation memories associated with the authenticated account.", + "parameters": [ + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 0 + }, + "description": "The index of the first page to return. Use with `page_size` to get the next page of translation memories." + }, + { + "name": "page_size", + "in": "query", + "schema": { + "type": "integer", + "default": 10, + "minimum": 1, + "maximum": 25 + }, + "description": "The maximum number of translation memories to return." + } + ], + "responses": { + "200": { + "description": "Returns a list of translation memories.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "translation_memories": { + "type": "array", + "items": { + "$ref": "#/components/schemas/TranslationMemory" + } + }, + "total_count": { + "type": "integer", + "description": "The total number of translation memories available.", + "example": 2 + } + } + }, + "examples": { + "Basic": { + "value": { + "translation_memories": [ + { + "translation_memory_id": "a74d88fb-ed2a-4943-a664-a4512398b994", + "name": "Legal", + "source_language": "en", + "target_languages": [ + "es", + "de" + ], + "segment_count": 3542 + }, + { + "translation_memory_id": "855d36ab-6112-4ef5-8868-0d69bc4d826a", + "name": "Medical terms", + "source_language": "de", + "target_languages": [ + "fr", + "ja", + "zh" + ], + "segment_count": 23 + } + ], + "total_count": 2 + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/v3/style_rules": { + "get": { + "summary": "Retrieve style rule lists", + "operationId": "getStyleRuleLists", + "parameters": [ + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 0 + }, + "description": "The index of the first page to return. Use with `page_size` to get the next page of rule lists" + }, + { + "name": "page_size", + "in": "query", + "schema": { + "type": "integer", + "default": 10, + "minimum": 1, + "maximum": 25 + }, + "description": "The maximum number of style rule lists to return." + }, + { + "name": "detailed", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Determines if the rule list's `configured_rules` and `custom_instructions` should be included in the response body." + } + ], + "responses": { + "200": { + "description": "JSON object containing the style rule lists.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "style_rules": { + "type": "array", + "items": { + "$ref": "#/components/schemas/StyleRuleList" + } + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + } + }, + "security": [ + { + "auth_header": [] + } + ] + }, + "post": { + "summary": "Create a style rule list", + "operationId": "createStyleRuleList", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "name", + "language" + ], + "properties": { + "name": { + "$ref": "#/components/schemas/StyleRuleName" + }, + "language": { + "$ref": "#/components/schemas/StyleRuleLanguage" + }, + "configured_rules": { + "$ref": "#/components/schemas/ConfiguredRules" + }, + "custom_instructions": { + "type": "array", + "description": "Array of custom instruction objects", + "maxItems": 200, + "items": { + "type": "object", + "required": [ + "label", + "prompt" + ], + "properties": { + "label": { + "type": "string", + "description": "Label for the custom instruction" + }, + "prompt": { + "type": "string", + "description": "Instruction text", + "maxLength": 300 + }, + "source_language": { + "type": "string", + "description": "Optional source language code" + } + } + } + } + } + }, + "example": { + "name": "My style rules", + "language": "de", + "configured_rules": { + "style_and_tone": { + "abbreviations": "use_abbreviations_and_symbols", + "short_vs_long_words": "use_short_words" + }, + "punctuation": { + "apostrophe": "use_curly_apostrophes" + } + }, + "custom_instructions": [ + { + "label": "Currency custom instruction", + "prompt": "Have currency symbols before the numerical value (e.g. $100, €100)", + "source_language": "en" + } + ] + } + } + } + }, + "responses": { + "201": { + "description": "Style rule list created successfully", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StyleRuleList" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/v3/style_rules/{style_id}": { + "get": { + "summary": "Get a style rule list", + "operationId": "getStyleRuleList", + "parameters": [ + { + "name": "style_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the style rule list" + } + ], + "responses": { + "200": { + "description": "Style rule list details", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StyleRuleList" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + } + }, + "security": [ + { + "auth_header": [] + } + ] + }, + "patch": { + "summary": "Update a style rule list's name", + "operationId": "updateStyleRuleList", + "parameters": [ + { + "name": "style_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the style rule list" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "$ref": "#/components/schemas/StyleRuleName" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Style rule list updated successfully", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StyleRuleList" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + } + }, + "security": [ + { + "auth_header": [] + } + ] + }, + "delete": { + "summary": "Delete a style rule list", + "operationId": "deleteStyleRuleList", + "parameters": [ + { + "name": "style_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the style rule list" + } + ], + "responses": { + "204": { + "description": "Style rule list deleted successfully", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/v3/style_rules/{style_id}/configured_rules": { + "put": { + "summary": "Replace configured rules for a style rule list", + "operationId": "updateStyleRuleConfiguredRules", + "parameters": [ + { + "name": "style_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the style rule list" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConfiguredRules" + }, + "example": { + "dates_and_times": { + "calendar_era": "use_bc_and_ad" + }, + "punctuation": { + "periods_in_academic_degrees": "do_not_use" + } + } + } + } + }, + "responses": { + "200": { + "description": "Configured rules updated successfully", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StyleRuleList" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/v3/style_rules/{style_id}/custom_instructions": { + "post": { + "summary": "Create a custom instruction", + "operationId": "createCustomInstruction", + "parameters": [ + { + "name": "style_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the style rule list" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "label", + "prompt" + ], + "properties": { + "label": { + "type": "string", + "description": "Label for the custom instruction", + "maxLength": 100 + }, + "prompt": { + "type": "string", + "description": "Instruction text", + "maxLength": 300 + }, + "source_language": { + "type": "string", + "description": "Optional source language code" + } + } + }, + "example": { + "label": "Currency custom instruction", + "prompt": "Have currency symbols before the numerical value (e.g. $100, €100)" + } + } + } + }, + "responses": { + "201": { + "description": "Custom instruction created successfully", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomInstruction" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/v3/style_rules/{style_id}/custom_instructions/{instruction_id}": { + "get": { + "summary": "Get a custom instruction", + "operationId": "getCustomInstruction", + "parameters": [ + { + "name": "style_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the style rule list" + }, + { + "name": "instruction_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the custom instruction" + } + ], + "responses": { + "200": { + "description": "Custom instruction details", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomInstruction" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + } + }, + "security": [ + { + "auth_header": [] + } + ] + }, + "put": { + "summary": "Replace a custom instruction", + "operationId": "updateCustomInstruction", + "parameters": [ + { + "name": "style_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the style rule list" + }, + { + "name": "instruction_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the custom instruction" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "label", + "prompt" + ], + "properties": { + "label": { + "type": "string", + "description": "Updated label for the custom instruction", + "maxLength": 100 + }, + "prompt": { + "type": "string", + "description": "Updated instruction text", + "maxLength": 300 + }, + "source_language": { + "type": "string", + "description": "Optional source language code" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Custom instruction updated successfully", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomInstruction" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + } + }, + "security": [ + { + "auth_header": [] + } + ] + }, + "delete": { + "summary": "Delete a custom instruction", + "operationId": "deleteCustomInstruction", + "parameters": [ + { + "name": "style_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the style rule list" + }, + { + "name": "instruction_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the custom instruction" + } + ], + "responses": { + "204": { + "description": "Custom instruction deleted successfully", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/v3/voice/realtime": { + "servers": [ + { + "url": "https://api.deepl.com", + "description": "Override base path for all operations with the /v3/voice path" + } + ], + "post": { + "tags": [ + "VoiceAPI" + ], + "summary": "Get Streaming URL", + "operationId": "getVoiceStreamingUrl", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "source_media_content_type" + ], + "properties": { + "message_format": { + "$ref": "#/components/schemas/VoiceMessageFormat" + }, + "source_media_content_type": { + "$ref": "#/components/schemas/VoiceSourceMediaContentType" + }, + "source_language": { + "$ref": "#/components/schemas/VoiceSourceLanguage" + }, + "source_language_mode": { + "$ref": "#/components/schemas/VoiceSourceLanguageMode" + }, + "target_languages": { + "$ref": "#/components/schemas/VoiceTargetLanguages" + }, + "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": { + "$ref": "#/components/schemas/VoiceFormality" + } + } + }, + "examples": { + "basic": { + "summary": "Basic configuration", + "value": { + "source_media_content_type": "audio/ogg; codecs=opus", + "source_language": "en", + "source_language_mode": "auto", + "target_languages": [ + "de", + "fr", + "es" + ], + "message_format": "json" + } + }, + "with_glossary": { + "summary": "With glossary and formality", + "value": { + "source_media_content_type": "audio/pcm; encoding=s16le; rate=16000", + "source_language": "en", + "source_language_mode": "fixed", + "target_languages": [ + "de", + "fr" + ], + "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.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VoiceStreamingResponse" + }, + "example": { + "streaming_url": "wss://api.deepl.com/v3/voice/realtime/connect", + "token": "VGhpcyBpcyBhIGZha2UgdG9rZW4K", + "session_id": "4f911080-cfe2-41d4-8269-0e6ec15a0354" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + } + }, + "security": [ + { + "auth_header": [] + } + ] + }, + "get": { + "tags": [ + "VoiceAPI" + ], + "summary": "Request Reconnection", + "operationId": "requestReconnection", + "parameters": [ + { + "name": "token", + "in": "query", + "required": true, + "description": "The latest ephemeral token obtained for the stream.", + "schema": { + "type": "string" + }, + "example": "VGhpcyBpcyBhIGZha2UgdG9rZW4K" + } + ], + "responses": { + "200": { + "description": "Successfully obtained streaming URL and reconnection token.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VoiceStreamingResponse" + }, + "example": { + "streaming_url": "wss://api.deepl.com/v3/voice/realtime/connect", + "token": "VGhpcyBpcyBhIGZha2UgdG9rZW4K", + "session_id": "4f911080-cfe2-41d4-8269-0e6ec15a0354" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + } + }, + "components": { + "headers": { + "X-Trace-ID": { + "description": "A unique identifier for the request that can be included in bug reports to DeepL support.", + "schema": { + "type": "string" + }, + "example": "501c3d93cc0c4f11ae2f60a226c2f0f0" + } + }, + "parameters": { + "DocumentID": { + "name": "document_id", + "description": "The document ID that was sent to the client when the document was uploaded to the API.", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "example": "04DE5AD98A02647D83285A36021911C6" + }, + "GlossaryID": { + "name": "glossary_id", + "description": "A unique ID assigned to the glossary.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + "SourceLanguage": { + "name": "source_lang", + "in": "query", + "schema": { + "$ref": "#/components/schemas/SourceLanguage" + } + }, + "TargetLanguage": { + "name": "target_lang", + "in": "query", + "required": true, + "schema": { + "$ref": "#/components/schemas/TargetLanguage" + } + } + }, + "responses": { + "BadRequest": { + "description": "Bad request. Please check error message and your parameters." + }, + "BadRequestGlossaries": { + "description": "Bad request. Please check error message and your parameters.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "message": { + "description": "Generic description of the error.", + "type": "string" + }, + "detail": { + "description": "More specific description of the error.", + "type": "string" + } + } + }, + "example": { + "message": "Invalid glossary entries provided", + "detail": "Key with the index 1 (starting at position 13) duplicates key with the index 0 (starting at position 0)" + } + } + } + }, + "Unauthorized": { + "description": "Authorization failed. Please supply a valid `DeepL-Auth-Key` via the `Authorization` header." + }, + "Forbidden": { + "description": "Authorization failed. Please supply a valid `DeepL-Auth-Key` via the `Authorization` header." + }, + "ForbiddenGlossaries": { + "description": "Forbidden. The access to the requested resource is denied, because of insufficient access rights." + }, + "NotFound": { + "description": "The requested resource could not be found." + }, + "NotFound404DocTransDownload": { + "description": "Trying to download a document using a non-existing document ID or the wrong document key will result in a 404 error. As stated above, documents can only be downloaded once before they are deleted from the server and their document ID is invalidated.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DocumentTranslationError" + }, + "examples": { + "NotFound": { + "summary": "Not Found", + "value": { + "message": "Document not found" + } + } + } + } + } + }, + "PayloadTooLarge": { + "description": "The request size exceeds the limit." + }, + "URITooLong": { + "description": "The request URL is too long. You can avoid this error by using a POST request instead of a GET request, and sending the parameters in the HTTP body." + }, + "UnsupportedMediaTypeGlossaries": { + "description": "The requested entries format specified in the `Accept` header is not supported." + }, + "TooManyRequests": { + "description": "Too many requests. Please wait and resend your request." + }, + "QuotaExceeded": { + "description": "Quota exceeded. The character limit has been reached." + }, + "QuotaExceededGlossaries": { + "description": "Quota exceeded. Too many requests were made to the glossary endpoints recently." + }, + "InternalServerError": { + "description": "Internal error." + }, + "ServiceUnavailable": { + "description": "Resource currently unavailable. Try again later." + }, + "ServiceUnavailable503DocTransDownload": { + "description": "A 503 result will be returned if the user tries to download a translated document that is currently being processed and is not yet ready for download.\nPlease make sure to check that the document status is 'done' before trying to send a download request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DocumentTranslationError" + }, + "examples": { + "AlreadyDownloaded": { + "summary": "Already Downloaded", + "value": { + "message": "Document already downloaded" + } + } + } + } + } + } + }, + "securitySchemes": { + "auth_header": { + "type": "apiKey", + "description": "Authentication with `Authorization` header and `DeepL-Auth-Key` authentication scheme. Example: `DeepL-Auth-Key `\n", + "name": "Authorization", + "in": "header", + "x-default": "DeepL-Auth-Key " + } + }, + "schemas": { + "ApiKeyId": { + "description": "API key ID. Consists of two valid GUIDs separated by a colon.", + "type": "string", + "example": "ca7d5694-96eb-4263-a9a4-7f7e4211529e:20c2abcf-4c3c-4cd6-8ae8-8bd2a7d4da38" + }, + "ApiKeyLabel": { + "description": "API key label. The default value is `DeepL API Key`.", + "type": "string", + "example": "developer key prod" + }, + "ApiKeyUsageCharacters": { + "description": "Restricts the number of total characters (across text translation, document translation, and text improvement) that can be consumed by an API key in a one-month usage period.\n\nSetting the limit to `0` means the API key will not be able to consume characters.\nSetting the limit to `null` disables the limit, effectively allowing unlimited usage.\n", + "type": "number", + "example": 5000 + }, + "ApiKeyUsageSpeechToTextMilliseconds": { + "description": "Restricts the number of milliseconds of speech-to-text that can be consumed by an API key in a one-month usage period.\nSetting the limit to `0` means the API key will not be able to consume speech-to-text milliseconds.\nSetting the limit to `null` disables the limit, effectively allowing unlimited usage.\n", + "type": "number", + "example": 3600000 + }, + "ApiKey": { + "description": "The API key.", + "type": "object", + "properties": { + "key_id": { + "$ref": "#/components/schemas/ApiKeyId" + }, + "label": { + "$ref": "#/components/schemas/ApiKeyLabel" + }, + "creation_time": { + "description": "Timestamp when the key was created (ISO 8601 format)", + "type": "string", + "example": "2025-07-08T08:15:29.362Z" + }, + "deactivated_time": { + "description": "Timestamp when the key was deactivated (ISO 8601 format). The default value is `null`.", + "type": "string", + "example": "2025-07-09T08:15:29.362Z" + }, + "is_deactivated": { + "description": "Flag indicating whether the API key is deactivated. The default value is `false`.", + "type": "boolean", + "example": true + }, + "usage_limits": { + "description": "Usage limits for the API key.", + "type": "object", + "properties": { + "characters": { + "$ref": "#/components/schemas/ApiKeyUsageCharacters" + }, + "speech_to_text_milliseconds": { + "$ref": "#/components/schemas/ApiKeyUsageSpeechToTextMilliseconds" + } + } + } + } + }, + "ConfiguredRules": { + "description": "The enabled rules for the style rule list including what option was selected for each rule. This schema combines rules from all supported languages.", + "type": "object", + "properties": { + "dates_and_times": { + "type": "object", + "properties": { + "calendar_era": { + "type": "string", + "description": "Formatting options for Calendar Era", + "enum": [ + "use_bc_and_ad", + "use_bce_and_ce" + ] + }, + "centuries": { + "type": "string", + "description": "Formatting options for Centuries", + "enum": [ + "spell_out", + "use_arabic_numerals", + "use_numerals", + "use_roman_numerals" + ] + }, + "date_format": { + "type": "string", + "description": "Formatting options for Date Format", + "enum": [ + "use_dd_period_mm_period_yy_with_leading_zeros_for_single_digit_days_and_months", + "use_dd_period_mm_period_yyyy", + "use_dd_period_mm_period_yyyy_with_leading_zeros_for_single_digit_days_and_months", + "use_dd_period_space_abbreviated_month_yyyy_with_abbreviations_jan_period_feb_period_mrz_period_apr_period_mai_jun_period_jul_period_aug_period_sep_period_okt_period_nov_period_dez_period_without_leading_zeros_for_single_digit_days", + "use_dd_period_space_abbreviated_month_yyyy_with_abbreviations_jan_period_febr_period_maerz_apr_period_mai_juni_juli_aug_period_sept_period_okt_period_nov_period_dez_period_without_leading_zeros_for_single_digit_days", + "use_dd_period_space_month_yyyy_without_leading_zeros_for_single_digit_days", + "use_dd_slash_mm_slash_yyyy", + "use_dd_slash_mm_slash_yyyy_with_leading_zeros_for_single_digit_days_and_months", + "use_dd_space_spelled_out_month_space_yyyy", + "use_dd_space_spelled_out_month_space_yyyy_and_use_spanish_word_septiembre_for_ninth_month", + "use_dd_space_spelled_out_month_space_yyyy_and_use_spanish_word_setiembre_for_ninth_month", + "use_dd_space_spelled_out_month_space_yyyy_without_leading_zeros_for_single_digit_days", + "use_historical_eras_and_write_numbers_in_chinese_followed_by_chinese_word_公元前_or_公元后_with_arabic_numerals_in_parentheses", + "use_mm_slash_dd_slash_yyyy_with_leading_zeros_for_single_digit_days_and_months", + "use_numerals_only_with_leading_zero_for_single_digits", + "use_numerals_only_without_leading_zero_for_single_digits", + "use_spelled_out_month_space_dd_comma_space_yyyy_and_use_spanish_word_septiembre_for_ninth_month", + "use_spelled_out_month_space_dd_comma_space_yyyy_without_leading_zeros_for_single_digit_days", + "use_traditional_calendar_system_with_chinese_numbers", + "use_yyyy_chinese_word_年_mm_chinese_word_月_dd_chinese_word_日_with_chinese_numbers", + "use_yyyy_chinese_word_年_mm_chinese_word_月_dd_chinese_word_日_without_leading_zero_for_single_digit_months_and_days", + "use_yyyy_hyphen_mm_hyphen_dd_with_leading_zero_for_single_digit_days_and_months", + "use_yyyy_hyphen_mm_hyphen_dd_with_leading_zeros_for_single_digit_days_and_months", + "use_yyyy_korean word_년_space_mm_korean word_월_space_dd_korean word_일_without_leading_zero_for_single_digit_days_and_months", + "use_yyyy_period_mm_period_dd", + "use_yyyy_period_space_mm_period_space_dd_period_space_without_leading_zero_for_single_digit_days_and_months", + "use_yyyy_slash_mm_slash_dd", + "use_yyyy_slash_mm_slash_dd_with_leading_zero_for_single_digit_days_and_months" + ] + }, + "dates_in_numerical_form": { + "type": "string", + "description": "Formatting options for Dates In Numerical Form", + "enum": [ + "use_dd_hyphen_mm_hyphen_yyyy", + "use_dd_period_mm_period_yyyy", + "use_dd_slash_mm_slash_yyyy" + ] + }, + "decades": { + "type": "string", + "description": "Formatting options for Decades", + "enum": [ + "spell_out", + "use_apostrophe_yy", + "use_yy_for_20th_century_but_yyyy_for_other_centuries", + "use_yy_without_apostrophe", + "use_yyyy" + ] + }, + "hours_minutes_seconds_separator": { + "type": "string", + "description": "Formatting options for Hours Minutes Seconds Separator", + "enum": [ + "use_colon", + "use_period" + ] + }, + "hours_minutes_separator": { + "type": "string", + "description": "Formatting options for Hours Minutes Separator", + "enum": [ + "use_colon_without_spaces", + "use_letter_h_with_regular_space_on_either_side", + "use_letter_h_without_spaces" + ] + }, + "midnight_in_numerals": { + "type": "string", + "description": "Formatting options for Midnight In Numerals", + "enum": [ + "use_00_00", + "use_24_00" + ] + }, + "single_digit_days_and_months": { + "type": "string", + "description": "Formatting options for Single Digit Days And Months", + "enum": [ + "do_not_use_leading_zero", + "use_leading_zero" + ] + }, + "single_digit_hours": { + "type": "string", + "description": "Formatting options for Single Digit Hours", + "enum": [ + "do_not_use_leading_zero", + "use_leading_zero" + ] + }, + "time_format": { + "type": "string", + "description": "Formatting options for Time Format", + "enum": [ + "spell_out_time_in_words", + "use_12_hour_clock_and_do_not_specify_morning_or_evening", + "use_12_hour_clock_and_lowercase_am_or_pm_with_periods", + "use_12_hour_clock_and_lowercase_am_or_pm_with_periods_except_use_noon_and_midnight_instead_of_12_am_and_12_pm", + "use_12_hour_clock_and_lowercase_am_or_pm_without_periods", + "use_12_hour_clock_and_lowercase_am_or_pm_without_periods_except_use_noon_and_midnight_instead_of_12_am_and_12_pm", + "use_12_hour_clock_and_specify_morning_or_evening", + "use_12_hour_clock_and_uppercase_am_or_pm_with_periods", + "use_12_hour_clock_and_uppercase_am_or_pm_with_periods_except_use_noon_and_midnight_instead_of_12_am_and_12_pm", + "use_12_hour_clock_and_uppercase_am_or_pm_without_periods", + "use_12_hour_clock_and_uppercase_am_or_pm_without_periods_except_use_noon_and_midnight_instead_of_12_am_and_12_pm", + "use_12_hour_clock_and_write_chinese_word_上午_or_下午_or_chinese_word_早上_or_晚上_followed_by_arabic_numerals", + "use_12_hour_clock_and_write_chinese_word_上午_or_下午_or_chinese_word_早上_or_晚上_followed_by_arabic_numerals_with_chinese_word_点_for_hours", + "use_12_hour_clock_and_write_chinese_word_上午_or_下午_or_chinese_word_早上_or_晚上_followed_by_arabic_numerals_with_chinese_words_时_and_分_for_hours_and_minutes", + "use_12_hour_clock_and_write_chinese_word_上午_or_下午_or_chinese_word_早上_or_晚上_followed_by_chinese_numbers_with_chinese_words_时_and_分_for_hours_and_minutes", + "use_12_hour_clock_with_arabic_numerals_and_colon", + "use_12_hour_clock_with_korean_words_시_and_분", + "use_12_hour_clock_without_leading_zero_or_minutes_for_full_hours_use_colon_as_separator_and_lowercase_am_or_pm_without_periods", + "use_12_hour_clock_without_leading_zero_or_minutes_for_full_hours_use_colon_as_separator_and_uppercase_am_or_pm_without_periods", + "use_12_hour_clock_without_leading_zero_use_period_as_separator_and_lowercase_am_or_pm_with_periods_and_spaces", + "use_24_hour_clock", + "use_24_hour_clock_with_arabic_numerals_and_colon", + "use_24_hour_clock_with_colon_as_separator", + "use_24_hour_clock_with_korean_words_시_and_분", + "use_24_hour_clock_with_period_as_separator", + "use_hh_colon_mm_german_word_uhr_with_leading_zeros_for_single_digit_hours", + "use_hh_colon_mm_german_word_uhr_without_leading_zeros_for_single_digit_hours", + "use_hh_period_mm_german_word_uhr_with_leading_zeros_for_single_digit_hours", + "use_hh_period_mm_german_word_uhr_without_leading_zeros_for_single_digit_hours", + "use_hh_period_mm_german_word_uhr_without_leading_zeros_for_single_digit_hours_and_for_full_hours_state_hour_only" + ] + }, + "writing_dates": { + "type": "string", + "description": "Formatting options for Writing Dates", + "enum": [ + "use_dd_space_spelled_out_month_space_yyyy", + "use_numerals" + ] + }, + "years": { + "type": "string", + "description": "Formatting options for Years", + "enum": [ + "use_apostrophe_yy", + "use_common_era", + "use_japanese_imperial_era", + "use_yyyy" + ] + } + } + }, + "formatting": { + "type": "object", + "properties": { + "email_address_format": { + "type": "string", + "description": "Formatting options for Email Address Format", + "enum": [ + "place_domain_in_parentheses", + "replace_at_symbol_with_english_word_at_in_brackets_and_replace_periods_with_english_word_dot_in_brackets", + "replace_at_symbol_with_english_word_at_in_brackets_with_space_on_either_side", + "replace_at_symbol_with_english_word_at_in_parentheses_with_space_on_either_side", + "replace_at_symbol_with_english_word_at_with_space_on_either_side", + "use_standard_format" + ] + }, + "phone_number_country_code_format": { + "type": "string", + "description": "Formatting options for Phone Number Country Code Format", + "enum": [ + "use_00_before_country_code", + "use_plus_sign_before_country_code" + ] + }, + "phone_number_format": { + "type": "string", + "description": "Formatting options for Phone Number Format", + "enum": [ + "do_not_use_spaces", + "do_not_use_spaces_or_special_characters_between_digits_of_phone_number", + "keep_original_format", + "place_area_code_in_parentheses_followed_by_space", + "separate_area_code_and_phone_number_with_slash", + "separate_area_code_and_phone_number_with_space", + "separate_country_code_area_code_local_prefix_and_last_four_digits_with_hyphens", + "separate_country_code_area_code_local_prefix_and_last_four_digits_with_periods", + "separate_country_code_area_code_local_prefix_and_last_four_digits_with_spaces", + "use_north_american_numbering_plan_format", + "use_space_after_country_code" + ] + }, + "space_between_arabic_numerals_and_unit": { + "type": "string", + "description": "Formatting options for Space Between Arabic Numerals And Unit", + "enum": [ + "do_not_use" + ] + }, + "space_between_chinese_and_english": { + "type": "string", + "description": "Formatting options for Space Between Chinese And English", + "enum": [ + "do_not_use" + ] + }, + "space_between_chinese_characters_and_arabic_numerals": { + "type": "string", + "description": "Formatting options for Space Between Chinese Characters And Arabic Numerals", + "enum": [ + "do_not_use" + ] + } + } + }, + "numbers": { + "type": "object", + "properties": { + "approximate_numbers": { + "type": "string", + "description": "Formatting options for Approximate Numbers", + "enum": [ + "use_kanji_numbers" + ] + }, + "currency_format": { + "type": "string", + "description": "Formatting options for Currency Format", + "enum": [ + "spell_out", + "spell_out_currency_name_followed_by_amount_in_arabic_numerals_without_space", + "spell_out_currency_name_followed_by_amount_in_chinese", + "use_amount_followed_by_currency_symbol_without_space", + "use_amount_followed_by_space_then_currency_symbol", + "use_amount_followed_by_space_then_iso_code", + "use_amount_followed_by_space_then_spell_out_currency_name", + "use_amount_followed_by_space_then_spell_out_currency_name_in_lowercase", + "use_amount_followed_by_spelled_out_currency_name_in_japanese_without_space", + "use_amount_followed_by_spelled_out_currency_name_without_space", + "use_currency_symbol_but_spell_out_if_no_symbol_exists", + "use_currency_symbol_but_use_iso_code_if_no_symbol_exists", + "use_currency_symbol_followed_by_amount_in_arabic_numerals_without_space", + "use_currency_symbol_followed_by_amount_without_space", + "use_currency_symbol_followed_by_space_then_amount", + "use_currency_symbol_followed_by_space_then_amount_in_arabic_numerals", + "use_full_width_currency_symbol_followed_by_amount_without_space", + "use_half_width_currency_symbol_followed_by_amount_without_space", + "use_half_width_currency_symbol_followed_by_space_then_amount", + "use_iso_code", + "use_iso_code_followed_by_space_then_amount", + "use_iso_code_followed_by_space_then_amount_in_arabic_numerals" + ] + }, + "decimal_numbers_less_than_one": { + "type": "string", + "description": "Formatting options for Decimal Numbers Less Than One", + "enum": [ + "always_use_0_before_decimal_separator" + ] + }, + "decimal_separator": { + "type": "string", + "description": "Formatting options for Decimal Separator", + "enum": [ + "use_comma_and_do_not_use_thousands_separator", + "use_comma_as_decimal_separator", + "use_comma_do_not_use_thousands_separator_and_use_period_only_for_radio_stations", + "use_period_and_do_not_use_thousands_separator", + "use_period_as_decimal_separator" + ] + }, + "dimensions_separator": { + "type": "string", + "description": "Formatting options for Dimensions Separator", + "enum": [ + "use_multiplication_sign_between_dimensions_with_space_on_either_side", + "use_multiplication_sign_between_dimensions_without_space_on_either_side", + "use_x_between_dimensions_with_space_on_either_side", + "use_x_between_dimensions_without_space_on_either_side" + ] + }, + "equation_formula_reference": { + "type": "string", + "description": "Formatting options for Equation Formula Reference", + "enum": [ + "always_use_arabic_numerals_to_number_equations_or_formulas_referenced_in_text" + ] + }, + "kanji_numbers": { + "type": "string", + "description": "Formatting options for Kanji Numbers", + "enum": [ + "use_kanji_numbers_for_numbers_in_phrases_and_counting_method_based_on_native_japanese_readings" + ] + }, + "large_number_format": { + "type": "string", + "description": "Formatting options for Large Number Format", + "enum": [ + "always_use_arabic_numerals", + "spell_out_large_numbers", + "use_abbreviations_for_large_numbers", + "use_chinese_characters_for_ten_thousands_and_hundred_millions", + "use_comma_to_separate_large_numbers_into_units_of_three_except_for_calendar_years", + "use_kanji_for_trillions_hundred_millions_and_ten_thousands", + "use_korean_words_만_억_조_with_space", + "use_korean_words_만_억_조_without_space" + ] + }, + "large_sums_of_money": { + "type": "string", + "description": "Formatting options for Large Sums Of Money", + "enum": [ + "spell_out_italian_words_milione_and_miliardo", + "use_italian_words_mio_and_mrd_instead_of_italian_words_milione_and_miliardo" + ] + }, + "large_sums_of_money_format": { + "type": "string", + "description": "Formatting options for Large Sums Of Money Format", + "enum": [ + "use_amount_followed_by_abbreviation_for_million_or_billion_without_space", + "use_amount_followed_by_space_then_abbreviation_for_million_or_billion", + "use_amount_followed_by_space_then_english_word_million_or_billion" + ] + }, + "list_of_measurements_with_units": { + "type": "string", + "description": "Formatting options for List Of Measurements With Units", + "enum": [ + "repeat_unit_for_each_measurement_in_list" + ] + }, + "mathematical_expression_spacing": { + "type": "string", + "description": "Formatting options for Mathematical Expression Spacing", + "enum": [ + "use_space_between_elements_of_mathematical_expression_or_equation" + ] + }, + "number_format": { + "type": "string", + "description": "Formatting options for Number Format", + "enum": [ + "use_half_width_comma_to_separate_large_numbers_into_units_of_three_except_for_calendar_years_and_use_half_width_period_as_decimal_separator" + ] + }, + "number_separator": { + "type": "string", + "description": "Formatting options for Number Separator", + "enum": [ + "do_not_use_chinese_comma_to_separate_numbers_indicating_approximate_value", + "use_chinese_comma_to_separate_numbers_in_abbreviations" + ] + }, + "numbers_of_5_digits_or_more": { + "type": "string", + "description": "Formatting options for Numbers Of 5 Digits Or More", + "enum": [ + "use_comma_as_decimal_separator_and_period_as_thousands_separator", + "use_comma_as_decimal_separator_and_space_as_thousands_separator", + "use_comma_as_decimal_separator_period_as_thousands_separator_and_period_for_radio_stations", + "use_comma_as_decimal_separator_space_as_thousands_separator_and_period_for_radio_stations", + "use_period_as_decimal_separator_and_comma_as_thousands_separator", + "use_period_as_decimal_separator_and_space_as_thousands_separator" + ] + }, + "numbers_up_to_4_digits": { + "type": "string", + "description": "Formatting options for Numbers Up To 4 Digits", + "enum": [ + "use_comma_as_decimal_separator_and_period_as_thousands_separator", + "use_comma_as_decimal_separator_and_space_as_thousands_separator", + "use_comma_as_decimal_separator_period_as_thousands_separator_and_period_for_radio_stations", + "use_comma_as_decimal_separator_space_as_thousands_separator_and_period_for_radio_stations", + "use_period_as_decimal_separator_and_comma_as_thousands_separator", + "use_period_as_decimal_separator_and_space_as_thousands_separator" + ] + }, + "percentage_format": { + "type": "string", + "description": "Formatting options for Percentage Format", + "enum": [ + "use_arabic_numerals_followed_by_percent_symbol_without_space", + "use_chinese_numbers_followed_by_chinese_word_百分之", + "use_numerals_followed_by_full_width_percent_symbol_without_space", + "use_numerals_followed_by_japanese_word_パーセント_without_space", + "use_numerals_followed_by_korean_word_퍼센트", + "use_numerals_followed_by_percent_symbol", + "use_numerals_followed_by_space_then_german_word_prozent", + "use_numerals_followed_by_space_then_half_width_percent_symbol", + "use_numerals_followed_by_space_then_italian_word_per_cento", + "use_numerals_followed_by_space_then_italian_word_percento", + "use_numerals_followed_by_space_then_korean_word_퍼센트", + "use_numerals_followed_by_space_then_percent_symbol", + "use_numerals_followed_by_space_then_spell_out_per_cent", + "use_numerals_followed_by_space_then_spell_out_percent", + "use_spanish_word_por_cien", + "use_spanish_word_por_ciento" + ] + }, + "reference_to_symbol": { + "type": "string", + "description": "Formatting options for Reference To Symbol", + "enum": [ + "spell_out_symbol_name_followed_by_symbol_in_parentheses" + ] + }, + "spelling_out_units": { + "type": "string", + "description": "Formatting options for Spelling Out Units", + "enum": [ + "abbreviate_units_of_measure_when_used_with_numeral_but_spell_out_when_used_without_numeral", + "always_abbreviate_units_of_measure", + "always_spell_out_units_of_measure", + "spell_out_units_in_korean", + "spell_out_units_of_measure_when_used_with_spelled_out_numbers_but_abbreviate_when_used_with_numeral", + "spell_out_units_of_measure_with_katakana_or_katakana_and_kanji", + "use_si_symbols", + "use_unit_symbols" + ] + }, + "temperature_format": { + "type": "string", + "description": "Formatting options for Temperature Format", + "enum": [ + "spell_out_unit", + "spell_out_unit_followed_by_numerals_then_korean_word_도", + "use_arabic_numerals_followed_by_space_then_spell_out_unit", + "use_arabic_numerals_followed_by_unit_symbol_without_space", + "use_arabic_numerals_then_spell_out_unit", + "use_chinese_numbers_then_spell_out_unit", + "use_italian_word_grado_and_do_not_specify_temperature_scale", + "use_numerals_followed_by_japanese_word_度_without_space", + "use_numerals_followed_by_korean_word_도", + "use_numerals_followed_by_space_then_spell_out_unit", + "use_numerals_followed_by_space_then_unit_symbol", + "use_numerals_followed_by_unit_symbol_without_space", + "use_spanish_word_grado_and_do_not_specify_temperature_scale" + ] + }, + "thousands_separator": { + "type": "string", + "description": "Formatting options for Thousands Separator", + "enum": [ + "do_not_use", + "do_not_use_thousands_separator", + "use_comma", + "use_comma_to_separate_large_numbers_into_units_of_three", + "use_period", + "use_period_as_thousands_separator", + "use_space", + "use_space_as_thousands_separator", + "use_space_to_separate_large_numbers_into_units_of_three", + "use_straight_apostrophe_as_thousands_separator" + ] + }, + "units_of_measure_spacing": { + "type": "string", + "description": "Formatting options for Units Of Measure Spacing", + "enum": [ + "do_not_use_space_between_numeral_and_unit_of_measure", + "use_space_between_numeral_and_unit_of_measure" + ] + }, + "use_of_hiragana_and_kanji": { + "type": "string", + "description": "Formatting options for Use Of Hiragana And Kanji", + "enum": [ + "use_hiragana_japanese_word_か所_or_か月_when_using_arabic_numerals_in_horizontal_writing_but_use_kanji_japanese_word_箇所_or_箇月_when_using_kanji_numbers" + ] + }, + "writing_numbers": { + "type": "string", + "description": "Formatting options for Writing Numbers", + "enum": [ + "always_use_kanji_numbers", + "use_arabic_numerals", + "use_full_width_arabic_numerals_and_only_use_kanji_numbers_where_it_would_otherwise_sound_unnatural", + "use_half_width_arabic_numerals_and_only_use_kanji_numbers_where_it_would_otherwise_sound_unnatural" + ] + }, + "zero_format": { + "type": "string", + "description": "Formatting options for Zero Format", + "enum": [ + "use_chinese_word_〇_for_numbering", + "use_chinese_word_零_for_measurement" + ] + } + } + }, + "punctuation": { + "type": "object", + "properties": { + "abbreviations": { + "type": "string", + "description": "Formatting options for Abbreviations", + "enum": [ + "do_not_separate_abbreviated_words", + "separate_each_abbreviated_word_with_period_and_space", + "separate_each_abbreviated_word_with_period_without_space", + "separate_each_abbreviated_word_with_space_without_period" + ] + }, + "acronyms": { + "type": "string", + "description": "Formatting options for Acronyms", + "enum": [ + "do_not_use_periods" + ] + }, + "ampersand_abbreviation_spacing": { + "type": "string", + "description": "Formatting options for Ampersand Abbreviation Spacing", + "enum": [ + "do_not_use_spaces_before_and_after_ampersand_as_part_of_abbreviation", + "use_spaces_before_and_after_ampersand_as_part_of_abbreviation" + ] + }, + "ampersand_usage": { + "type": "string", + "description": "Formatting options for Ampersand Usage", + "enum": [ + "use_english_word_and_except_in_company_names_common_abbreviations_titles_software_code_and_mathematical_equations", + "use_full_width_ampersand", + "use_german_word_und_except_in_company_names_common_abbreviations_titles_software_code_and_mathematical_equations", + "use_half_width_ampersand" + ] + }, + "apostrophe": { + "type": "string", + "description": "Formatting options for Apostrophe", + "enum": [ + "use_curly_apostrophes", + "use_straight_apostrophes" + ] + }, + "bracket": { + "type": "string", + "description": "Formatting options for Bracket", + "enum": [ + "use_hexagonal_brackets", + "use_lenticular_brackets", + "use_parentheses", + "use_square_brackets_for_nationality_and_hexagonal_brackets_for_historical_period" + ] + }, + "chinese_mixed_with_english": { + "type": "string", + "description": "Formatting options for Chinese Mixed With English", + "enum": [ + "do_not_place_english_in_quotation_marks", + "place_english_in_quotation_marks" + ] + }, + "colon": { + "type": "string", + "description": "Formatting options for Colon", + "enum": [ + "use_full_width_colon", + "use_half_width_colon" + ] + }, + "colon_between_hours_and_minutes_or_chapters_and_verses": { + "type": "string", + "description": "Formatting options for Colon Between Hours And Minutes Or Chapters And Verses", + "enum": [ + "do_not_use_space_before_or_after_colon" + ] + }, + "colon_in_heading": { + "type": "string", + "description": "Formatting options for Colon In Heading", + "enum": [ + "use_space_after_colon_not_before" + ] + }, + "colon_to_replace_versus_or_to": { + "type": "string", + "description": "Formatting options for Colon To Replace Versus Or To", + "enum": [ + "do_not_use_space_before_or_after_colon" + ] + }, + "comma_after_conjunctive_adverbs": { + "type": "string", + "description": "Formatting options for Comma After Conjunctive Adverbs", + "enum": [ + "do_not_use", + "use" + ] + }, + "comma_after_i_e_and_e_g": { + "type": "string", + "description": "Formatting options for Comma After I E And E G", + "enum": [ + "do_not_use", + "use" + ] + }, + "comma_after_short_introductory_phrase": { + "type": "string", + "description": "Formatting options for Comma After Short Introductory Phrase", + "enum": [ + "do_not_use", + "use" + ] + }, + "comma_and_semicolon": { + "type": "string", + "description": "Formatting options for Comma And Semicolon", + "enum": [ + "use_comma_between_clauses", + "use_semicolon_between_clauses" + ] + }, + "corner_bracket_and_periods": { + "type": "string", + "description": "Formatting options for Corner Bracket And Periods", + "enum": [ + "add_period_after_closing_corner_bracket_at_end_of_sentence" + ] + }, + "corner_brackets_and_periods": { + "type": "string", + "description": "Formatting options for Corner Brackets And Periods", + "enum": [ + "do_not_add_period_before_closing_corner_bracket_when_sentence_continues" + ] + }, + "dash": { + "type": "string", + "description": "Formatting options for Dash", + "enum": [ + "use_em_dash", + "use_hyphen", + "use_tilde" + ] + }, + "ellipsis": { + "type": "string", + "description": "Formatting options for Ellipsis", + "enum": [ + "use_ellipsis_character", + "use_one_ellipsis_character", + "use_six_dots_at_the_bottom", + "use_six_dots_in_the_center", + "use_three_dots_at_the_bottom", + "use_three_dots_in_the_center", + "use_three_ellipsis_characters", + "use_three_periods", + "use_three_periods_without_spaces", + "use_three_spaced_periods", + "use_two_ellipsis_characters" + ] + }, + "em_dash": { + "type": "string", + "description": "Formatting options for Em Dash", + "enum": [ + "use_double_em_dash" + ] + }, + "emphasis": { + "type": "string", + "description": "Formatting options for Emphasis", + "enum": [ + "use_double_corner_brackets" + ] + }, + "exclamation_marks": { + "type": "string", + "description": "Formatting options for Exclamation Marks", + "enum": [ + "do_not_use" + ] + }, + "explanatory_note_indicator": { + "type": "string", + "description": "Formatting options for Explanatory Note Indicator", + "enum": [ + "use_double_em_dash", + "use_parentheses" + ] + }, + "full_sentence_in_round_brackets": { + "type": "string", + "description": "Formatting options for Full Sentence In Round Brackets", + "enum": [ + "add_period_before_closing_round_bracket" + ] + }, + "highlighting_specific_expressions": { + "type": "string", + "description": "Formatting options for Highlighting Specific Expressions", + "enum": [ + "use_single_curly_quotation_marks", + "use_single_straight_quotation_marks" + ] + }, + "japanese_reference_materials": { + "type": "string", + "description": "Formatting options for Japanese Reference Materials", + "enum": [ + "use_double_corner_brackets" + ] + }, + "parentheses_for_supplementary_information": { + "type": "string", + "description": "Formatting options for Parentheses For Supplementary Information", + "enum": [ + "use_parentheses_without_space_on_either_side" + ] + }, + "passage_of_time_and_movement_between_locations": { + "type": "string", + "description": "Formatting options for Passage Of Time And Movement Between Locations", + "enum": [ + "use_double_em_dash" + ] + }, + "periods_and_commas": { + "type": "string", + "description": "Formatting options for Periods And Commas", + "enum": [ + "use_full_width_japanese_periods_and_full_width_japanese_commas", + "use_full_width_japanese_periods_and_full_width_non_japanese_commas", + "use_full_width_non_japanese_periods_and_full_width_japanese_commas", + "use_full_width_non_japanese_periods_and_full_width_non_japanese_commas" + ] + }, + "periods_in_academic_degrees": { + "type": "string", + "description": "Formatting options for Periods In Academic Degrees", + "enum": [ + "do_not_use", + "use" + ] + }, + "periods_in_direct_quotes": { + "type": "string", + "description": "Formatting options for Periods In Direct Quotes", + "enum": [ + "do_not_use", + "use" + ] + }, + "periods_in_uppercase_initialisms_and_acronyms": { + "type": "string", + "description": "Formatting options for Periods In Uppercase Initialisms And Acronyms", + "enum": [ + "do_not_use" + ] + }, + "plus_sign_usage": { + "type": "string", + "description": "Formatting options for Plus Sign Usage", + "enum": [ + "do_not_use_plus_sign_to_symbolize_english_word_and_unless_it_is_part_of_a_proper_noun" + ] + }, + "possessives_of_proper_names_ending_in_s_style": { + "type": "string", + "description": "Formatting options for Possessives Of Proper Names Ending In S Style", + "enum": [ + "add_apostrophe_only", + "add_apostrophe_s" + ] + }, + "quotation_mark": { + "type": "string", + "description": "Formatting options for Quotation Mark", + "enum": [ + "use_curly_quotation_marks", + "use_double_curly_quotation_marks", + "use_double_straight_quotation_marks", + "use_guillemets", + "use_straight_quotation_marks" + ] + }, + "quotation_mark_and_apostrophe": { + "type": "string", + "description": "Formatting options for Quotation Mark And Apostrophe", + "enum": [ + "use_curly_quotation_marks_and_apostrophes", + "use_double_and_single_curly_quotation_marks_and_curly_apostrophes", + "use_double_and_single_straight_quotation_marks_and_straight_apostrophes", + "use_guillemets_and_curly_apostrophes", + "use_guillemets_and_straight_apostrophes", + "use_straight_quotation_marks_and_apostrophes" + ] + }, + "quotation_style": { + "type": "string", + "description": "Formatting options for Quotation Style", + "enum": [ + "use_corner_brackets_for_primary_quotations_and_double_corner_brackets_for_secondary_quotations", + "use_double_curly_quotation_marks_for_primary_quotations_and_single_curly_quotation_marks_for_secondary_quotations", + "use_double_curly_quotation_marks_for_primary_quotations_then_alternate_with_single_curly_quotation_marks_for_nested_quotations", + "use_double_german_quotation_marks_for_primary_quotations_and_single_german_quotation_marks_for_secondary_quotations", + "use_double_quotation_marks_for_primary_quotations_and_single_quotation_marks_for_secondary_quotations", + "use_double_straight_quotation_marks_for_primary_quotations_and_single_straight_quotation_marks_for_secondary_quotations", + "use_double_straight_quotation_marks_for_primary_quotations_then_alternate_with_single_straight_quotation_marks_for_nested_quotations", + "use_guillemets_for_primary_quotations_and_double_curly_quotation_marks_for_secondary_quotations", + "use_guillemets_for_primary_quotations_and_double_straight_quotation_marks_for_secondary_quotations", + "use_guillemets_for_primary_quotations_and_single_guillemets_for_secondary_quotations", + "use_guillemets_for_primary_quotations_double_curly_quotation_marks_for_secondary_quotations_and_single_curly_quotation_marks_for_further_nested_quotations", + "use_reversed_guillemets_for_primary_quotations_and_single_reversed_guillemets_for_secondary_quotations", + "use_single_quotation_marks_for_primary_quotations_and_double_quotation_marks_for_secondary_quotations" + ] + }, + "range_indicator": { + "type": "string", + "description": "Formatting options for Range Indicator", + "enum": [ + "use_en_dash_with_spaces", + "use_en_dash_without_space_on_either_side", + "use_en_dash_without_spaces", + "use_english_word_to", + "use_full_width_dash", + "use_full_width_wave_dash", + "use_german_word_bis", + "use_half_width_dash", + "use_hyphen", + "use_hyphen_with_space_on_either_side", + "use_hyphen_with_spaces", + "use_hyphen_without_space_on_either_side", + "use_hyphen_without_spaces", + "use_italian_words_da_a", + "use_japanese_word_から", + "use_korean_words_부터_까지", + "use_spanish_words_de_a", + "use_tilde" + ] + }, + "related_phrases_indicator": { + "type": "string", + "description": "Formatting options for Related Phrases Indicator", + "enum": [ + "use_comma", + "use_hyphen", + "use_middle_dot" + ] + }, + "round_brackets": { + "type": "string", + "description": "Formatting options for Round Brackets", + "enum": [ + "use_full_width_round_brackets", + "use_half_width_round_brackets" + ] + }, + "salutation": { + "type": "string", + "description": "Formatting options for Salutation", + "enum": [ + "do_not_use_comma_after_salutation_capitalize_following_word", + "use_colon_after_salutation", + "use_comma_after_salutation", + "use_exclamation_mark_after_salutation" + ] + }, + "sentence_break_indicator": { + "type": "string", + "description": "Formatting options for Sentence Break Indicator", + "enum": [ + "use_em_dash_with_space_on_either_side", + "use_em_dash_without_space_on_either_side", + "use_en_dash_with_space_on_either_side" + ] + }, + "serial_comma": { + "type": "string", + "description": "Formatting options for Serial Comma", + "enum": [ + "do_not_use", + "do_not_use_serial_comma_when_using_chinese_comma", + "use", + "use_serial_comma_when_using_comma" + ] + }, + "setting_off_non_quoted_phrases": { + "type": "string", + "description": "Formatting options for Setting Off Non Quoted Phrases", + "enum": [ + "use_full_width_quotation_marks", + "use_half_width_quotation_marks" + ] + }, + "slash": { + "type": "string", + "description": "Formatting options for Slash", + "enum": [ + "do_not_use_spaces_before_and_after_slashes", + "use_spaces_before_and_after_slashes", + "use_spaces_before_and_after_slashes_if_there_are_multiple_words_before_and_after_slash", + "use_spaces_before_and_after_slashes_if_there_are_multiple_words_before_or_after_slash" + ] + }, + "slash_usage": { + "type": "string", + "description": "Formatting options for Slash Usage", + "enum": [ + "do_not_use_slash_to_symbolize_english_word_or" + ] + }, + "spacing_and_punctuation": { + "type": "string", + "description": "Formatting options for Spacing And Punctuation", + "enum": [ + "do_not_use_space", + "use_regular_space" + ] + }, + "text_in_round_brackets_referring_to_previous_sentence": { + "type": "string", + "description": "Formatting options for Text In Round Brackets Referring To Previous Sentence", + "enum": [ + "add_period_after_closing_round_bracket", + "add_period_before_closing_round_bracket" + ] + }, + "text_in_round_brackets_supplementing_preceding_text": { + "type": "string", + "description": "Formatting options for Text In Round Brackets Supplementing Preceding Text", + "enum": [ + "add_period_after_closing_round_bracket" + ] + }, + "titles_of_books_and_newspapers": { + "type": "string", + "description": "Formatting options for Titles Of Books And Newspapers", + "enum": [ + "use_double_angle_brackets", + "use_double_corner_brackets", + "use_double_straight_quotation_marks" + ] + }, + "titles_of_creative_works_trade_names_laws_and_regulations": { + "type": "string", + "description": "Formatting options for Titles Of Creative Works Trade Names Laws And Regulations", + "enum": [ + "use_single_angle_brackets", + "use_single_corner_brackets", + "use_single_straight_quotation_marks" + ] + }, + "uppercase_acronyms": { + "type": "string", + "description": "Formatting options for Uppercase Acronyms", + "enum": [ + "do_not_use_spaces", + "use_spaces" + ] + } + } + }, + "spelling_and_grammar": { + "type": "object", + "properties": { + "abbreviating_french_word_numero": { + "type": "string", + "description": "Formatting options for Abbreviating French Word Numero", + "enum": [ + "abbreviate_as_n_then_degree_symbol", + "abbreviate_as_n_then_o_in_superscript", + "abbreviate_as_no" + ] + }, + "abbreviation_usage": { + "type": "string", + "description": "Formatting options for Abbreviation Usage", + "enum": [ + "do_not_use_abbreviations", + "do_not_use_abbreviations_unless_necessary", + "use_abbreviations", + "use_abbreviations_as_needed" + ] + }, + "accents_and_cedillas": { + "type": "string", + "description": "Formatting options for Accents And Cedillas", + "enum": [ + "do_not_use_on_capital_letters", + "never_use", + "use_even_on_capital_letters" + ] + }, + "accents_in_verbs_conjugated_like_french_word_céder": { + "type": "string", + "description": "Formatting options for Accents In Verbs Conjugated Like French Word Céder", + "enum": [ + "use_acute_accent", + "use_grave_accent" + ] + }, + "accents_with_subject_verb_inversion": { + "type": "string", + "description": "Formatting options for Accents With Subject Verb Inversion", + "enum": [ + "use_acute_accent", + "use_grave_accent" + ] + }, + "active_passive_voice": { + "type": "string", + "description": "Formatting options for Active Passive Voice", + "enum": [ + "use_active_voice_if_subject_is_prominent_and_agent_is_clear", + "use_active_voice_to_describe_operations_with_user_as_subject", + "use_active_voice_unless_agent_is_unknown_or_irrelevant", + "use_passive_voice_as_needed", + "use_passive_voice_for_automatic_operations_from_user_perspective", + "use_passive_voice_if_agent_is_unknown_or_irrelevant" + ] + }, + "all_caps": { + "type": "string", + "description": "Formatting options for All Caps", + "enum": [ + "do_not_use_all_caps_except_for_acronyms_initialisms_or_proper_nouns", + "do_not_use_all_caps_except_for_acronyms_or_brand_names" + ] + }, + "complete_sentences": { + "type": "string", + "description": "Formatting options for Complete Sentences", + "enum": [ + "always_write_complete_sentences" + ] + }, + "compound_nouns": { + "type": "string", + "description": "Formatting options for Compound Nouns", + "enum": [ + "write_as_one_word", + "write_with_hyphen" + ] + }, + "conjunctions": { + "type": "string", + "description": "Formatting options for Conjunctions", + "enum": [ + "never_start_sentence_with_coordinating_conjunction" + ] + }, + "contractions": { + "type": "string", + "description": "Formatting options for Contractions", + "enum": [ + "do_not_use_contractions", + "use_contractions", + "use_contractions_but_avoid_negative_contractions" + ] + }, + "established_loanwords": { + "type": "string", + "description": "Formatting options for Established Loanwords", + "enum": [ + "use_as_is", + "use_native_or_sino_korean_equivalents" + ] + }, + "eszett": { + "type": "string", + "description": "Formatting options for Eszett", + "enum": [ + "replace_eszett_with_ss" + ] + }, + "foreign_word_translation": { + "type": "string", + "description": "Formatting options for Foreign Word Translation", + "enum": [ + "use_equivalent_expressions_in_chinese", + "use_foreign_forms_or_abbreviations_for_technical_terms_or_brand_names", + "use_literal_translation", + "use_localized_names_for_brands_with_official_chinese_translations", + "use_mixture_of_transliteration_and_translation", + "use_transliteration" + ] + }, + "french_verbs_ending_in_eler_and_eter": { + "type": "string", + "description": "Formatting options for French Verbs Ending In Eler And Eter", + "enum": [ + "transcribe_open_e_sound_by_doubling_next_consonant", + "transcribe_open_e_sound_with_grave_accent" + ] + }, + "i_and_u_with_circumflex_accents": { + "type": "string", + "description": "Formatting options for I And U With Circumflex Accents", + "enum": [ + "do_not_use_circumflex_accents_except_in_verbs_and_to_distinguish_homophones", + "use_circumflex_accents" + ] + }, + "informal_address_pronouns": { + "type": "string", + "description": "Formatting options for Informal Address Pronouns", + "enum": [ + "capitalize_informal_address_pronouns", + "do_not_capitalize_informal_address_pronouns" + ] + }, + "latin_abbreviations": { + "type": "string", + "description": "Formatting options for Latin Abbreviations", + "enum": [ + "do_not_use_latin_abbreviations" + ] + }, + "passive_voice": { + "type": "string", + "description": "Formatting options for Passive Voice", + "enum": [ + "avoid_passive_voice_when_agent_is_known" + ] + }, + "past_participle_of_french_word_laisser_followed_by_infinitive": { + "type": "string", + "description": "Formatting options for Past Participle Of French Word Laisser Followed By Infinitive", + "enum": [ + "make_french_word_laisser_agree_with_direct_object_complement_if_it_appears_before_verb", + "use_invariable_form_french_word_laissé" + ] + }, + "personal_titles": { + "type": "string", + "description": "Formatting options for Personal Titles", + "enum": [ + "abbreviate", + "do_not_abbreviate" + ] + }, + "pluralizing_foreign_words": { + "type": "string", + "description": "Formatting options for Pluralizing Foreign Words", + "enum": [ + "use_french_spelling_rules", + "use_original_language_spelling" + ] + }, + "quotation_modification": { + "type": "string", + "description": "Formatting options for Quotation Modification", + "enum": [ + "do_not_modify_text_in_quotation_marks", + "modify_text_in_quotation_marks_according_to_custom_rules" + ] + }, + "spanish_word_solo": { + "type": "string", + "description": "Formatting options for Spanish Word Solo", + "enum": [ + "never_use_acute_accent", + "use_acute_accent_when_used_as_adverb" + ] + }, + "special_characters": { + "type": "string", + "description": "Formatting options for Special Characters", + "enum": [ + "never_use_symbols" + ] + }, + "spelled_out_numbers": { + "type": "string", + "description": "Formatting options for Spelled Out Numbers", + "enum": [ + "use_hyphens", + "use_hyphens_between_elements_under_100_and_not_separated_by_french_word_et" + ] + }, + "umlauts": { + "type": "string", + "description": "Formatting options for Umlauts", + "enum": [ + "replace_umlauts_with_ae_oe_ue" + ] + }, + "unestablished_loanwords": { + "type": "string", + "description": "Formatting options for Unestablished Loanwords", + "enum": [ + "paraphrase_in_korean", + "use_as_is", + "use_as_is_with_explanation_in_parentheses" + ] + } + } + }, + "style_and_tone": { + "type": "object", + "properties": { + "abbreviations": { + "type": "string", + "description": "Formatting options for Abbreviations", + "enum": [ + "avoid_abbreviations_and_symbols_that_can_be_spelled_out_easily", + "use_abbreviations_and_symbols" + ] + }, + "addressing_non_binary_people": { + "type": "string", + "description": "Formatting options for Addressing Non Binary People", + "enum": [ + "use_spanish_word_elle", + "use_spanish_word_ellx" + ] + }, + "addressing_the_reader": { + "type": "string", + "description": "Formatting options for Addressing The Reader", + "enum": [ + "use_formal_french_word_vous", + "use_formal_italian_word_lei", + "use_informal_french_word_tu", + "use_informal_italian_word_tu" + ] + }, + "anglicisms": { + "type": "string", + "description": "Formatting options for Anglicisms", + "enum": [ + "avoid_anglicisms_when_there_is_a_french_equivalent" + ] + }, + "binary_representation_of_gender": { + "type": "string", + "description": "Formatting options for Binary Representation Of Gender", + "enum": [ + "avoid_binary_representation_of_gender_when_gender_neutral_language_can_be_used", + "replace_binary_representations_of_gender_with_gender_neutral_language", + "use_neutral_pronouns" + ] + }, + "complex_sentences": { + "type": "string", + "description": "Formatting options for Complex Sentences", + "enum": [ + "avoid_unnecessarily_complex_sentences" + ] + }, + "country_names": { + "type": "string", + "description": "Formatting options for Country Names", + "enum": [ + "use_long_form", + "use_short_form" + ] + }, + "declarative_endings": { + "type": "string", + "description": "Formatting options for Declarative Endings", + "enum": [ + "mix_hapsho_and_haeyo_styles", + "use_hae_style", + "use_haeyo_style", + "use_hapsho_style", + "use_hara_style" + ] + }, + "default_first_person_pronoun": { + "type": "string", + "description": "Formatting options for Default First Person Pronoun", + "enum": [ + "do_not_use_first_person_pronouns", + "omit_first_person_subject_when_clear_from_context", + "use_first_person_pronouns" + ] + }, + "default_second_person_pronoun": { + "type": "string", + "description": "Formatting options for Default Second Person Pronoun", + "enum": [ + "do_not_use_second_person_pronouns", + "use_second_person_pronouns" + ] + }, + "directional_language": { + "type": "string", + "description": "Formatting options for Directional Language", + "enum": [ + "do_not_use_directional_language" + ] + }, + "double_negatives": { + "type": "string", + "description": "Formatting options for Double Negatives", + "enum": [ + "do_not_use_double_negatives", + "use_double_negatives" + ] + }, + "formality": { + "type": "string", + "description": "Formatting options for Formality", + "enum": [ + "use_casual_tone", + "use_formal_tone" + ] + }, + "gender_neutral_language_readability": { + "type": "string", + "description": "Formatting options for Gender Neutral Language Readability", + "enum": [ + "use_generic_masculine_for_common_compound_nouns_if_it_increases_readability" + ] + }, + "gender_unspecified": { + "type": "string", + "description": "Formatting options for Gender Unspecified", + "enum": [ + "use_both_masculine_and_feminine_forms", + "use_gender_neutral_terms", + "use_masculine_form_only", + "use_middle_dots", + "use_parentheses", + "use_periods" + ] + }, + "gender_unspecified_or_mixed": { + "type": "string", + "description": "Formatting options for Gender Unspecified Or Mixed", + "enum": [ + "use_both_feminine_and_masculine_forms", + "use_feminine_form_only", + "use_inclusive_nouns_and_adjectives", + "use_masculine_form_only", + "use_neutral_nouns_and_adjectives" + ] + }, + "idioms_colloquialisms_and_culture_specific_references": { + "type": "string", + "description": "Formatting options for Idioms Colloquialisms And Culture Specific References", + "enum": [ + "do_not_use" + ] + }, + "inflected_words_masculine_noun_agreement": { + "type": "string", + "description": "Formatting options for Inflected Words Masculine Noun Agreement", + "enum": [ + "place_masculine_nouns_closest_to_inflected_words" + ] + }, + "instructions_style": { + "type": "string", + "description": "Formatting options for Instructions Style", + "enum": [ + "use_imperative", + "use_indicative", + "use_infinitive", + "use_modal_verbs", + "use_passive_voice" + ] + }, + "mixing_styles": { + "type": "string", + "description": "Formatting options for Mixing Styles", + "enum": [ + "do_not_mix_desu_masu_style_and_dearu_style" + ] + }, + "modal_verbs": { + "type": "string", + "description": "Formatting options for Modal Verbs", + "enum": [ + "avoid_modal_verbs" + ] + }, + "personal_vs_impersonal_style": { + "type": "string", + "description": "Formatting options for Personal Vs Impersonal Style", + "enum": [ + "use_impersonal_style", + "use_personal_style" + ] + }, + "positive_vs_negative_language": { + "type": "string", + "description": "Formatting options for Positive Vs Negative Language", + "enum": [ + "use_positive_language" + ] + }, + "proximity_agreement": { + "type": "string", + "description": "Formatting options for Proximity Agreement", + "enum": [ + "use" + ] + }, + "reader_action_required": { + "type": "string", + "description": "Formatting options for Reader Action Required", + "enum": [ + "use_you_must_when_action_is_required_from_reader" + ] + }, + "redundant_introductory_phrases": { + "type": "string", + "description": "Formatting options for Redundant Introductory Phrases", + "enum": [ + "avoid_redundant_introductory_phrases", + "do_not_use_redundant_phrases_that_refer_to_current_text" + ] + }, + "redundant_phrases": { + "type": "string", + "description": "Formatting options for Redundant Phrases", + "enum": [ + "avoid_relativizing_and_redundant_phrases", + "do_not_use_redundant_phrases" + ] + }, + "referring_to_non_binary_people": { + "type": "string", + "description": "Formatting options for Referring To Non Binary People", + "enum": [ + "use_the_singular_and_plural_schwa" + ] + }, + "short_vs_long_words": { + "type": "string", + "description": "Formatting options for Short Vs Long Words", + "enum": [ + "use_short_words" + ] + }, + "simple_words_and_sentences": { + "type": "string", + "description": "Formatting options for Simple Words And Sentences", + "enum": [ + "use_simple_words_and_sentences_avoid_hard_to_translate_words_and_figures_of_speech" + ] + }, + "text_position_references": { + "type": "string", + "description": "Formatting options for Text Position References", + "enum": [ + "avoid_directional_terms_as_only_reference_to_position_in_text_specify_exact_position_instead" + ] + }, + "tone": { + "type": "string", + "description": "Formatting options for Tone", + "enum": [ + "use_dearu_style_to_give_impression_content_is_accurate_and_rigorous_or_to_convey_sense_of_confidence_and_reliability", + "use_desu_masu_style_to_give_impression_content_is_plain_and_straightforward_or_to_give_reader_reassuring_or_soft_impression" + ] + }, + "verbal_vs_nominal_style": { + "type": "string", + "description": "Formatting options for Verbal Vs Nominal Style", + "enum": [ + "use_nominal_style", + "use_verbal_style" + ] + } + } + }, + "vocabulary": { + "type": "object", + "properties": { + "abbreviations": { + "type": "string", + "description": "Formatting options for Abbreviations", + "enum": [ + "write_original_term_then_abbreviation_and_explanation" + ] + }, + "loanwords": { + "type": "string", + "description": "Formatting options for Loanwords", + "enum": [ + "add_explanation_to_loanword_if_difficult_to_rephrase", + "rephrase_loanword_in_daily_use_chinese_or_japanese_words_if_possible", + "rephrase_loanword_with_another_expression_if_not_established", + "use_loanword_as_is_if_well_established" + ] + } + } + } + }, + "example": { + "style_and_tone": { + "abbreviations": "use_abbreviations_and_symbols", + "short_vs_long_words": "use_short_words" + }, + "punctuation": { + "apostrophe": "use_curly_apostrophes" + } + } + }, + "Context": { + "description": "Additional context that can influence a translation but is not translated itself.\n\nCharacters included in the `context` parameter will not be counted toward billing.", + "type": "string", + "example": "This is context." + }, + "CreateGlossaryParameters": { + "type": "object", + "required": [ + "name", + "source_lang", + "target_lang", + "entries", + "entries_format" + ], + "properties": { + "name": { + "description": "Name to be associated with the glossary.", + "type": "string", + "example": "My Glossary" + }, + "source_lang": { + "$ref": "#/components/schemas/GlossarySourceLanguage" + }, + "target_lang": { + "$ref": "#/components/schemas/GlossaryTargetLanguage" + }, + "entries": { + "description": "The entries of the glossary. The entries have to be specified in the format provided by the `entries_format` parameter.", + "type": "string", + "example": "Hello\tGuten Tag" + }, + "entries_format": { + "description": "The format in which the glossary entries are provided. Formats currently available:\n- `tsv` (default) - tab-separated values\n- `csv` - comma-separated values\n\nSee [Supported Glossary Formats](/api-reference/multilingual-glossaries#formats) for details about each format.", + "type": "string", + "enum": [ + "tsv", + "csv" + ], + "example": "tsv", + "default": "tsv" + } + } + }, + "CreateMultilingualGlossaryParameters": { + "type": "object", + "required": [ + "name", + "dictionaries" + ], + "properties": { + "name": { + "description": "Name to be associated with the glossary.", + "type": "string", + "example": "My Glossary" + }, + "dictionaries": { + "description": "Dictionaries to populate the glossary with.", + "type": "array", + "items": { + "$ref": "#/components/schemas/GlossaryDictionary" + } + } + } + }, + "CustomInstruction": { + "description": "All enabled custom instructions for the style rule list", + "type": "object", + "required": [ + "id", + "label", + "prompt" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the custom instruction", + "example": "68fdb803-c013-4e67-b62e-1aad0ab519cd" + }, + "label": { + "type": "string", + "description": "Name associated with the custom instruction", + "example": "Currency custom instruction" + }, + "prompt": { + "type": "string", + "description": "Prompt of the custom instruction", + "example": "Have currency symbols before the numerical value (e.g. $100, €100)" + }, + "source_language": { + "type": "string", + "description": "Optional source language of the custom instruction", + "example": "en" + } + } + }, + "StyleRuleList": { + "type": "object", + "required": [ + "style_id", + "name", + "creation_time", + "updated_time", + "language", + "version" + ], + "properties": { + "style_id": { + "$ref": "#/components/schemas/StyleId" + }, + "name": { + "$ref": "#/components/schemas/StyleRuleName" + }, + "creation_time": { + "description": "The creation time of the style rule list in the ISO 8601-1:2019 format (e.g.: `2021-08-03T14:16:18.329Z`).", + "type": "string", + "format": "date-time" + }, + "updated_time": { + "description": "The time of the style rule list when it was last updated in the ISO 8601-1:2019 format (e.g.: `2022-08-03T14:16:18.329Z`).", + "type": "string", + "format": "date-time" + }, + "language": { + "$ref": "#/components/schemas/StyleRuleLanguage" + }, + "version": { + "description": "The version of the style rule list. Incremented when the style rule list is updated.", + "type": "integer", + "example": 13 + }, + "configured_rules": { + "$ref": "#/components/schemas/ConfiguredRules" + }, + "custom_instructions": { + "type": "array", + "description": "List of custom instructions enabled for the style rule list.", + "items": { + "$ref": "#/components/schemas/CustomInstruction" + } + } + } + }, + "StyleId": { + "type": "string", + "description": "A unique ID assigned to a style rule list.", + "example": "bd0a38f3-1831-440b-a8dd-2c702e2325ab" + }, + "StyleRuleLanguage": { + "description": "The language that the style rule list is applied to.", + "type": "string", + "enum": [ + "de", + "en", + "es", + "fr", + "it", + "ja", + "ko", + "zh" + ] + }, + "StyleRuleName": { + "description": "Name associated with the style rule list.", + "type": "string" + }, + "DocumentTranslationError": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "detailed error message" + } + } + }, + "DocumentKey": { + "type": "object", + "required": [ + "document_key" + ], + "properties": { + "document_key": { + "description": "The document encryption key that was sent to the client when the document was uploaded to the API.", + "type": "string", + "example": "0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A" + } + } + }, + "Formality": { + "description": "Sets whether the translated text should lean towards formal or informal language.\nThis feature is only available for certain target languages. Setting this parameter \nwith a target language that does not support formality will fail, unless one of the \n`prefer_...` options are used.\nPossible options are:\n * `default` (default)\n * `more` - for a more formal language\n * `less` - for a more informal language\n * `prefer_more` - for a more formal language if available, otherwise fallback to default formality\n * `prefer_less` - for a more informal language if available, otherwise fallback to default formality", + "type": "string", + "enum": [ + "default", + "more", + "less", + "prefer_more", + "prefer_less" + ], + "default": "default", + "example": "prefer_more" + }, + "GlossaryDictionary": { + "type": "object", + "description": "A dictionary contained in a multilingual glossary. Each dictionary contains the mapping of source terms to target language terms.", + "properties": { + "source_lang": { + "$ref": "#/components/schemas/GlossarySourceLanguage" + }, + "target_lang": { + "$ref": "#/components/schemas/GlossaryTargetLanguage" + }, + "entries": { + "$ref": "#/components/schemas/GlossaryEntries" + }, + "entries_format": { + "$ref": "#/components/schemas/GlossaryEntriesFormat" + } + } + }, + "GlossaryEntries": { + "type": "string", + "description": "The entries of the glossary. The entries have to be specified in the format provided by the `entries_format` parameter.", + "example": "Hello\tGuten Tag" + }, + "GlossaryEntriesFormat": { + "description": "The format in which the glossary entries are provided. Formats currently available:\n- `tsv` (default) - tab-separated values\n- `csv` - comma-separated values\n\nSee [Supported Glossary Formats](/api-reference/multilingual-glossaries#formats) for details about each format.", + "type": "string", + "enum": [ + "tsv", + "csv" + ], + "example": "tsv", + "default": "tsv" + }, + "GlossaryEntryCount": { + "description": "The number of entries in the glossary.", + "type": "integer" + }, + "GlossaryId": { + "type": "string", + "description": "A unique ID assigned to a glossary.", + "example": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7" + }, + "GlossaryName": { + "description": "Name associated with the glossary.", + "type": "string" + }, + "GlossarySourceLanguage": { + "type": "string", + "description": "The language in which the source texts in the glossary are specified.", + "enum": [ + "ar", + "bg", + "cs", + "da", + "de", + "el", + "en", + "es", + "et", + "fi", + "fr", + "he", + "hu", + "id", + "it", + "ja", + "ko", + "lt", + "lv", + "nb", + "nl", + "pl", + "pt", + "ro", + "ru", + "sk", + "sl", + "sv", + "th", + "tr", + "uk", + "vi", + "zh" + ], + "example": "en" + }, + "GlossaryTargetLanguage": { + "type": "string", + "description": "The language in which the target texts in the glossary are specified.", + "enum": [ + "ar", + "bg", + "cs", + "da", + "de", + "el", + "en", + "es", + "et", + "fi", + "fr", + "he", + "hu", + "id", + "it", + "ja", + "ko", + "lt", + "lv", + "nb", + "nl", + "pl", + "pt", + "ro", + "ru", + "sk", + "sl", + "sv", + "th", + "tr", + "uk", + "vi", + "zh" + ], + "example": "de" + }, + "ModelType": { + "type": "string", + "description": "Specifies which DeepL model should be used for translation.", + "enum": [ + "quality_optimized", + "prefer_quality_optimized", + "latency_optimized" + ] + }, + "MonolingualGlossary": { + "type": "object", + "properties": { + "glossary_id": { + "$ref": "#/components/schemas/GlossaryId" + }, + "name": { + "description": "Name associated with the glossary.", + "type": "string" + }, + "ready": { + "description": "Indicates if the newly created glossary can already be used in `translate` requests.\nIf the created glossary is not yet ready, you have to wait and check the `ready` status\nof the glossary before using it in a `translate` request.", + "type": "boolean" + }, + "source_lang": { + "$ref": "#/components/schemas/GlossarySourceLanguage" + }, + "target_lang": { + "$ref": "#/components/schemas/GlossaryTargetLanguage" + }, + "creation_time": { + "description": "The creation time of the glossary in the ISO 8601-1:2019 format (e.g.: `2021-08-03T14:16:18.329Z`).", + "type": "string", + "format": "date-time" + }, + "entry_count": { + "description": "The number of entries in the glossary.", + "type": "integer" + } + }, + "example": { + "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7", + "ready": true, + "name": "My Glossary", + "source_lang": "en", + "target_lang": "de", + "creation_time": "2021-08-03T14:16:18.329Z", + "entry_count": 1 + } + }, + "MultilingualGlossary": { + "type": "object", + "properties": { + "glossary_id": { + "$ref": "#/components/schemas/GlossaryId" + }, + "name": { + "$ref": "#/components/schemas/GlossaryName" + }, + "dictionaries": { + "description": "List of dictionaries contained in this glossary.\nEach dictionary contains a source and target language, as well as pairs of source and target entries.", + "type": "array", + "items": { + "$ref": "#/components/schemas/GlossaryDictionary" + } + }, + "creation_time": { + "description": "The creation time of the glossary in the ISO 8601-1:2019 format (e.g.: `2021-08-03T14:16:18.329Z`).", + "type": "string", + "format": "date-time" + } + }, + "example": { + "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7", + "name": "My Glossary", + "dictionaries": [ + { + "source_lang": "en", + "target_lang": "de", + "entry_count": 1 + } + ], + "creation_time": "2021-08-03T14:16:18.329Z" + } + }, + "MultilingualGlossaryEntries": { + "type": "object", + "properties": { + "source_lang": { + "$ref": "#/components/schemas/GlossarySourceLanguage" + }, + "target_lang": { + "$ref": "#/components/schemas/GlossaryTargetLanguage" + }, + "entries": { + "$ref": "#/components/schemas/GlossaryEntries" + }, + "entries_format": { + "$ref": "#/components/schemas/GlossaryEntriesFormat" + } + } + }, + "MultilingualGlossaryEntriesResponse": { + "type": "object", + "properties": { + "dictionaries": { + "type": "array", + "items": { + "$ref": "#/components/schemas/MultilingualGlossaryEntriesInformation" + } + } + } + }, + "MultilingualGlossaryEntriesInformation": { + "type": "object", + "properties": { + "source_lang": { + "$ref": "#/components/schemas/GlossarySourceLanguage" + }, + "target_lang": { + "$ref": "#/components/schemas/GlossaryTargetLanguage" + }, + "entry_count": { + "$ref": "#/components/schemas/GlossaryEntryCount" + } + } + }, + "OutlineDetectionOption": { + "description": "Disable the automatic detection of XML structure by setting the `outline_detection` parameter \nto `false` and selecting the tags that should be considered structure tags. This will split sentences \nusing the `splitting_tags` parameter.", + "type": "boolean", + "default": true + }, + "OutlineDetectionOptionStr": { + "description": "Disable the automatic detection of XML structure by setting the `outline_detection` parameter \nto `false` and selecting the tags that should be considered structure tags. This will split sentences \nusing the `splitting_tags` parameter.", + "type": "string", + "default": "1", + "enum": [ + "0" + ] + }, + "PatchMultilingualGlossaryParameters": { + "type": "object", + "properties": { + "name": { + "$ref": "#/components/schemas/GlossaryId" + }, + "dictionaries": { + "description": "Dictionaries to edit the glossary with. Currently only supports 0 or 1 dictionaries in the array.", + "type": "array", + "items": { + "$ref": "#/components/schemas/GlossaryDictionary" + } + } + } + }, + "PreserveFormattingOption": { + "description": "Sets whether the translation engine should respect the original formatting, even if it would usually \ncorrect some aspects.", + "type": "boolean", + "default": false + }, + "PreserveFormattingOptionStr": { + "description": "Sets whether the translation engine should respect the original formatting, even if it would usually \ncorrect some aspects.", + "type": "string", + "enum": [ + "0", + "1" + ], + "default": "0" + }, + "ShowBilledCharacters": { + "description": "When true, the response will include the billed_characters parameter, giving the \nnumber of characters from the request that will be counted by DeepL for billing purposes.", + "type": "boolean" + }, + "SplitSentencesOption": { + "description": "Sets whether the translation engine should first split the input into sentences. \n\nPossible values are:\n * 0 - no splitting at all, whole input is treated as one sentence\n * 1 (default when tag_handling is not set to html) - splits on punctuation and on newlines\n * nonewlines (default when tag_handling=html) - splits on punctuation only, ignoring newlines", + "type": "string", + "enum": [ + "0", + "1", + "nonewlines" + ], + "default": "1", + "example": "1" + }, + "SourceLanguage": { + "type": "string", + "description": "Language of the text to be translated. If this parameter is omitted, the API will attempt to\ndetect the language of the text and translate it.\n\nFor the full list of supported source languages, see [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) or query the [`GET /v3/languages` endpoint](https://developers.deepl.com/api-reference/languages/retrieve-supported-languages-by-product) (beta).", + "example": "EN" + }, + "TranslationMemory": { + "type": "object", + "required": [ + "translation_memory_id", + "name", + "source_language", + "target_languages", + "segment_count" + ], + "properties": { + "translation_memory_id": { + "$ref": "#/components/schemas/TranslationMemoryId" + }, + "name": { + "description": "Name associated with the translation memory.", + "type": "string", + "example": "Legal" + }, + "source_language": { + "$ref": "#/components/schemas/TranslationMemorySourceLanguage" + }, + "target_languages": { + "description": "The list of target languages available in the translation memory.", + "type": "array", + "items": { + "$ref": "#/components/schemas/TranslationMemoryTargetLanguage" + }, + "example": [ + "es", + "de" + ] + }, + "segment_count": { + "description": "The number of segments stored in the translation memory.", + "type": "integer", + "example": 34 + } + } + }, + "TranslationMemoryId": { + "type": "string", + "format": "uuid", + "description": "A unique ID assigned to a translation memory.\n\n**Note:** Requests with the `translation_memory_id` parameter must use the `quality_optimized` model type. Requests combining `translation_memory_id` and `model_type: latency_optimized` will be rejected.", + "example": "a74d88fb-ed2a-4943-a664-a4512398b994" + }, + "TranslationMemorySourceLanguage": { + "description": "The source language of the translation memory.", + "type": "string", + "enum": [ + "de", + "en", + "es", + "fr", + "it", + "ja", + "ko", + "zh" + ], + "example": "en" + }, + "TranslationMemoryTargetLanguage": { + "description": "The list of target languages available in the translation memory. A translation memory's target language must be compatible with the `target_lang` specified in a translation request.", + "type": "string", + "enum": [ + "de", + "en", + "en-gb", + "en-us", + "es", + "es-419", + "fr", + "it", + "ja", + "ko", + "zh", + "zh-hans" + ], + "example": "es" + }, + "TranslationMemoryThreshold": { + "type": "integer", + "description": "The minimum matching percentage required for a translation memory segment to be applied (recommended to be 75% or higher).", + "minimum": 0, + "maximum": 100, + "default": 75, + "example": 75 + }, + "TagHandlingOption": { + "description": "Sets which kind of tags should be handled. Options currently available:\n * `xml`\n * `html`", + "type": "string", + "enum": [ + "xml", + "html" + ], + "example": "html" + }, + "TagHandlingVersionOption": { + "description": "Sets which version of the tag handling algorithm should be used. Options currently available:\n* `v1`: Traditional algorithm (currently the default, will become deprecated in the future).\n* `v2`: Improved algorithm released in October 2025 (will become the default in the future).", + "type": "string", + "enum": [ + "v2", + "v1" + ] + }, + "NonSplittingTagCommaSeparatedList": { + "allOf": [ + { + "$ref": "#/components/schemas/TagCommaSeparatedList" + } + ], + "description": "Comma-separated list of XML tags which never split sentences." + }, + "NonSplittingTagList": { + "allOf": [ + { + "$ref": "#/components/schemas/TagList" + } + ], + "description": "List of XML tags which never split sentences.\n\n\nFor some XML files, finding tags with textual content and splitting sentences using those tags won't yield the best results. The following example shows the engine splitting sentences on `par` tags and proceeding to translate the parts separately, resulting in an incorrect translation:\n * Example request:\n```\nThe firm said it had been conducting an internal investigation.\n```\n * Example response:\n```\nDie Firma sagte, es sei eine gute Idee gewesen. Durchführung einer internen Untersuchung.\n```\n\n\nAs this can lead to bad translations, this type of structure should either be avoided, or the `non_splitting_tags` parameter should be set. The following example shows the same call, with the parameter set to `par`:\n * Example request:\n```\nThe firm said it had been conducting an internal investigation.\n```\n * Example response:\n```\nDie Firma sagte, dass sie eine interne Untersuchung durchgeführt habe.\n```\n\n\nThis time, the sentence is translated as a whole. The XML tags are now considered markup and copied into the translated sentence. As the translation of the words \"had been\" has moved to another position in the German sentence, the two par tags are duplicated (which is expected here)." + }, + "SplittingTagCommaSeparatedList": { + "allOf": [ + { + "$ref": "#/components/schemas/TagCommaSeparatedList" + } + ], + "description": "Comma-separated list of XML tags which always cause splits.\n\n\nSee the example in the `outline_detection` parameter's description." + }, + "SplittingTagList": { + "allOf": [ + { + "$ref": "#/components/schemas/TagList" + } + ], + "description": "List of XML tags which always cause splits.\n\n\nSee the example in the `outline_detection` parameter's description." + }, + "IgnoreTagCommaSeparatedList": { + "allOf": [ + { + "$ref": "#/components/schemas/TagCommaSeparatedList" + } + ], + "description": "Comma-separated list of XML tags that indicate text not to be translated." + }, + "IgnoreTagList": { + "allOf": [ + { + "$ref": "#/components/schemas/TagList" + } + ], + "description": "List of XML tags that indicate text not to be translated." + }, + "TagCommaSeparatedList": { + "description": "Comma-separated list of XML tags.", + "type": "string", + "example": "a,p,span" + }, + "TagList": { + "description": "List of XML tags.", + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "a", + "p", + "span" + ] + }, + "TargetLanguage": { + "type": "string", + "description": "The language into which the text should be translated.\n\nFor the full list of supported target languages, see [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) or query the [`GET /v3/languages` endpoint](https://developers.deepl.com/api-reference/languages/retrieve-supported-languages-by-product) (beta).", + "example": "DE" + }, + "TargetLanguageWrite": { + "type": "string", + "description": "The language for the text improvement.", + "enum": [ + "de", + "en", + "en-GB", + "en-US", + "es", + "fr", + "it", + "ja", + "ko", + "pt", + "pt-BR", + "pt-PT", + "zh", + "zh-Hans" + ], + "example": "de" + }, + "UsageResponse": { + "type": "object", + "properties": { + "character_count": { + "description": "Characters translated so far in the current billing period.", + "type": "integer", + "format": "int64", + "example": 180118 + }, + "character_limit": { + "description": "Current maximum number of characters that can be translated per billing period. If cost control is set, the cost control limit will be returned in this field.", + "type": "integer", + "format": "int64", + "example": 1250000 + }, + "products": { + "type": "array", + "description": "Only present for API Pro users. Per-product usage details.", + "items": { + "type": "object", + "properties": { + "product_type": { + "type": "string", + "description": "The type of product (e.g., 'write', 'translate').", + "example": "write" + }, + "billing_unit": { + "type": "string", + "enum": [ + "characters", + "milliseconds" + ], + "description": "The billing unit for this product type.", + "example": "characters" + }, + "api_key_unit_count": { + "type": "integer", + "description": "Units used for this product by this API key in the current period.", + "example": 0 + }, + "account_unit_count": { + "type": "integer", + "description": "Total units used for this product in the current period.", + "example": 5643 + }, + "api_key_character_count": { + "type": "integer", + "deprecated": true, + "description": "Use api_key_unit_count instead. Characters used for this product by this API key in the current period.\"", + "example": 0 + }, + "character_count": { + "type": "integer", + "deprecated": true, + "description": "Use account_unit_count instead. Total characters used for this product in the current period.\"", + "example": 5643 + } + } + } + }, + "api_key_character_count": { + "type": "integer", + "description": "Only present for API Pro users. Total characters used by this API key in the current period.", + "example": 636 + }, + "api_key_character_limit": { + "type": "integer", + "description": "Only present for API Pro users. Character limit for this API key in the current period.", + "example": 1000000000000 + }, + "speech_to_text_milliseconds_count": { + "type": "integer", + "description": "Only present for API Pro users. Milliseconds of speech-to-text used in the current period.", + "example": 1800000 + }, + "speech_to_text_milliseconds_limit": { + "type": "integer", + "description": "Only present for API Pro users. Milliseconds of speech-to-text limit in the current period.", + "example": 36000000 + }, + "start_time": { + "type": "string", + "format": "date-time", + "description": "Only present for API Pro users. Start time of the current billing period (ISO 8601).", + "example": "2025-05-13T09:18:42Z" + }, + "end_time": { + "type": "string", + "format": "date-time", + "description": "Only present for API Pro users. End time of the current billing period (ISO 8601).", + "example": "2025-06-13T09:18:42Z" + } + } + }, + "VoiceFormality": { + "description": "Sets whether the translated text should lean towards formal or informal language.\nPossible options are:\n * `default` - use the default formality for the target language\n * `formal`/`more` - for a more formal language\n * `informal`/`less` - for a more informal language", + "type": "string", + "enum": [ + "default", + "formal", + "more", + "informal", + "less" + ], + "default": "default", + "example": "formal" + }, + "VoiceMessageFormat": { + "description": "Message encoding format for WebSocket communication. Determines how messages are serialized and transmitted.\nUsing `json`, messages are JSON-encoded and sent as TEXT WebSocket frames. All binary fields (such as audio data) are base64-encoded strings.\nUsing `msgpack`, messages are MessagePack-encoded and sent as BINARY WebSocket frames. All binary fields (such as audio data) contain raw binary data.\n\nFor 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": " 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.\n \n | Content Type | Container | Codec |\n | :------------------------------------ | :------------------------------------------------ | :---------------------------------------- |\n | `audio/auto` | Auto-detect: FLAC / Matroska / MPEG / Ogg / WebM | Auto-detect AAC / FLAC / MP3 / OPUS |\n | `audio/flac` | FLAC (flac) | FLAC |\n | `audio/mpeg` | MPEG (mp3/m4a) | MP3 |\n | `audio/ogg` | Ogg (ogg/oga) | Auto-detect FLAC / OPUS |\n | `audio/webm` | WebM (webm) | OPUS |\n | `audio/x-matroska` | Matroska (mkv/mka) | Auto-detect: AAC / FLAC / MP3 / OPUS |\n | `audio/ogg;codecs=flac` | Ogg (ogg/oga) | FLAC |\n | `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/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 | `audio/x-matroska;codecs=mp3` | Matroska (mkv/mka) | MP3 |\n | `audio/x-matroska;codecs=opus` | Matroska (mkv/mka) | OPUS |\n \n\nWe recommend the following bitrates as good tradeoff between quality and bandwidth:\n - AAC: 96 kbps\n - FLAC: 256 kbps (16000 Hz)\n - MP3: 128 kbps\n - OPUS: 32 kbps (recommendation for low bandwidth scenarios)\n - PCM: 256 kbps (16000 Hz, default recommendation)\n ", + "enum": [ + "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" + ], + "example": "audio/ogg;codecs=opus" + }, + "VoiceSourceLanguage": { + "type": "string", + "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.\nNote: Some source transcription languages are provided through external service partners. See the [supported languages table](/api-reference/voice#show-supported-languages) for details.\n", + "enum": [ + "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": null, + "example": "en" + }, + "VoiceSourceLanguageMode": { + "type": "string", + "description": "Controls how the source_language value is used.\n- `auto`: Treats source language as a hint; server can override\n- `fixed`: Treats source language as mandatory; server must use this language", + "enum": [ + "auto", + "fixed" + ], + "default": "auto", + "example": "fixed" + }, + "VoiceTargetLanguages": { + "type": "array", + "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.\n", + "items": { + "type": "string", + "enum": [ + "ar", + "bg", + "bn", + "cs", + "da", + "de", + "el", + "en", + "en-GB", + "en-US", + "es", + "et", + "fi", + "fr", + "ga", + "he", + "hr", + "hu", + "id", + "it", + "ja", + "ko", + "lt", + "lv", + "mt", + "nb", + "nl", + "pl", + "pt", + "pt-BR", + "pt-PT", + "ro", + "ru", + "sk", + "sl", + "sv", + "th", + "tl", + "tr", + "uk", + "vi", + "zh", + "zh-HANS", + "zh-HANT" + ] + }, + "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.\nNote: Some translated audio languages are provided through external service partners. See the [supported languages table](/api-reference/voice#show-supported-languages) for details.\n", + "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": [ + "streaming_url", + "token" + ], + "properties": { + "streaming_url": { + "type": "string", + "description": "The WebSocket URL to use for establishing [the stream connection](/api-reference/voice/websocket-streaming).\n", + "example": "wss://api.deepl.com/v3/voice/realtime/connect" + }, + "token": { + "type": "string", + "description": "A unique ephemeral token for authentication with the streaming endpoint. Pass this as a query parameter when connecting to [the streaming URL](/api-reference/voice/websocket-streaming). This token is ephemeral and valid for a short time and one-time use only.\n", + "example": "VGhpcyBpcyBhIGZha2UgdG9rZW4K" + }, + "session_id": { + "type": "string", + "description": "Internal use only. A unique identifier for the requested stream.\n", + "example": "4f911080-cfe2-41d4-8269-0e6ec15a0354" + } + } + }, + "WritingStyle": { + "type": "string", + "description": "Specify a style to rephrase your text in a way that fits your audience and goals.\nThe `prefer_` prefix allows falling back to the default style if the language does not yet support styles.", + "enum": [ + "academic", + "business", + "casual", + "default", + "simple", + "prefer_academic", + "prefer_business", + "prefer_casual", + "prefer_simple" + ] + }, + "WritingTone": { + "type": "string", + "description": "Specify the desired tone for your text.\nThe `prefer_` prefix allows falling back to the default tone if the language does not yet support tones.", + "enum": [ + "confident", + "default", + "diplomatic", + "enthusiastic", + "friendly", + "prefer_confident", + "prefer_diplomatic", + "prefer_enthusiastic", + "prefer_friendly" + ] + }, + "AdminUsageReport": { + "type": "object", + "description": "The response for admin usage statistics.", + "properties": { + "usage_report": { + "$ref": "#/components/schemas/AdminUsageReportData" + } + } + }, + "AdminUsageReportData": { + "type": "object", + "description": "Contains the detailed usage statistics for the specified date range.", + "properties": { + "total_usage": { + "$ref": "#/components/schemas/UsageBreakdown" + }, + "start_date": { + "type": "string", + "format": "date-time", + "description": "Start date of the usage report period.", + "example": "2025-09-29T00:00:00" + }, + "end_date": { + "type": "string", + "format": "date-time", + "description": "End date of the usage report period.", + "example": "2025-10-01T00:00:00" + }, + "group_by": { + "type": "string", + "description": "The grouping method used, if any.", + "enum": [ + "key", + "key_and_day" + ], + "example": "key_and_day" + }, + "key_usages": { + "type": "array", + "description": "Usage statistics grouped by key. Present when group_by='key'.", + "items": { + "$ref": "#/components/schemas/KeyUsageItem" + } + }, + "key_and_day_usages": { + "type": "array", + "description": "Usage statistics grouped by key and day. Present when group_by='key_and_day'.", + "items": { + "$ref": "#/components/schemas/KeyAndDayUsageItem" + } + } + } + }, + "UsageBreakdown": { + "type": "object", + "description": "Breakdown of character usage by category.", + "properties": { + "total_characters": { + "type": "integer", + "description": "Total number of characters used.", + "example": 9619 + }, + "text_translation_characters": { + "type": "integer", + "description": "Number of characters used for text translation.", + "example": 4892 + }, + "document_translation_characters": { + "type": "integer", + "description": "Number of characters used for document translation.", + "example": 0 + }, + "text_improvement_characters": { + "type": "integer", + "description": "Number of characters used for text improvement.", + "example": 4727 + }, + "speech_to_text_minutes": { + "type": "number", + "description": "Duration of speech-to-text usage in minutes.", + "example": 107.46 + } + } + }, + "KeyAndDayUsageItem": { + "type": "object", + "description": "Usage statistics for a specific API key and optionally a specific date.", + "properties": { + "api_key": { + "type": "string", + "description": "Masked API key identifier.", + "example": "db96****cb2c" + }, + "api_key_label": { + "type": "string", + "description": "Label associated with the API key.", + "example": "DeepL API Key Prod" + }, + "usage_date": { + "type": "string", + "format": "date-time", + "description": "The usage date. Only present when group_by is \"key_and_day\".", + "example": "2025-09-29T00:00:00Z" + }, + "usage": { + "$ref": "#/components/schemas/UsageBreakdown" + } + } + }, + "KeyUsageItem": { + "type": "object", + "description": "Usage statistics for a specific API key and optionally a specific date.", + "properties": { + "api_key": { + "type": "string", + "description": "Masked API key identifier.", + "example": "db96****cb2c" + }, + "api_key_label": { + "type": "string", + "description": "Label associated with the API key.", + "example": "DeepL API Key Prod" + }, + "usage": { + "$ref": "#/components/schemas/UsageBreakdown" + } + } + } + } + } +} diff --git a/api-reference/voice/voice.asyncapi.json b/api-reference/voice/voice.asyncapi.json new file mode 100644 index 00000000..2a12ce98 --- /dev/null +++ b/api-reference/voice/voice.asyncapi.json @@ -0,0 +1,742 @@ +{ + "asyncapi": "3.0.0", + "info": { + "title": "DeepL Voice API - WebSocket Streaming", + "version": "1.0.0", + "description": "WebSocket streaming API for real-time voice transcription and translation. After obtaining a streaming URL and token via the REST API, establish a WebSocket connection to stream audio data and receive real-time transcriptions and translations.\nThe API supports two message encoding formats: JSON (default) and MessagePack. The encoding format is configured via the message_format parameter when requesting a session. JSON format uses TEXT WebSocket frames. Fields with binary data (such as audio chunks) are base64-encoded strings, while MessagePack format uses BINARY WebSocket frames where fields with binary data contain raw binary data. Compared to JSON, MessagePack typically reduces bandwidth usage by 25-30% and improves message encoding/decoding speed by 2x-4x.\nWhen using MessagePack encoding, messages must be encoded as maps with string keys, not as arrays. The message structure must match the JSON schema exactly, with all field names preserved as string keys. Array-based or integer-keyed encoding is not supported.\n", + "contact": { + "name": "DeepL - Contact us", + "url": "https://www.deepl.com/contact-us" + } + }, + "servers": { + "production": { + "host": "api.deepl.com", + "pathname": "/v3/voice/realtime/connect", + "protocol": "wss", + "description": "DeepL Voice API WebSocket endpoint.", + "variables": { + "token": { + "description": "This is the ephemeral authentication token obtained from the REST API", + "examples": [ + "VGhpcyBpcyBhIGZha2UgdG9rZW4K" + ] + } + } + } + }, + "channels": { + "voiceStream": { + "address": "/v3/voice/realtime/connect?token={token}", + "description": "WebSocket channel for streaming audio and receiving transcriptions and translations. Messages are exchanged in JSON or MessagePack format. WebSocket messages are exchanged in TEXT frames when using JSON format and in BINARY frames when using MessagePack format. Sending the wrong frame type will result in connection errors.\n", + "parameters": { + "token": { + "description": "This is the ephemeral authentication token obtained from the [Request Session](/api-reference/voice/request-session) endpoint. The token is valid for one-time use only and must be passed as a query parameter when establishing the WebSocket connection.\n", + "examples": [ + "VGhpcyBpcyBhIGZha2UgdG9rZW4K" + ] + } + }, + "messages": { + "SourceMediaChunk": { + "$ref": "#/components/messages/SourceMediaChunk" + }, + "EndOfSourceMedia": { + "$ref": "#/components/messages/EndOfSourceMedia" + }, + "SourceTranscriptUpdate": { + "$ref": "#/components/messages/SourceTranscriptUpdate" + }, + "TargetTranscriptUpdate": { + "$ref": "#/components/messages/TargetTranscriptUpdate" + }, + "TargetMediaChunk": { + "$ref": "#/components/messages/TargetMediaChunk" + }, + "EndOfSourceTranscript": { + "$ref": "#/components/messages/EndOfSourceTranscript" + }, + "EndOfTargetTranscript": { + "$ref": "#/components/messages/EndOfTargetTranscript" + }, + "EndOfTargetMedia": { + "$ref": "#/components/messages/EndOfTargetMedia" + }, + "EndOfStream": { + "$ref": "#/components/messages/EndOfStream" + }, + "Error": { + "$ref": "#/components/messages/Error" + } + } + } + }, + "operations": { + "sendAudioData": { + "action": "send", + "channel": { + "$ref": "#/channels/voiceStream" + }, + "summary": "Send audio data to the server", + "description": "Send audio chunks and control messages to the server.\nAudio data must be base64-encoded and match the configured format.", + "messages": [ + { + "$ref": "#/channels/voiceStream/messages/SourceTranscriptUpdate" + }, + { + "$ref": "#/channels/voiceStream/messages/TargetTranscriptUpdate" + }, + { + "$ref": "#/channels/voiceStream/messages/TargetMediaChunk" + }, + { + "$ref": "#/channels/voiceStream/messages/EndOfSourceTranscript" + }, + { + "$ref": "#/channels/voiceStream/messages/EndOfTargetTranscript" + }, + { + "$ref": "#/channels/voiceStream/messages/EndOfTargetMedia" + }, + { + "$ref": "#/channels/voiceStream/messages/EndOfStream" + }, + { + "$ref": "#/channels/voiceStream/messages/Error" + } + ] + }, + "receiveTranscriptions": { + "action": "receive", + "channel": { + "$ref": "#/channels/voiceStream" + }, + "summary": "Receive transcriptions and translations", + "description": "Receive real-time transcription and translation messages from the server.\nThe server sends transcript updates, translated audio chunks, end of transcript notifications and errors.", + "messages": [ + { + "$ref": "#/channels/voiceStream/messages/SourceMediaChunk" + }, + { + "$ref": "#/channels/voiceStream/messages/EndOfSourceMedia" + } + ] + } + }, + "components": { + "messages": { + "SourceMediaChunk": { + "name": "SourceMediaChunk", + "title": "Source Media Chunk", + "description": " The message contains a chunk of audio data. The audio encoding must be the same that was specified in the [Request Session](/api-reference/voice/request-session) request. \n\n When using JSON format, the audio data is base64-encoded. When using MessagePack format, the audio data is raw binary data. \n\n The chunk size must not be more than 100 kilobyte or one second in duration. The recommended duration is 50 - 250 milliseconds to achieve the best tradeoff between latency and quality. The interval between chunks must not be less than half of the duration of the preceding chunk and not exceed 30 seconds. Otherwise you will run into rate limits or the session will terminate due to timing out and the connection will be closed. \n\n For PCM data the chunk size must be a multiple of the frame size aka encoding unit.", + "contentType": "application/json", + "payload": { + "$ref": "#/components/schemas/SourceMediaChunkPayload" + }, + "examples": [ + { + "name": "SourceMediaChunk", + "summary": "Source media chunk", + "payload": { + "source_media_chunk": { + "data": "VGhpcyBpcyBhIGZha2UgYXVkaW8gY2h1bmsK" + } + } + } + ] + }, + "EndOfSourceMedia": { + "name": "EndOfSourceMedia", + "title": "End of Source Media", + "description": "The message indicates the end of source media data. It causes the finalization of tentative transcript segments and triggers the emission of final transcript updates, end of transcript messages and the end of stream message. No more data chunks can be sent afterwards. It marks the end of the stream input.\n", + "contentType": "application/json", + "payload": { + "$ref": "#/components/schemas/EndOfSourceMediaPayload" + }, + "examples": [ + { + "name": "EndStream", + "summary": "End of audio stream", + "payload": { + "end_of_source_media": {} + } + } + ] + }, + "SourceTranscriptUpdate": { + "name": "SourceTranscriptUpdate", + "title": "Source Transcript Update", + "description": " The message contains an update to the transcription of the supplied media in the *source* language. \n\n Each message is an incremental addition to the already received updates of the *source* transcript with concluded and tentative text segments. Concluded segments are fixed and will only appear once, while tentative segments may be updated in subsequent messages as more audio is processed. \n\n Clients should merge the concluded segments into a final transcript and update the tentative segments as new updates arrive.", + "contentType": "application/json", + "payload": { + "$ref": "#/components/schemas/SourceTranscriptUpdatePayload" + }, + "examples": [ + { + "name": "TranscriptUpdate", + "summary": "Source language transcript update", + "payload": { + "source_transcript_update": { + "concluded": [ + { + "language": "en", + "text": "Hello, how are you", + "start_time": 0, + "end_time": 1500 + } + ], + "tentative": [ + { + "language": "en", + "text": " today?", + "start_time": 1500, + "end_time": 2000 + } + ] + } + } + } + ] + }, + "TargetTranscriptUpdate": { + "name": "TargetTranscriptUpdate", + "title": "Target Transcript Update", + "description": " The message contains an update to the transcription of the supplied media in the *target* language. \n\n Each message is an incremental addition to the already received updates of the *target* transcript with concluded and tentative text segments. Concluded segments are fixed and will only appear once, while tentative segments may be updated in subsequent messages as more audio is processed. \n\n Clients should merge the concluded segments into a final transcript and update the tentative segments as new updates arrive.", + "contentType": "application/json", + "payload": { + "$ref": "#/components/schemas/TargetTranscriptUpdatePayload" + }, + "examples": [ + { + "name": "TranslationUpdate", + "summary": "Target language translation update", + "payload": { + "target_transcript_update": { + "language": "es", + "concluded": [ + { + "text": "Hola, ¿cómo estás", + "start_time": 0, + "end_time": 1500 + } + ], + "tentative": [ + { + "text": " hoy?", + "start_time": 1500, + "end_time": 2000 + } + ] + } + } + } + ] + }, + "TargetMediaChunk": { + "name": "TargetMediaChunk", + "title": "Target Media Chunk", + "description": " (closed beta) The message contains translated audio data in the target language. \n\n The audio data is provided as an array of base64-encoded indivisible chunks (e.g., codec packets or container pages/clusters). The first message of this type includes the content type and optional headers field. The `headers` field (when present) indicates how many packets at the start of the `data` array contain initialization/header data required by the decoder. For containerized formats, all packets can be passed directly to the demuxer. For raw codec formats with headers, the header packets must be used to initialize the decoder before processing subsequent audio packets. When `headers` is `null` or absent, all packets in the `data` array are audio data. \n\n The audio stream contains only synthesized speech segments, without silence or padding. \n\n Clients should decode and play back the audio chunks in the order received and sequence given in `data`. For subtitle synchronization, use the `text` field to identify subtitle segments and accumulate `duration` values to calculate total playback time for each subtitle.", + "contentType": "application/json", + "payload": { + "$ref": "#/components/schemas/TargetMediaChunkPayload" + }, + "examples": [ + { + "name": "TargetMediaChunkFirst", + "summary": "First target media chunk with headers", + "payload": { + "target_media_chunk": { + "language": "de", + "content_type": "audio/webm;codecs=opus;", + "headers": 1, + "data": [ + "GkXfo59ChoEBQveBAULygQRC84EIQoKEd0VFSUgBU0WIQo17hEgBc0WjgQBBxYWIAvLhEKBjYEfA", + "H0O2dBUMRQyBElkIBE9nZ1MAAgAAAAAAAAAAtJhTXAAAAAAAoyC5AQAAAAA=", + "H0O2dBUMRQyBElkIBE9nZ1MAAAAAAAAAAAAAtJhTXAIAAAAAamZ0BwE=" + ], + "duration": 2400, + "text": "Hallo, wie geht es dir heute?" + } + } + }, + { + "name": "TargetMediaChunkSubsequent", + "summary": "Subsequent target media chunk", + "payload": { + "target_media_chunk": { + "language": "de", + "data": [ + "H0O2dBUMRQyBElkIBE9nZ1MAAQAAAAAAAAAAtJhTXAMAAAAAcGh1CAE=", + "H0O2dBUMRQyBElkIBE9nZ1MAAgAAAAAAAAAAtJhTXAQAAAAAdGltZQkB" + ], + "duration": 1800 + } + } + }, + { + "name": "TargetMediaChunkRawOpus", + "summary": "Raw Opus with RFC 7845 header", + "payload": { + "target_media_chunk": { + "language": "de", + "content_type": "audio/opus", + "headers": 1, + "data": [ + "T3B1c0hlYWQBAgA8AABAC0AAAAAA", + "z/nldGFnAAAAAAAAAAAAAAAAAAAA", + "KP9J1XN0YXJ0IG9mIGF1ZGlvIGRhdGE=" + ], + "duration": 3200, + "text": "Guten Tag" + } + } + }, + { + "name": "TargetMediaChunkRawPCM", + "summary": "Raw PCM without headers", + "payload": { + "target_media_chunk": { + "language": "de", + "content_type": "audio/pcm;encoding=s16le;rate=24000", + "data": [ + "AAEAAgADAAQABQAGAAcACAAJAAoACwAMAA0ADgAPABAAEQASABMAFAAVABYAFw==" + ], + "duration": 1500, + "text": "Willkommen" + } + } + } + ] + }, + "EndOfSourceTranscript": { + "name": "EndOfSourceTranscript", + "title": "End of Source Transcript", + "description": "The message indicates that the *source* transcript is complete and no further updates will be sent. It gets emitted after client sends End of Source Media.\n", + "contentType": "application/json", + "payload": { + "$ref": "#/components/schemas/EndOfSourceTranscriptPayload" + }, + "examples": [ + { + "name": "EndSource", + "summary": "Source transcript complete", + "payload": { + "end_of_source_transcript": {} + } + } + ] + }, + "EndOfTargetTranscript": { + "name": "EndOfTargetTranscript", + "title": "End of Target Transcript", + "description": "This message indicates that the *target* transcript is complete and no further updates will be sent. It gets emitted after client sends End of Source Media.\n", + "contentType": "application/json", + "payload": { + "$ref": "#/components/schemas/EndOfTargetTranscriptPayload" + }, + "examples": [ + { + "name": "EndTarget", + "summary": "Target transcript complete", + "payload": { + "end_of_target_transcript": { + "language": "fr" + } + } + } + ] + }, + "EndOfTargetMedia": { + "name": "EndOfTargetMedia", + "title": "End of Target Media", + "description": "(closed beta) This message indicates that the *target* media stream is complete and no further audio chunks will be sent for this target language. It gets emitted after client sends End of Source Media and all target audio has been sent.\n", + "contentType": "application/json", + "payload": { + "$ref": "#/components/schemas/EndOfTargetMediaPayload" + }, + "examples": [ + { + "name": "EndTargetMedia", + "summary": "Target media complete", + "payload": { + "end_of_target_media": { + "language": "es" + } + } + } + ] + }, + "EndOfStream": { + "name": "EndOfStream", + "title": "End of Stream", + "description": "This message indicates that all outputs are complete and the stream ended. It is the very last message the client will receive after it sends End of Source Media. You can safely close the connection after you received this message.\n", + "contentType": "application/json", + "payload": { + "$ref": "#/components/schemas/EndOfStreamPayload" + }, + "examples": [ + { + "name": "EndStream", + "summary": "Stream ended", + "payload": { + "end_of_stream": {} + } + } + ] + }, + "Error": { + "name": "Error", + "title": "Error", + "description": "This message reports errors encountered during audio processing or streaming. It includes an error code, reason code, and a human-readable message. After an error, the session is terminated and reconnection is not possible. You need to request a new session.\n", + "contentType": "application/json", + "payload": { + "$ref": "#/components/schemas/ErrorPayload" + }, + "examples": [ + { + "name": "AudioFormatError", + "summary": "Audio format error", + "payload": { + "error": { + "request_type": "source_media_chunk", + "error_code": 400, + "reason_code": 4000403, + "error_message": "Audio format not supported" + } + } + } + ] + } + }, + "schemas": { + "SourceMediaChunkPayload": { + "type": "object", + "required": [ + "source_media_chunk" + ], + "properties": { + "source_media_chunk": { + "type": "object", + "required": [ + "data" + ], + "properties": { + "data": { + "type": "string", + "format": "binary", + "description": "Audio data in the audio format specified during session initialization. Encoded as base64 string when using JSON. Raw binary data when using MessagePack.\n" + } + } + } + } + }, + "EndOfSourceMediaPayload": { + "type": "object", + "required": [ + "end_of_source_media" + ], + "properties": { + "end_of_source_media": { + "type": "object", + "description": "Empty object signaling end of media stream" + } + } + }, + "TranscriptSegment": { + "type": "object", + "required": [ + "text", + "start_time", + "end_time" + ], + "properties": { + "text": { + "type": "string", + "description": "Source or target transcript text" + }, + "start_time": { + "type": "integer", + "description": "Estimated start time of the segment in the input stream in milliseconds", + "examples": [ + 1250 + ] + }, + "end_time": { + "type": "integer", + "description": "Estimated end time of the segment in the input stream in milliseconds", + "examples": [ + 1570 + ] + } + } + }, + "SourceTranscriptSegment": { + "allOf": [ + { + "$ref": "#/components/schemas/TranscriptSegment" + }, + { + "type": "object", + "required": [ + "language" + ], + "properties": { + "language": { + "type": "string", + "description": "IETF BCP 47 language tag of the detected source language", + "examples": [ + "en" + ] + } + } + } + ] + }, + "SourceTranscriptUpdatePayload": { + "type": "object", + "required": [ + "source_transcript_update" + ], + "properties": { + "source_transcript_update": { + "type": "object", + "required": [ + "concluded", + "tentative" + ], + "properties": { + "concluded": { + "type": "array", + "description": "Array of fixed transcript segments that will not change anymore. Array objects contain `language` property of type `string` (IETF BCP 47 language tag of the detected source language), `text` property of type `string` (Source or target transcript text), `start_time` property of type `integer` (Estimated start time of the segment in the input stream in milliseconds) and `end_time` property of type `integer` (Estimated end time of the segment in the input stream in milliseconds).\n", + "items": { + "$ref": "#/components/schemas/SourceTranscriptSegment" + } + }, + "tentative": { + "type": "array", + "description": "Array of preliminary transcript segments that are subject to change. Array objects contain `language` property of type `string` (IETF BCP 47 language tag of the detected source language), `text` property of type `string` (Source or target transcript text), `start_time` property of type `integer` (Estimated start time of the segment in the input stream in milliseconds) and `end_time` property of type `integer` (Estimated end time of the segment in the input stream in milliseconds).\n", + "items": { + "$ref": "#/components/schemas/SourceTranscriptSegment" + } + } + } + } + } + }, + "TargetTranscriptUpdatePayload": { + "type": "object", + "required": [ + "target_transcript_update" + ], + "properties": { + "target_transcript_update": { + "type": "object", + "required": [ + "language", + "concluded", + "tentative" + ], + "properties": { + "language": { + "type": "string", + "description": "IETF BCP 47 language tag of the target language", + "examples": [ + "es" + ] + }, + "concluded": { + "type": "array", + "description": "Array of fixed transcript segments that will not change anymore. Array objects contain `text` property of type `string` (Source or target transcript text), `start_time` property of type `integer` (Estimated start time of the segment in the input stream in milliseconds) and `end_time` property of type `integer` (Estimated end time of the segment in the input stream in milliseconds).\n", + "items": { + "$ref": "#/components/schemas/TranscriptSegment" + } + }, + "tentative": { + "type": "array", + "description": "Array of preliminary transcript segments that are subject to change. Array objects contain `text` property of type `string` (Source or target transcript text), `start_time` property of type `integer` (Estimated start time of the segment in the input stream in milliseconds) and `end_time` property of type `integer` (Estimated end time of the segment in the input stream in milliseconds).\n", + "items": { + "$ref": "#/components/schemas/TranscriptSegment" + } + } + } + } + } + }, + "TargetMediaChunkPayload": { + "type": "object", + "required": [ + "target_media_chunk" + ], + "properties": { + "target_media_chunk": { + "type": "object", + "required": [ + "language", + "data", + "duration" + ], + "properties": { + "language": { + "type": "string", + "description": "IETF BCP 47 language tag of the target media language", + "examples": [ + "de" + ] + }, + "content_type": { + "type": "string", + "description": "(Optional) MIME type of the audio stream. Only present in the first message of this type.", + "examples": [ + "audio/webm;codecs=opus;" + ] + }, + "headers": { + "type": "integer", + "description": "(Optional) Number of packets at the start of the data array that contain initialization/header data. Only present in the first message of this type. When present, the first N elements in the data array (where N equals the headers value) contain header/initialization data required by the decoder, and subsequent elements contain audio packets. For containerized formats, all packets can be passed directly to the demuxer. For raw codec formats, header packets must be used to initialize the decoder before processing audio packets. When null or absent, all packets are audio data.", + "examples": [ + 1 + ] + }, + "data": { + "type": "array", + "description": "Array of indivisible chunks of audio data (e.g., codec packets or container pages/clusters). Each element is encoded as base64 string when using JSON message format, or raw binary data when using MessagePack message format. When the headers field is present, the first N elements contain header data, and subsequent elements contain audio packets.", + "items": { + "type": "string", + "format": "byte" + } + }, + "duration": { + "type": "integer", + "description": "The total playback duration of all audio data in this chunk, measured in milliseconds. Accumulate duration values across chunks belonging to the same text segment to determine the total playback time for that subtitle. Also useful for synchronization, buffering calculations, and determining the timing of subsequent chunks.", + "examples": [ + 2400 + ] + }, + "text": { + "type": "string", + "description": "(Optional) The target transcript segment from which this audio was synthesized. Present only in the first audio chunk belonging to a new transcript segment. Subsequent audio chunks for the same transcript segment will have this field set to null. Multiple audio chunks can belong to the same text segment. The cumulative content of this field across all chunks matches the cumulative target transcript received via target transcript updates. This allows clients to associate audio chunks with their corresponding transcript segments and display synchronized captions or subtitles during playback." + } + } + } + } + }, + "EndOfSourceTranscriptPayload": { + "type": "object", + "required": [ + "end_of_source_transcript" + ], + "properties": { + "end_of_source_transcript": { + "type": "object", + "description": "Empty object indicating source transcript is complete" + } + } + }, + "EndOfTargetTranscriptPayload": { + "type": "object", + "required": [ + "end_of_target_transcript" + ], + "properties": { + "end_of_target_transcript": { + "type": "object", + "required": [ + "language" + ], + "properties": { + "language": { + "type": "string", + "description": "IETF BCP 47 language tag indicating which target transcript has ended", + "examples": [ + "fr" + ] + } + } + } + } + }, + "EndOfTargetMediaPayload": { + "type": "object", + "required": [ + "end_of_target_media" + ], + "properties": { + "end_of_target_media": { + "type": "object", + "required": [ + "language" + ], + "properties": { + "language": { + "type": "string", + "description": "IETF BCP 47 language tag indicating which target media stream has ended", + "examples": [ + "es" + ] + } + } + } + } + }, + "EndOfStreamPayload": { + "type": "object", + "required": [ + "end_of_stream" + ], + "properties": { + "end_of_stream": { + "type": "object", + "description": "Empty object indicating all outputs are complete" + } + } + }, + "ErrorPayload": { + "type": "object", + "required": [ + "error" + ], + "properties": { + "error": { + "type": "object", + "required": [ + "request_type", + "error_code", + "reason_code", + "error_message" + ], + "properties": { + "request_type": { + "type": "string", + "description": "The type of request that caused the error", + "examples": [ + "source_media_chunk" + ] + }, + "error_code": { + "type": "integer", + "description": "HTTP-style error code", + "examples": [ + 400 + ] + }, + "reason_code": { + "type": "integer", + "description": "Detailed reason code for debugging", + "examples": [ + 4000403 + ] + }, + "error_message": { + "type": "string", + "description": "Human-readable error description", + "examples": [ + "Audio format not supported" + ] + } + } + } + } + } + } + } +}