Merge pull request #24 from DeepLcom/show-billed-characters

[ACL-949] Add show_billed_characters parameter to OpenAPI spec

Author: mike-winters-deepl

openapi.json

@@ -80,6 +80,9 @@
                   "context": {
                     "$ref": "#/components/schemas/Context"
                   },
+                  "show_billed_characters": {
+                    "$ref": "#/components/schemas/ShowBilledCharacters"
+                  },
                   "split_sentences": {
                     "$ref": "#/components/schemas/SplitSentencesOption"
                   },
@@ -184,6 +187,9 @@
                   "context": {
                     "$ref": "#/components/schemas/Context"
                   },
+                  "show_billed_characters": {
+                    "$ref": "#/components/schemas/ShowBilledCharacters"
+                  },
                   "split_sentences": {
                     "$ref": "#/components/schemas/SplitSentencesOption"
                   },
@@ -252,6 +258,10 @@
                           "text": {
                             "description": "The translated text.",
                             "type": "string"
+                          },
+                          "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"
                           }
                         }
                       }
@@ -264,7 +274,8 @@
                       "translations": [
                         {
                           "detected_source_language": "EN",
-                          "text": "Hallo, Welt!"
+                          "text": "Hallo, Welt!",
+                          "billed_characters": 42
                         }
                       ]
                     }
@@ -1854,6 +1865,10 @@
         ],
         "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. For text translations where \n`tag_handling` is not set to `html`, the default value is `1`, meaning the engine splits on punctuation and on newlines.\n\nFor text translations where `tag_handling=html`, the default value is `nonewlines`, meaning the engine splits on punctuation only, ignoring newlines.  \n\nThe use of `nonewlines` as the default value for text translations where `tag_handling=html` is new behavior that was implemented in November 2022, \nwhen HTML handling was moved out of beta. \n\nPossible values are: \n\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\n\nFor applications that send one sentence per text parameter, we recommend setting `split_sentences` to `0`, in order to prevent the engine from splitting the sentence unintentionally.\n\n\nPlease note that newlines will split sentences when `split_sentences=1`. We recommend cleaning files so they don't contain breaking sentences or setting the parameter `split_sentences` to `nonewlines`.",
         "type": "string",

openapi.yaml

@@ -138,6 +138,8 @@ paths:
                   $ref: '#/components/schemas/TargetLanguageText'
                 context:
                   $ref: '#/components/schemas/Context'
+                show_billed_characters:
+                  $ref: '#/components/schemas/ShowBilledCharacters'
                 split_sentences:
                   $ref: '#/components/schemas/SplitSentencesOption'
                 preserve_formatting:
@@ -212,6 +214,8 @@ paths:
                   $ref: '#/components/schemas/TargetLanguageText'
                 context:
                   $ref: '#/components/schemas/Context'
+                show_billed_characters:
+                  $ref: '#/components/schemas/ShowBilledCharacters'
                 split_sentences:
                   $ref: '#/components/schemas/SplitSentencesOption'
                 preserve_formatting:
@@ -262,12 +266,17 @@ paths:
                         text:
                           description: The translated text.
                           type: string
+                        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
               examples:
                 Basic:
                   value:
                     translations:
                     - detected_source_language: EN
                       text: Hallo, Welt!
+                      billed_characters: 42
                 Glossary:
                   value:
                     translations:
@@ -1547,6 +1556,11 @@ components:
       - '0'
       - '1'
       default: '0'
+    ShowBilledCharacters:
+      description: |-
+        When true, the response will include the billed_characters parameter, giving the 
+        number 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. For text translations where 

openapi_gitbook.yaml

@@ -95,6 +95,8 @@ paths:
                   $ref: '#/components/schemas/TargetLanguageText'
                 context:
                   $ref: '#/components/schemas/Context'
+                show_billed_characters:
+                  $ref: '#/components/schemas/ShowBilledCharacters'
                 split_sentences:
                   $ref: '#/components/schemas/SplitSentencesOption'
                 preserve_formatting:
@@ -150,6 +152,8 @@ paths:
                   $ref: '#/components/schemas/TargetLanguageText'
                 context:
                   $ref: '#/components/schemas/Context'
+                show_billed_characters:
+                  $ref: '#/components/schemas/ShowBilledCharacters'
                 split_sentences:
                   $ref: '#/components/schemas/SplitSentencesOption'
                 preserve_formatting:
@@ -214,6 +218,11 @@ paths:
                           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
         400:
           $ref: '#/components/responses/BadRequest'
         403:
@@ -1156,6 +1165,13 @@ components:
       name: Authorization
       in: header
   schemas:
+    Context:
+      description: |-
+        Additional context that can influence a translation but is not translated itself.
+
+        Characters included in the `context` parameter will not be counted toward billing.
+      type: string
+      example: This is context.
     CreateGlossaryParameters:
       type: object
       required:
@@ -1315,13 +1331,6 @@ components:
         using the `splitting_tags` parameter.
       type: boolean
       default: true
-    Context:
-      description: |-
-        Additional context that can influence a translation but is not translated itself.
-
-        Characters included in the `context` parameter will not be counted toward billing.
-      type: string
-      example: This is context. 
     OutlineDetectionOptionStr:
       description: |-
         Disable the automatic detection of XML structure by setting the `outline_detection` parameter 
@@ -1346,6 +1355,11 @@ components:
       - '0'
       - '1'
       default: '0'
+    ShowBilledCharacters:
+      description: |-
+        When true, the response will include the billed_characters parameter, giving the 
+        number 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.