DeepL Translate Documents API

openapi: 3.2.0
info:
  title: DeepL API Documentation Translate Documents API
  description: 'The DeepL API provides programmatic access to DeepL’s language AI technology.


    Note: this OpenAPI spec is embedded into our API documentation and has shortened descriptions.'
  termsOfService: https://www.deepl.com/pro-license
  contact:
    name: DeepL - Contact us
    url: https://www.deepl.com/contact-us
  version: 3.13.0
servers:
- url: https://api.deepl.com
  description: DeepL API Pro
- url: https://api-free.deepl.com
  description: DeepL API Free
tags:
- name: TranslateDocuments
  description: 'The document translation API allows you to translate whole documents and supports the following file types and extensions:

    * `docx` - Microsoft Word Document

    * `pptx` - Microsoft PowerPoint Document

    * `xlsx` - Microsoft Excel Document

    * `xlsm` - Microsoft Excel Macro-Enabled Workbook (currently in beta)

    * `pdf` - Portable Document Format

    * `htm / html` - HTML Document

    * `txt` - Plain Text Document

    * `xlf / xliff` - XLIFF Document (versions 1.2, 2.0, and 2.1)

    * `srt` - SRT Document

    * `vtt` - WebVTT Subtitle Document (currently in beta)

    * `idml` - Adobe InDesign Markup Language

    * `xml` - XML Document

    * `json` - JSON Document

    * `yaml / yml` - YAML Document (currently in beta)

    * `properties` - Java Properties Document (currently in beta)

    * `strings` - iOS/macOS Strings Document (currently in beta)

    * `md / markdown` - Markdown Document (currently in beta)

    * `dita` - DITA topic (Darwin Information Typing Architecture)

    * `mif` - Adobe FrameMaker Interchange Format

    * `zip` - SCORM Package (e-learning content, currently in beta)

    * `odt` - OpenDocument Text Document (currently in beta)

    * `rtf` - Rich Text Format Document (currently in beta)

    * `resx` - .NET Resource Document (currently in beta)

    * `jpeg` / `jpg` / `png` - Image (currently in beta)'
