Add custom_instructions parameter to text translation (#188)

Author: BriannaDelgado

api-reference/openapi.yaml

@@ -406,6 +406,17 @@ paths:
                     **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
+                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.
+
+                    **Important:**  The target language must be `de`, `en`, `es`, `fr`, `it`, `ja`, `ko`, `zh` or any variants of these languages.
+                    
+                    **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:

api-reference/translate.mdx

@@ -282,11 +282,20 @@ Note that we do not include examples for our client libraries in every single se
 </ParamField>
 <ParamField body="style_id" type="string">
   Specify the style rule list to use for the translation which can be used to customize translations according to the selected formatting and style conventions.
-  <Note>
+  <Info>
     The target language has to match the language of the style rule list. 
 
-    Additionally, 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.
-  </Note>
+    Additionally, any request with the `style_id` parameter enabled will default to use the `quality_optimized` model type. Requests combining `style_id` and `model_type: latency_optimized` will be rejected.
+  </Info>
+</ParamField>
+<ParamField body="custom_instructions" type="array[string]">
+  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.
+
+  <Info>  
+    The target language must be `de`, `en`, `es`, `fr`, `it`, `ja`, `ko`, `zh` or any variants of these languages.
+
+    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.
+  </Info>
 </ParamField>
 <ParamField body="show_billed_characters" type="boolean">
   When <code>true</code>, the response will include an additional key-value pair with the key <code>billed_characters</code> and a value that is an integer showing the number of characters from the request that will be counted by DeepL for billing purposes.

docs/resources/roadmap-and-release-notes.mdx

@@ -6,7 +6,6 @@ rss: true
 
 <Update label="In active development">
 - Add more events to audit logs for Pro API customers (API key management, cost control and usage limit changes)
-- Add a new parameter to the text translation API to allow custom instructions, making it possible to customize the translation behavior (e.g. ["Use a friendly, diplomatic tone"])
 </Update>
 
 <Update label="Q4 2025">
@@ -19,6 +18,7 @@ rss: true
 - Added support for 75 new languages, initially through the `enable_beta_languages` parameter, for text and document translation. Beta languages are not billed during the beta phase and do not yet support glossaries or formality. See [here](../getting-started/supported-languages#beta-languages) for more information
 - Added HE, TH and VI to the languages endpoint, since they are now also available in document translation
 - Added 6 additional beta languages, for text and document translation. See the previous note about 75 new languages.
+- Added a new parameter to the text translation API to allow custom instructions, making it possible to customize the translation behavior (e.g. ["Use a friendly, diplomatic tone"])
 </Update>
 
 <Update label="Q3 2025">