Wirestack
DeepL document translation now takes custom instructions (November 2, 2026)
POST /v2/document accepts custom_instructions: a JSON array of up to 10 instructions, 300 characters each. Not with style_profile_id.
Your keys
0 of 1 ready
Create each key on its own page, paste it below, then copy the finished lines into your project's .env file. What you paste stays in this tab. It is never sent to Wirestack or saved.
- DeepL API keyDEEPL_AUTH_KEYGet key
Sign in, open API Keys & Limits, click Create key and copy it from the popup. The Free API plan works.
3 of 3 free copies left this month.Unlimited with Pro
What changed
On November 2, 2026 DeepL added the custom_instructions parameter to POST /v2/document, so document translation now matches text translation.
- Send it as a single form field that holds a JSON array of strings.
- Up to 10 instructions, each up to 300 characters.
- The upload is rejected with
400if the value is not a JSON array of strings, goes over the limits, or is sent together withstyle_profile_id.
Prerequisites
Steps
- Upload the document to
POST /v2/documentas a multipart form, as you do today. - Add a
custom_instructionsform field. The API reference example sends these fields:target_langset toDE,fileset to@document.docx, andcustom_instructionsset to'["Use a friendly, diplomatic tone", "Keep sentences short"]'. - Do not send
style_profile_idin the same request. If you use a style profile, choose one or the other. - Check the status and download the result the same way you already do.
Test it
Translate a short .docx once with custom_instructions set to '["Keep sentences short"]' and once without, then compare. Send 11 instructions to check that you get a 400.
Not confirmed
- The API reference has no curl example, only a multipart example with the fields above.
- Which API plans include custom instructions for documents, and whether they change billing.
- Whether every target language and file format supports them.