paths:
  /v2/document:
    post:
      tags:
      - TranslateDocuments
      summary: Upload and Translate a Document
      operationId: translateDocument
      description: 'Upload a document for translation and receive a `document_id` and `document_key`. Use

        them to poll the document status and download the translated file. Translation is

        asynchronous: the upload response confirms the request, not a finished translation.'
      requestBody:
        required: true
        content:
          multipart/form-data:
            examples:
              Basic:
                summary: Basic Document Translation
                value:
                  target_lang: DE
                  file: '@document.docx'
              Watermark:
                summary: Adding a "Translated by DeepL" watermark (docx/pdf only)
                value:
                  target_lang: DE
                  file: '@document.pdf'
                  enable_watermark: true
              SuppressImages:
                summary: Suppressing translation of embedded images (pptx only)
                value:
                  target_lang: DE
                  file: '@document.pptx'
                  input_conversion_options: version:1,suppress-image-types:all
              Glossary:
                summary: Using a Glossary
                value:
                  source_lang: EN
                  target_lang: DE
                  file: '@document.docx'
                  glossary_id: '[yourGlossaryId]'
              MultipleGlossaries:
                summary: Using Multiple Glossaries
                value:
                  source_lang: EN
                  target_lang: DE
                  file: '@document.docx'
                  glossary_ids: '[yourGlossaryId1],[yourGlossaryId2]'
              StyleRule:
                summary: Using a Style Rule List
                value:
                  source_lang: EN
                  target_lang: DE
                  file: '@document.docx'
                  style_id: '[yourStyleId]'
              TranslationMemory:
                summary: Using a Translation Memory
                value:
                  source_lang: EN
                  target_lang: DE
                  file: '@document.docx'
                  translation_memory_id: '[yourTranslationMemoryId]'
                  translation_memory_threshold: 75
              QualityEvaluation:
                summary: Requesting a quality evaluation report (beta)
                value:
                  source_lang: EN
                  target_lang: DE
                  file: '@document.docx'
                  enable_quality_evaluation: true
            schema:
              type: object
              required:
              - target_lang
              - file
              properties:
                source_lang:
                  $ref: '#/components/schemas/SourceLanguage'
                target_lang:
                  $ref: '#/components/schemas/TargetLanguage'
                file:
                  type: string
                  format: binary
                  description: "The document file to be translated. The file name should be included in this part's content disposition. As an alternative, the filename parameter can be used. The following file types and extensions are supported:\n  * `docx` - Microsoft Word Document\n  * `pptx` - Microsoft PowerPoint Document\n  * `xlsx` - Microsoft Excel Document\n  * `xlsm` - Microsoft Excel Macro-Enabled Workbook (currently in beta)\n  * `pdf` - Portable Document Format\n  * `htm / html` - HTML Document\n  * `txt` - Plain Text Document\n  * `xlf / xliff` - XLIFF Document (versions 1.2, 2.0, and 2.1)\n  * `srt` - SRT Document\n  * `vtt` - WebVTT Subtitle Document (currently in beta)\n  * `idml` - Adobe InDesign Markup Language\n  * `xml` - XML Document\n  * `json` - JSON Document\n  * `yaml / yml` - YAML Document (currently in beta)\n  * `properties` - Java Properties Document (currently in beta)\n  * `strings` - iOS/macOS Strings Document (currently in beta)\n  * `md / markdown` - Markdown Document (currently in beta)\n  * `dita` - DITA topic (Darwin Information Typing Architecture)\n  * `mif` - Adobe FrameMaker Interchange Format\n  * `zip` - SCORM Package (e-learning content, currently in beta)\n  * `odt` - OpenDocument Text Document (currently in beta)\n  * `rtf` - Rich Text Format Document (currently in beta)\n  * `resx` - .NET Resource Document (currently in beta)\n  * `jpeg` / `jpg` / `png` - Image (currently in beta)"
                filename:
                  type: string
                  description: The name of the uploaded file. Can be used as an alternative to including the file name in the file part's content disposition.
                output_format:
                  type: string
                  description: 'File extension of desired format of translated file, for example: `docx`. If unspecified, by default the translated file will be in the same format as the input file.

                    '
                input_conversion_options:
                  description: "Comma-separated list of `key:value` conversion options, prefixed with a version, that control how the input document is converted before translation. For example: `version:1,suppress-image-types:all`.\n\nSupported keys:\n\n  * `suppress-image-types` - Leaves the specified types of images embedded in the document untranslated. The value is a hyphen-separated list of image content types (for example `logo-photo` suppresses logos and photos), or `all` to suppress every embedded image. Recognized image content types: `logo`, `icon`, `decorative`, `barcode`, `formula`, `signature`, `handwriting`, `stamp`, `screenshot`, `diagram`, `chart`, `photo`, `illustration`, `comic`, `music`, `infographic`, `table`, `text`, `other`, `unknown`. Only `pptx` documents support this key.\n  * `json-placeholders` - Controls how brace-delimited placeholders in `json` string values are handled. `protect` (the default) keeps identifier-shaped placeholders such as `{stars}` or `{{userName}}` verbatim so they are not translated; `translate` translates them along with the surrounding text. ICU MessageFormat skeletons such as `{count, plural, one {# item} other {# items}}` are always protected, with only the branch text translated, in both modes. Multi-word groups such as `{see note}` are treated as translatable text in both modes.\n\nFor other file types this parameter is ignored. Unrecognized keys are ignored."
                  type: string
                  example: version:1,suppress-image-types:all
                formality:
                  $ref: '#/components/schemas/Formality'
                glossary_id:
                  description: 'A unique ID assigned to a glossary. To check glossary support for a language pair, call `GET /v3/languages?resource=translate_document` and verify the `glossary` feature key is present on both the source and target language.


                    Cannot be used together with `glossary_ids`.'
                  type: string
                  example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7
                glossary_ids:
                  description: 'Comma-separated list of up to 5 glossary IDs to use for the translation. Each glossary''s matching terms are applied to the translated document. May also be sent as a repeated parameter.


                    **Important:** This requires the `source_lang` parameter to be set. Every listed glossary must contain a dictionary for the requested language pair.


                    Cannot be used together with `glossary_id`.'
                  type: array
                  maxItems: 5
                  items:
                    type: string
                    example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7
                style_id:
                  description: 'Specify the [style rule list](/docs/customize/using-style-rules) to use for the translation.


                    **Important:** The target language has to match the language of the style rule list. A list

                    created for a root language (for example `en`) applies to that language and all of its variants

                    (`EN-GB`, `EN-US`). A list created for a variant (for example `en-GB`) applies only when

                    `target_lang` is that variant.'
                  type: string
                  example: 7ff9bfd6-cd85-4190-8503-d6215a321519
                translation_memory_id:
                  $ref: '#/components/schemas/TranslationMemoryId'
                translation_memory_threshold:
                  $ref: '#/components/schemas/TranslationMemoryThreshold'
                enable_watermark:
                  description: 'When `true`, adds a "Translated by DeepL" watermark to the translated document.


                    Only 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
                  default: false
                enable_quality_evaluation:
                  description: '(beta) When `true`, DeepL also evaluates the finished translation and returns a `quality_evaluation_job_id`. Poll [`GET /v1/quality-evaluations/{job_id}`](/api-reference/quality-evaluations/poll) with it for a per-segment report of translation issues. The translation itself is unaffected.


                    **Important:** Available to select customers; contact your customer success manager to enable it. Supported for `docx`, `pptx`, `pdf`, `srt`, `idml`, `xml`, `dita`, `mif`, and XLIFF 2.1 uploads, and for the [supported language pairs](/api-reference/quality-evaluations/poll#supported-language-pairs) only.


                    Rejected before the upload is accepted: `403` if quality evaluation is not enabled for the account, `400` for an ineligible file type, an unsupported language pair, or a value other than `true` or `false`.'
                  type: boolean
                  default: false
                enable_beta_languages:
                  description: This parameter is maintained for backward compatibility and has no effect.
                  type: boolean
                  default: false
                  deprecated: true
      responses:
        '200':
          description: The document function returns a JSON object containing the ID and encryption key assigned to the uploaded document. Once received by the server, uploaded documents are immediately encrypted using a uniquely generated encryption key. This key is not persistently stored on the server. Therefore, it must be stored by the client and sent back to the server with every subsequent request that refers to this particular document.
          headers:
            X-Trace-ID:
              $ref: '#/components/headers/X-Trace-ID'
          content:
            application/json:
              schema:
                type: object
                properties:
                  document_id:
                    description: A unique ID assigned to the uploaded document and the translation process. Must be used when referring to this particular document in subsequent API requests.
                    type: string
                    example: 04DE5AD98A02647D83285A36021911C6
                  document_key:
                    description: A unique key that is used to encrypt the uploaded document as well as the resulting translation on the server side. Must be provided with every subsequent API request regarding this particular document.
                    type: string
                    example: 0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A
                  quality_evaluation_job_id:
                    description: (beta) A unique ID assigned to the quality evaluation. Returned only when the request set `enable_quality_evaluation=true`. Use it to retrieve the report from [`GET /v1/quality-evaluations/{job_id}`](/api-reference/quality-evaluations/poll).
                    type: string
                    example: 04DE5AD98A02647D83285A36021911C6
              example:
                document_id: 04DE5AD98A02647D83285A36021911C6
                document_key: 0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenScoped'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '456':
          $ref: '#/components/responses/QuotaExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '504':
          $ref: '#/components/responses/ServiceUnavailable'
        '529':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
  /v2/document/{document_id}:
    post:
      tags:
      - TranslateDocuments
      summary: Check Document Status
      operationId: getDocumentStatus
      description: 'Retrieve the translation status of an uploaded document. Poll this endpoint until the

        status is `done`, then download the result. The response includes an estimated

        remaining time while the document is still translating.'
      parameters:
      - $ref: '#/components/parameters/DocumentID'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/DocumentKey'
            examples:
              basic:
                summary: Basic
                value:
                  document_key: 0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentKey'
      responses:
        '200':
          description: The document status request returns a JSON object containing the document ID that was used in the request as well as string indicating the current status of the translation process. While the translation is running, the estimated number of seconds remaining until the process is done is also included in the response.
          headers:
            X-Trace-ID:
              $ref: '#/components/headers/X-Trace-ID'
          content:
            application/json:
              schema:
                type: object
                required:
                - document_id
                - status
                properties:
                  document_id:
                    description: A unique ID assigned to the uploaded document and the requested translation process. The same ID that was used when requesting the translation status.
                    type: string
                    example: 04DE5AD98A02647D83285A36021911C6
                  status:
                    description: "A short description of the state the document translation process is currently in. Possible values are:\n * `queued` - the translation job is waiting in line to be processed\n * `translating` - the translation is currently ongoing\n * `done` - the translation is done and the translated document is ready for download\n * `error` - an irrecoverable error occurred while translating the document"
                    type: string
                    example: done
                    enum:
                    - queued
                    - translating
                    - done
                    - error
                  seconds_remaining:
                    description: 'Estimated number of seconds until the translation is done.

                      This parameter is only included while `status` is `"translating"`.'
                    type: integer
                  billed_characters:
                    description: The number of characters billed to your account. The characters will only be billed after a successful download request.
                    type: integer
                    example: 1337
                  error_message:
                    description: 'A short description of the error, if available.

                      Note that the content is subject to change.

                      This parameter may be included if an error occurred during translation.'
                    type: string
                    example: Only available if document status is error
              examples:
                translating:
                  summary: Translating
                  value:
                    document_id: 04DE5AD98A02647D83285A36021911C6
                    status: translating
                    seconds_remaining: 20
                done:
                  summary: Done
                  value:
                    document_id: 04DE5AD98A02647D83285A36021911C6
                    status: done
                    billed_characters: 1337
                queued:
                  summary: Queued
                  value:
                    document_id: 04DE5AD98A02647D83285A36021911C6
                    status: queued
                error:
                  summary: Error
                  value:
                    document_id: 04DE5AD98A02647D83285A36021911C6
                    status: error
                    message: Source and target language are equal.
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenScoped'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '456':
          $ref: '#/components/responses/QuotaExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '504':
          $ref: '#/components/responses/ServiceUnavailable'
        '529':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
  /v2/document/{document_id}/result:
    post:
      tags:
      - TranslateDocuments
      summary: Download Translated Document
      operationId: downloadDocument
      description: 'Download a translated document. The document must have a status of `done`. Each

        document can be downloaded only once: after a successful download DeepL deletes the

        file and invalidates the `document_id`.'
      parameters:
      - $ref: '#/components/parameters/DocumentID'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/DocumentKey'
            examples:
              basic:
                summary: Basic
                value:
                  document_key: 0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentKey'
      responses:
        '200':
          description: The document is provided as a download. There is no other data included in the response besides the document data. The content type used in the response corresponds to the document type.
          headers:
            X-Trace-ID:
              $ref: '#/components/headers/X-Trace-ID'
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
              examples:
                OK:
                  summary: OK
                  description: binary document data
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenScoped'
        '404':
          $ref: '#/components/responses/NotFound404DocTransDownload'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '456':
          $ref: '#/components/responses/QuotaExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable503DocTransDownload'
        '504':
          $ref: '#/components/responses/ServiceUnavailable'
        '529':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
components:
  responses:
    ForbiddenScoped:
      description: Authorization failed. Please supply a valid `DeepL-Auth-Key` via the `Authorization` header. This error is also returned when the API key is scoped but does not include the scope required for this endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound404DocTransDownload:
      description: Trying to download a document using a non-existing document ID or the wrong document key will result in a 404 error. As stated above, documents can only be downloaded once before they are deleted from the server and their document ID is invalidated.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DocumentTranslationError'
          examples:
            NotFound:
              summary: Not Found
              value:
                message: Document not found
    ServiceUnavailable503DocTransDownload:
      description: 'A 503 result will be returned if the user tries to download a translated document that is currently being processed and is not yet ready for download.

        Please make sure to check that the document status is ''done'' before trying to send a download request.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DocumentTranslationError'
          examples:
            AlreadyDownloaded:
              summary: Already Downloaded
              value:
                message: Document already downloaded
    ServiceUnavailable:
      description: Resource currently unavailable. Try again later.
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/ErrorResponse'
            - $ref: '#/components/schemas/InfrastructureErrorResponse'
    TooManyRequests:
      description: Too many requests. Please wait and resend your request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal error.
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/ErrorResponse'
            - $ref: '#/components/schemas/InfrastructureErrorResponse'
    NotFound:
      description: The requested resource could not be found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request. Please check error message and your parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PayloadTooLarge:
      description: The request size exceeds the limit.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    QuotaExceeded:
      description: Quota exceeded. The character limit has been reached.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    Formality:
      description: "Sets whether the translated text should lean towards formal or informal language.\nThis feature is only available for certain target languages. Setting this parameter\nwith a target language that does not support formality will fail, unless one of the\n`prefer_...` options are used.\nPossible options are:\n  * `default` (default)\n  * `more` - for a more formal language\n  * `less` - for a more informal language\n  * `prefer_more` - for a more formal language if available, otherwise fallback to default formality\n  * `prefer_less` - for a more informal language if available, otherwise fallback to default formality"
      type: string
      enum:
      - default
      - more
      - less
      - prefer_more
      - prefer_less
      default: default
      example: prefer_more
    InfrastructureErrorResponse:
      description: 'Error body returned by DeepL''s edge infrastructure for failures that occur before a request reaches the API itself. The message is nested under `error`, unlike the application-level `ErrorResponse`. Clients that parse error bodies should handle both shapes.

        '
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          properties:
            message:
              type: string
              description: A human-readable description of the error.
              example: Bad Gateway.
    SourceLanguage:
      type: string
      description: 'Language of the text to be translated. If this parameter is omitted, the API will attempt to

        detect the language of the text and translate it.


        For the full list of supported source languages, see [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) or query the [`GET /v3/languages` endpoint](https://developers.deepl.com/docs/languages/using-the-languages-api).'
      example: EN
    ErrorResponse:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: A human-readable description of the error.
        code:
          type: string
          description: A machine-readable identifier for the error, when available. Clients should match on this value rather than on `message` when branching on error types.
          example: invalid_content_type
    TranslationMemoryId:
      type: string
      format: uuid
      description: A unique ID assigned to a translation memory.
      example: a74d88fb-ed2a-4943-a664-a4512398b994
    TargetLanguage:
      type: string
      description: 'The language into which the text should be translated.


        For the full list of supported target languages, see [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) or query the [`GET /v3/languages` endpoint](https://developers.deepl.com/docs/languages/using-the-languages-api).'
      example: DE
    TranslationMemoryThreshold:
      type: integer
      description: The minimum matching percentage required for a translation memory segment to be applied (recommended to be 75% or higher). A value below 50 is treated as 50.
      minimum: 0
      maximum: 100
      default: 75
      example: 75
    DocumentTranslationError:
      type: object
      properties:
        message:
          type: string
          description: detailed error message
    DocumentKey:
      type: object
      required:
      - document_key
      properties:
        document_key:
          description: The document encryption key that was sent to the client when the document was uploaded to the API.
          type: string
          example: 0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A
  headers:
    X-Trace-ID:
      description: A unique identifier for the request that can be included in bug reports to DeepL support.
      schema:
        type: string
      example: 501c3d93cc0c4f11ae2f60a226c2f0f0
  parameters:
    DocumentID:
      name: document_id
      description: The document ID that was sent to the client when the document was uploaded to the API.
      in: path
      required: true
      schema:
        type: string
      example: 04DE5AD98A02647D83285A36021911C6
  securitySchemes:
    auth_header:
      type: apiKey
      description: 'Authentication with `Authorization` header and `DeepL-Auth-Key` authentication scheme. Example: `DeepL-Auth-Key <api-key>`

        '
      name: Authorization
      in: header
      x-default: 'DeepL-Auth-Key '
externalDocs:
  description: DeepL Pro - Plans and pricing
  url: https://www.deepl.com/pro#developer
x-hideTryItPanel: true
x-codeSamples: false
x-provenance:
  method: harvested
  publisher: DeepL
  source: https://developers.deepl.com/api-reference/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)