diff --git a/CHANGELOG.md b/CHANGELOG.md index 7119ab9..5d1566b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,14 @@ number is used only for corrections to the OpenAPI specification, for example: typos, schema fixes, or adding examples. +### [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 @@ -156,6 +164,7 @@ typos, schema fixes, or adding examples. Initial release of the OpenAPI specification. +[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 diff --git a/openapi.json b/openapi.json index 198838b..ecbabc7 100644 --- a/openapi.json +++ b/openapi.json @@ -8,7 +8,7 @@ "name": "DeepL - Contact us", "url": "https://www.deepl.com/contact-us" }, - "version": "2.16.0" + "version": "2.17.0" }, "externalDocs": { "description": "DeepL Pro - Plans and pricing", @@ -63,9 +63,8 @@ ], "properties": { "text": { - "description": "Text to be translated. Only UTF-8-encoded plain text is supported. The parameter may be specified\nmultiple times and translations are returned in the same order as they are requested. Each of the\nparameter values may contain multiple sentences. Up to 50 texts can be sent for translation in one\nrequest.", + "description": "Text to be translated. Only UTF-8-encoded plain text is supported. The parameter may be specified\nmultiple times and translations are returned in the same order as they are requested. Each of the\nparameter values may contain multiple sentences.", "type": "array", - "maxItems": 50, "items": { "type": "string", "example": "Hello, World!" @@ -92,6 +91,9 @@ "formality": { "$ref": "#/components/schemas/Formality" }, + "model_type": { + "$ref": "#/components/schemas/ModelType" + }, "glossary_id": { "allOf": [ { @@ -199,6 +201,9 @@ "formality": { "$ref": "#/components/schemas/Formality" }, + "model_type": { + "$ref": "#/components/schemas/ModelType" + }, "glossary_id": { "allOf": [ { @@ -262,6 +267,11 @@ "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" + }, + "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" } } } @@ -1748,6 +1758,15 @@ ], "default": "default" }, + "ModelType": { + "type": "string", + "description": "Specifies which DeepL model should be used for translation.\n\nPossible values are:\n* `latency_optimized` (default) - uses lower latency \u201cclassic\u201d translation models, which support all language pairs; \n default value \n* `quality_optimized` - uses higher latency, improved quality \u201cnext-gen\u201d translation models, which support only a\n subset of language pairs; if a language pair that is not supported by next-gen models is included in the\n request, it will fail. Consider using prefer_quality_optimized instead. \n* `prefer_quality_optimized` - prioritizes use of higher latency, improved quality \u201cnext-gen\u201d translation models,\n which support only a subset of DeepL languages; if a request includes a language pair not supported by \n next-gen models, the request will fall back to latency_optimized classic models.", + "enum": [ + "quality_optimized", + "prefer_quality_optimized", + "latency_optimized" + ] + }, "GlossaryId": { "type": "string", "description": "A unique ID assigned to a glossary.", diff --git a/openapi.yaml b/openapi.yaml index 9196267..7a0ebae 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -7,7 +7,7 @@ info: contact: name: DeepL - Contact us url: https://www.deepl.com/contact-us - version: 2.16.0 + version: 2.17.0 externalDocs: description: DeepL Pro - Plans and pricing url: https://www.deepl.com/pro#developer?cta=header-prices/ @@ -125,10 +125,8 @@ paths: description: |- Text to be translated. Only UTF-8-encoded plain text is supported. The parameter may be specified multiple times and translations are returned in the same order as they are requested. Each of the - parameter values may contain multiple sentences. Up to 50 texts can be sent for translation in one - request. + parameter values may contain multiple sentences. type: array - maxItems: 50 items: type: string example: Hello, World! @@ -146,6 +144,8 @@ paths: $ref: '#/components/schemas/PreserveFormattingOption' formality: $ref: '#/components/schemas/Formality' + model_type: + $ref: '#/components/schemas/ModelType' glossary_id: allOf: - $ref: '#/components/schemas/GlossaryId' @@ -222,6 +222,8 @@ paths: $ref: '#/components/schemas/PreserveFormattingOptionStr' formality: $ref: '#/components/schemas/Formality' + model_type: + $ref: '#/components/schemas/ModelType' glossary_id: allOf: - $ref: '#/components/schemas/GlossaryId' @@ -270,6 +272,11 @@ paths: description: Number of characters counted by DeepL for billing purposes. Only present if the show_billed_characters parameter is set to true. type: integer + 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 examples: Basic: value: @@ -1386,6 +1393,25 @@ components: - prefer_more - prefer_less default: default + ModelType: + type: string + description: |- + Specifies which DeepL model should be used for translation. + + Possible values are: + * `latency_optimized` (default) - uses lower latency “classic” translation models, which support all language pairs; + default value + * `quality_optimized` - uses higher latency, improved quality “next-gen” translation models, which support only a + subset of language pairs; if a language pair that is not supported by next-gen models is included in the + request, it will fail. Consider using prefer_quality_optimized instead. + * `prefer_quality_optimized` - prioritizes use of higher latency, improved quality “next-gen” translation models, + which support only a subset of DeepL languages; if a request includes a language pair not supported by + next-gen models, the request will fall back to latency_optimized classic models. + + enum: + - quality_optimized + - prefer_quality_optimized + - latency_optimized GlossaryId: type: string description: A unique ID assigned to a glossary. diff --git a/openapi_gitbook.yaml b/openapi_gitbook.yaml index 2fb2857..a54f507 100644 --- a/openapi_gitbook.yaml +++ b/openapi_gitbook.yaml @@ -9,7 +9,7 @@ info: contact: name: DeepL - Contact us url: https://www.deepl.com/contact-us - version: 2.16.0 + version: 2.17.0 externalDocs: description: DeepL Pro - Plans and pricing url: https://www.deepl.com/pro#developer?cta=header-prices/ @@ -83,9 +83,9 @@ paths: text: description: |- Text to be translated. Only UTF-8-encoded plain text is supported. The parameter may be specified - up to 50 times in a single request. Translations are returned in the same order as they are requested. + many times in a single request, within the request size limit (128KiB). Translations are returned + in the same order as they are requested. type: array - maxItems: 50 items: type: string example: Hello, World! @@ -103,6 +103,8 @@ paths: $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` @@ -140,8 +142,9 @@ paths: - target_lang properties: text: - description: Text to be translated. Only UTF-8-encoded plain text is supported. The parameter may be specified - up to 50 times in a single request. Translations are returned in the same order as they are requested. + 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. type: array items: type: string @@ -160,6 +163,8 @@ paths: $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` @@ -223,6 +228,12 @@ paths: 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: @@ -1244,6 +1255,13 @@ components: - prefer_less default: default example: prefer_more + ModelType: + type: string + description: Specifies which DeepL model should be used for translation. + enum: + - quality_optimized + - prefer_quality_optimized + - latency_optimized GlossaryId: type: string description: A unique ID assigned to a glossary.