From 23d6fab31a22a961446f6b3bd186789cf7f0a25a Mon Sep 17 00:00:00 2001 From: Maxim Brunnmeier Date: Mon, 19 Oct 2026 11:00:24 +0200 Subject: [PATCH 1/3] docs: document custom_instructions on POST /v2/document MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add the custom_instructions field to the document upload request body, sent as a JSON array of strings in a single form field - Add a request example and document the 400 cases - Link the document translation reference from the custom instructions guide 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- api-reference/openapi.json | 13 +++++++++++++ api-reference/openapi.yaml | 15 +++++++++++++++ docs/customize/custom-instructions.mdx | 1 + 3 files changed, 29 insertions(+) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 6ebd432b..105ae31d 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -1154,6 +1154,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": { @@ -1223,6 +1231,11 @@ "translation_memory_threshold": { "$ref": "#/components/schemas/TranslationMemoryThreshold" }, + "custom_instructions": { + "description": "Specify a list of [custom instructions](/docs/customize/custom-instructions) to customize the translation behavior, as a JSON array of strings in a single form field, for example `[\"Use a friendly, diplomatic tone\", \"Keep sentences short\"]`. See [Technical constraints](/docs/customize/custom-instructions#technical-constraints) for the number and length of instructions and the supported target languages.\n\nCan be combined with `style_id`. The style rule list's stored custom instructions are applied as well.\n\nRejected with `400` before the upload is accepted if the value is not a JSON array of strings, or if it has too many or too long instructions.", + "type": "string", + "example": "[\"Use a friendly, diplomatic tone\"]" + }, "enable_watermark": { "description": "When `true`, adds a \"Translated by DeepL\" watermark to the translated document.\n\nOnly supported for `docx` and `pdf` output. For all other output formats the parameter is ignored and the document is returned without a watermark.", "type": "boolean", diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 508c603b..8f30cf0b 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -927,6 +927,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: @@ -1028,6 +1034,15 @@ paths: $ref: '#/components/schemas/TranslationMemoryId' translation_memory_threshold: $ref: '#/components/schemas/TranslationMemoryThreshold' + custom_instructions: + description: |- + Specify a list of [custom instructions](/docs/customize/custom-instructions) to customize the translation behavior, as a JSON array of strings in a single form field, for example `["Use a friendly, diplomatic tone", "Keep sentences short"]`. See [Technical constraints](/docs/customize/custom-instructions#technical-constraints) for the number and length of instructions and the supported target languages. + + Can be combined with `style_id`. The style rule list's stored custom instructions are applied as well. + + Rejected with `400` before the upload is accepted if the value is not a JSON array of strings, or if it has too many or too long instructions. + type: string + example: '["Use a friendly, diplomatic tone"]' enable_watermark: description: |- When `true`, adds a "Translated by DeepL" watermark to the translated document. 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) From c3d326e928817b793332bcd5c0b426d3b81bbff9 Mon Sep 17 00:00:00 2001 From: Maxim Brunnmeier Date: Mon, 19 Oct 2026 11:37:16 +0200 Subject: [PATCH 2/3] docs: align the document custom_instructions description with text translation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- api-reference/openapi.json | 2 +- api-reference/openapi.yaml | 6 ++---- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 105ae31d..4e7cc9be 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -1232,7 +1232,7 @@ "$ref": "#/components/schemas/TranslationMemoryThreshold" }, "custom_instructions": { - "description": "Specify a list of [custom instructions](/docs/customize/custom-instructions) to customize the translation behavior, as a JSON array of strings in a single form field, for example `[\"Use a friendly, diplomatic tone\", \"Keep sentences short\"]`. See [Technical constraints](/docs/customize/custom-instructions#technical-constraints) for the number and length of instructions and the supported target languages.\n\nCan be combined with `style_id`. The style rule list's stored custom instructions are applied as well.\n\nRejected with `400` before the upload is accepted if the value is not a JSON array of strings, or if it has too many or too long 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\"]" }, diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 8f30cf0b..000033ee 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -1036,11 +1036,9 @@ paths: $ref: '#/components/schemas/TranslationMemoryThreshold' custom_instructions: description: |- - Specify a list of [custom instructions](/docs/customize/custom-instructions) to customize the translation behavior, as a JSON array of strings in a single form field, for example `["Use a friendly, diplomatic tone", "Keep sentences short"]`. See [Technical constraints](/docs/customize/custom-instructions#technical-constraints) for the number and length of instructions and the supported target languages. + 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. - Can be combined with `style_id`. The style rule list's stored custom instructions are applied as well. - - Rejected with `400` before the upload is accepted if the value is not a JSON array of strings, or if it has too many or too long instructions. + 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"]' enable_watermark: From af25fe5609e1437462a09db79f3517570ca5a499 Mon Sep 17 00:00:00 2001 From: Maxim Brunnmeier Date: Mon, 2 Nov 2026 10:01:45 +0100 Subject: [PATCH 3/3] docs: changelog entry and style_profile_id conflict for document custom_instructions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- api-reference/openapi.json | 2 +- api-reference/openapi.yaml | 5 +++-- docs/resources/roadmap-and-release-notes.mdx | 7 +++++++ 3 files changed, 11 insertions(+), 3 deletions(-) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 400b7fa3..2d3a9182 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -1256,7 +1256,7 @@ "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 7c8e7660..6419488b 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -1117,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/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.