Merge pull request #25 from DeepLcom/add-model-type

/translate: Add model_type and model_type_used parameters

Author: daniel-jones-dev

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

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.",

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.

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.