From 23d6fab31a22a961446f6b3bd186789cf7f0a25a Mon Sep 17 00:00:00 2001 From: Maxim Brunnmeier Date: Mon, 19 Oct 2026 11:00:24 +0200 Subject: [PATCH 1/2] 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/2] 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: