Document Translation API | Document-Translator.com

Quick start

Sign in and create an API key. Store the key in your server’s secret configuration. API translations require prepaid credits; the free browser allowance does not apply.
Extract the document’s text in your client, give each segment a stable ID, and request a quote. Keep the original document locally for reconstruction.
Start with the quote ID, a stable idempotency key, and the same payload. Poll until ready, retrieve the translated segments, and rebuild your document.

The API accepts extracted text. It does not receive original document binaries or return generated document files.

Create a quote

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

{
  "version": "document-ir/1",
  "format": "txt",
  "fingerprint": "<64-character SHA-256 of the source file>",
  "sourceLanguage": "auto",
  "targetLanguage": "Spanish",
  "segments": [
    {
      "id": "s0",
      "text": "Hello, world."
    }
  ]
}

The response includes the quote ID, source word count, exact credit cost, and expiry. Quotes last ten minutes. Requesting a quote does not reserve credits or save document text.

Start the translation

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

{
  "quoteId": "<quote id>",
  "idempotencyKey": "<stable key, 16–80 letters, digits, underscores or hyphens>",
  "payload": {
    "version": "document-ir/1",
    "format": "txt",
    "fingerprint": "<the same source fingerprint>",
    "sourceLanguage": "auto",
    "targetLanguage": "Spanish",
    "segments": [
      {
        "id": "s0",
        "text": "Hello, world."
      }
    ]
  }
}

Send the original quoted payload again at start. The server verifies its owner and canonical hash before storing text or reserving credits. JSON object-key order does not matter; changing the text, segment order, format, fingerprint, or languages requires a new quote.

Build a document translation workflow

Extract text and rebuild downloads in your application. Send the payload shown above, then use the returned segment IDs to put each translation back into its document.

// Run this on your server. Keep your API key private.
const response = await fetch(
  'https://document-translator.com/api/v1/quotes',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  }
);
if (!response.ok) throw new Error('Quote request failed');
const quote = await response.json();
// Show the price before starting with the same payload.

DOCX preserves supported original structures. PDF export reflows text and does not reproduce exact page layouts. Scanned or password-protected PDFs are not supported. Review important translations and formatting before use.

Translation credits and API keys

The quote returns the source word count and exact credits required for each document. Credits are reserved at start and charged once a complete, validated translation is ready. API keys use prepaid credits; daily and signup allowances are available through the website.

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

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
POST /api/v1/translations/JOB_ID/retry
DELETE /api/v1/translations/JOB_ID

Batch status accepts at most ten 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 ten 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 one hour after completion; unsuccessful input expires one hour after creation. Expired results return 410. Deleted or inaccessible jobs return 404.

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

Account balance and history

GET /api/v1/translations?before=NEXT_CURSOR
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.

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 and PDFs to 100 pages.
Up to 100 queued or processing documents per account. Starts and retries share rate limits. Honor Retry-After on 429 responses and use bounded backoff for temporary failures.
Missing, duplicate, or malformed translated segments fail validation before publication and charging. Failed or cancelled unfinished jobs release their reserved credits.

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.

Original documents and generated downloads stay in your client. Extracted text is processed by our translation provider. Temporary private storage is cleaned on a schedule; provider retention policies also apply. Privacy details