diff --git a/api-reference/openapi.json b/api-reference/openapi.json
index a6a3df79..2d3a9182 100644
--- a/api-reference/openapi.json
+++ b/api-reference/openapi.json
@@ -1173,6 +1173,14 @@
"translation_memory_threshold": 75
}
},
+ "CustomInstructions": {
+ "summary": "Using Custom Instructions",
+ "value": {
+ "target_lang": "DE",
+ "file": "@document.docx",
+ "custom_instructions": "[\"Use a friendly, diplomatic tone\", \"Keep sentences short\"]"
+ }
+ },
"QualityEvaluation": {
"summary": "Requesting a quality evaluation report (beta)",
"value": {
@@ -1242,8 +1250,13 @@
"translation_memory_threshold": {
"$ref": "#/components/schemas/TranslationMemoryThreshold"
},
+ "custom_instructions": {
+ "description": "Specify a list of instructions to customize the translation behavior, as a JSON array of strings, for example `[\"Use a friendly, diplomatic tone\"]`. Up to 10 custom instructions can be specified, each with a maximum of 300 characters.\n\nRejected with `400` before the upload is accepted if the value is not a JSON array of strings or exceeds these limits.",
+ "type": "string",
+ "example": "[\"Use a friendly, diplomatic tone\"]"
+ },
"style_profile_id": {
- "description": "Translate with a [style profile](/api-reference/style-profiles/list-all-style-profiles): its glossaries,\nstyle rule lists and translation memories through one ID. The profile is applied once the\ndocument's source language is known: the glossaries with a dictionary for the language pair, the\nstyle rule list for the target language, and the translation memories whose source language matches\nthe document. A component that does not fit the language pair is left out; this is not an error.\n\nCannot be combined with `glossary_id`, `glossary_ids`, `style_id`, `translation_memory_id` or\n`translation_memory_threshold`. A request that combines them is rejected with `400 Bad Request`.\nA style profile that does not exist or that your account cannot access is not rejected at upload:\nthe document status reports an error with the message `Style profile not found.`.",
+ "description": "Translate with a [style profile](/api-reference/style-profiles/list-all-style-profiles): its glossaries,\nstyle rule lists and translation memories through one ID. The profile is applied once the\ndocument's source language is known: the glossaries with a dictionary for the language pair, the\nstyle rule list for the target language, and the translation memories whose source language matches\nthe document. A component that does not fit the language pair is left out; this is not an error.\n\nCannot be combined with `glossary_id`, `glossary_ids`, `style_id`, `translation_memory_id`,\n`translation_memory_threshold` or `custom_instructions`. A request that combines them is rejected\nwith `400 Bad Request`.\nA style profile that does not exist or that your account cannot access is not rejected at upload:\nthe document status reports an error with the message `Style profile not found.`.",
"type": "string",
"format": "uuid",
"example": "3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47"
diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml
index f440e20a..6419488b 100644
--- a/api-reference/openapi.yaml
+++ b/api-reference/openapi.yaml
@@ -991,6 +991,12 @@ paths:
file: '@document.docx'
translation_memory_id: '[yourTranslationMemoryId]'
translation_memory_threshold: 75
+ CustomInstructions:
+ summary: Using Custom Instructions
+ value:
+ target_lang: DE
+ file: '@document.docx'
+ custom_instructions: '["Use a friendly, diplomatic tone", "Keep sentences short"]'
QualityEvaluation:
summary: Requesting a quality evaluation report (beta)
value:
@@ -1096,6 +1102,13 @@ paths:
$ref: '#/components/schemas/TranslationMemoryId'
translation_memory_threshold:
$ref: '#/components/schemas/TranslationMemoryThreshold'
+ custom_instructions:
+ description: |-
+ Specify a list of instructions to customize the translation behavior, as a JSON array of strings, for example `["Use a friendly, diplomatic tone"]`. Up to 10 custom instructions can be specified, each with a maximum of 300 characters.
+
+ Rejected with `400` before the upload is accepted if the value is not a JSON array of strings or exceeds these limits.
+ type: string
+ example: '["Use a friendly, diplomatic tone"]'
style_profile_id:
description: |-
Translate with a [style profile](/api-reference/style-profiles/list-all-style-profiles): its glossaries,
@@ -1104,8 +1117,9 @@ paths:
style rule list for the target language, and the translation memories whose source language matches
the document. A component that does not fit the language pair is left out; this is not an error.
- Cannot be combined with `glossary_id`, `glossary_ids`, `style_id`, `translation_memory_id` or
- `translation_memory_threshold`. A request that combines them is rejected with `400 Bad Request`.
+ Cannot be combined with `glossary_id`, `glossary_ids`, `style_id`, `translation_memory_id`,
+ `translation_memory_threshold` or `custom_instructions`. A request that combines them is rejected
+ with `400 Bad Request`.
A style profile that does not exist or that your account cannot access is not rejected at upload:
the document status reports an error with the message `Style profile not found.`.
type: string
diff --git a/docs/customize/custom-instructions.mdx b/docs/customize/custom-instructions.mdx
index 081e080f..de3fac36 100644
--- a/docs/customize/custom-instructions.mdx
+++ b/docs/customize/custom-instructions.mdx
@@ -116,6 +116,7 @@ When using custom instructions, keep these constraints in mind:
## Related documentation
- [Text translation API reference](/api-reference/translate/request-translation)
+- [Document translation API reference](/api-reference/document/upload-and-translate-a-document)
- [Working with context](/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter)
- [Style rules API](/docs/customize/using-style-rules)
- [Multilingual glossaries](/docs/customize/managing-glossaries)
diff --git a/docs/resources/roadmap-and-release-notes.mdx b/docs/resources/roadmap-and-release-notes.mdx
index c3a76b7b..65d3ed35 100644
--- a/docs/resources/roadmap-and-release-notes.mdx
+++ b/docs/resources/roadmap-and-release-notes.mdx
@@ -8,6 +8,13 @@ rss: true
- Editing the contents of an existing [translation memory](/docs/customize/using-translation-memories) via API
+
+## November 2 - Custom Instructions for Document Translation
+- [Custom instructions](/docs/customize/custom-instructions) are natural language directives, such as "Use a friendly, diplomatic tone", that guide how DeepL translates. [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document) now accepts them in the `custom_instructions` parameter, as they already work in text translation.
+- Send the instructions as a JSON array of strings in a single form field, for example `["Use a friendly, diplomatic tone"]`. The same limits as text translation apply: up to 10 instructions, each with a maximum of 300 characters.
+- The upload is rejected with `400` if the value is not a JSON array of strings, exceeds these limits, or is combined with `style_profile_id`.
+
+
## October 29 - Higher Character Limit Per Document
- Documents submitted with [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document) on DeepL API paid plans can now contain up to 5 million characters for Word, PowerPoint, and PDF, increased from 1 million. Other formats keep their existing per-document character limit.