Document Translation API

node --env-file=.env translate-text.mjs input.txt Spanish translated.txt
node --env-file=.env translate-text.mjs input.txt Spanish translated.txt --start

POST /api/v1/quotes
Authorization: Bearer doctr_...
Content-Type: application/json

{
  "version": "document-ir/8",
  "format": "txt",
  "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
  "sourceLanguage": "auto",
  "targetLanguage": "Spanish",
  "segments": [
    {
      "id": "s0",
      "text": "Hello, world."
    }
  ]
}

POST /api/v1/quotes?output=best-effort-v1

POST /api/v1/translations
Authorization: Bearer doctr_...
Content-Type: application/json

{
  "quoteId": "<quote id>",
  "idempotencyKey": "my-document-0001",
  "payload": {
    "version": "document-ir/8",
    "format": "txt",
    "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
    "sourceLanguage": "auto",
    "targetLanguage": "Spanish",
    "segments": [
      {
        "id": "s0",
        "text": "Hello, world."
      }
    ]
  }
}

GET /api/v1/translations/JOB_ID/result
Authorization: Bearer doctr_...

{
  "version": "document-ir/8",
  "jobId": "<job id>",
  "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
  "targetLanguage": "Spanish",
  "segments": [
    {
      "id": "s0",
      "text": "Hola, mundo."
    }
  ],
  "mock": false
}

One quote with cURL

Save the quote JSON above as payload.json and set DOCUMENT_TRANSLATOR_API_KEY in your shell. This command requests a quote only. To start, send the start JSON with the returned quote ID and the identical payload to the translations endpoint.

curl https://document-translator.com/api/v1/quotes \
  -H "Authorization: Bearer $DOCUMENT_TRANSLATOR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @payload.json

In PowerShell, use curl.exe and $env:DOCUMENT_TRANSLATOR_API_KEY; write the command on one line instead of using the backslash continuation shown above.

Translation credits and API keys

Each API document reserves one account credit within the limits. Strict jobs charge only when validated and ready; failed or cancelled unfinished jobs release the reservation. With best-effort output, small gaps may use the agreed credit, while major gaps or critical errors release it. Read outcome.creditOutcome and outcome.completion rather than assuming every ready result was charged.

Create up to five active API keys per account. Keys are shown only once, stored as hashes, and can be revoked in Account. An active key can access that account’s paid translations, including jobs created with another key on the same account. Keys do not authorize sign-in or payments.

Retries and interrupted requests

GET /api/v1/translations?requestKey=IDEMPOTENCY_KEY&quoteId=QUOTE_ID
DELETE /api/v1/translations?requestKey=IDEMPOTENCY_KEY&quoteId=QUOTE_ID

Reuse the same quote ID, payload, and idempotency key after an uncertain start request. Identical retries return the existing job without another charge. A changed payload or a key reused for another quote returns 409. Job and idempotency metadata are retained for seven days after termination.

A resumable failed job can be retried while its source text remains available. The retry keeps its job ID and reuses completed chunks. Jobs permit at most three processing attempts. Download failures can retry the result endpoint without starting another translation.

Polling and downloads

GET /api/v1/translations/JOB_ID
GET /api/v1/translations?ids=JOB_ID_1,JOB_ID_2
GET /api/v1/translations/JOB_ID/result
PUT /api/v1/translations/JOB_ID/files/txt
GET /api/v1/translations/JOB_ID/files/txt
POST /api/v1/translations/JOB_ID/retry
DELETE /api/v1/translations/JOB_ID

Batch status accepts at most 100 IDs and returns { jobs: [...] } containing only authorized, undeleted jobs. Poll about every five seconds while processing and every fifteen seconds while queued. Rotate batches fairly when recovering more than 100 jobs. Pause polling in hidden tabs and stop on terminal states or permanent authorization errors.

When the state is ready, fetch the result with the same account authorization. It contains the translated segment mapping for local reconstruction. Results are accessible for 24 hours after completion; unsuccessful input expires one hour after creation. Expired results return 410. Deleted or inaccessible jobs return 404.

queued → processing → ready
                   ↘ failed / cancelled / expired

{"jobs":[{"id":"<job id>","state":"processing","completedChunks":1,"totalChunks":2}]}

Save a finished file with PUT using its binary body, Content-Length, and matching Content-Type. Supported extensions are docx, pptx, xlsx, pdf, txt, and md, with one saved file per format and a 50 MB output limit. Repeating a successful save keeps the existing file. GET downloads the saved file; savedFormats in job status lists available formats. Saving and downloading use the same job ownership checks, cost no extra credits, and never extend the 24-hour deadline.

PUT /api/v1/translations/{id}/files/docx
X-Download-Kind: reading-copy
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Length: {bytes}

{binary DOCX body}

GET /api/v1/translations/{id}

{"savedFormats":["docx"],"savedDownloads":[{"format":"docx","kind":"reading-copy"}]}

DELETE cancels unfinished work or removes available text and saved files. Deleting a completed result does not refund it or extend its download window. There are no completion webhooks in this release.

PUT /api/v1/translations/{id}/manifest
Content-Type: application/json
Content-Length: {bytes, maximum 2 MiB}

{"version":1,"parserVersion":"document-ir/8","fingerprint":"{original SHA-256}","ocr":[]}

PUT /api/v1/translations/{id}/source
Content-Type: application/octet-stream
Content-Length: {bytes, maximum 25 MiB}
X-Parser-Version: document-ir/8
X-Source-SHA256: {original SHA-256}

{unchanged original bytes}

GET /api/v1/translations/{id}
// sourceBackup is available only after both saves
GET /api/v1/translations/{id}/manifest
GET /api/v1/translations/{id}/source

Account balance and history

GET /api/v1/translations?before=NEXT_CURSOR&limit=5
GET /api/v1/translations?active=1&before=NEXT_CURSOR
GET /api/account/balance

History is limited to the current owner and uses the returned pagination cursor. The balance endpoint uses the browser account session and returns minimal sign-in and balance information. During pending Checkout, poll it every five seconds for at most ten attempts, pause while hidden, and stop when credit arrives or the account signs out.

n8n, Make and Zapier

Use an HTTP request step with a secret Bearer credential. Extract the text first, POST the JSON payload to the quote endpoint, then POST the quote ID, payload and a stable 16–80 character idempotency key to the translations endpoint. Add a delay and GET status until ready, fetch the result, and rebuild or save the translated text. Persist the quote ID and retry key with your workflow record. No dedicated connector or multipart upload is required.

Limits and errors

• Up to 50,000 source words, 400,000 extracted characters, and 12,000 text segments per document. The browser also limits original files to 25 MB, PDFs to 300 pages, and PowerPoint files to 300 slides. These are source limits, checked before translation starts.
• Up to 100 queued or processing documents per account. API keys share 120 quotes per minute and five new starts or retries per ten seconds per account. Honor Retry-After on 429 responses and use bounded backoff for temporary failures; increasing polling frequency does not speed up processing.
• Strict output rejects missing, duplicate or malformed translated segments before charging. Best-effort output retains validated translations and may keep original text in unresolved sections, with outcome and issues describing the result. No watermark or service attribution is added to document content.

Errors include an error message and code. 400 indicates invalid input, 401 invalid authorization, 402 insufficient credits, 404 an unavailable job, 409 a conflicting quote or state, 410 expiry, 429 a rate or capacity limit, and 503 an unavailable service.

We keep a private copy of your original document until 24 hours after translation finishes, so you can recover your downloads. You can remove it sooner by deleting the translation. Only extracted text is sent to our translation provider. Privacy details