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/9",
  "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/9",
    "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/9",
  "jobId": "<job id>",
  "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
  "targetLanguage": "Spanish",
  "segments": [
    {
      "id": "s0",
      "text": "Hola, mundo."
    }
  ],
  "mock": false
}

Eén offerte met cURL

Sla de bovenstaande JSON voor de prijsopgave op als payload.json en stel DOCUMENT_TRANSLATOR_API_KEY in je shell in. Deze opdracht vraagt alleen een prijsopgave aan. Om te starten, stuur je de start-JSON met de geretourneerde quote-ID en de identieke payload naar het vertalingen-eindpunt.

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

Gebruik in PowerShell curl.exe en $env:DOCUMENT_TRANSLATOR_API_KEY; schrijf de opdracht op één regel in plaats van de hierboven getoonde backslash voor regelafbreking te gebruiken.

Vertaaltegoed en API-sleutels

Elk API-document reserveert één accountcredit, binnen de limieten. Strikte opdrachten worden pas in rekening gebracht wanneer ze zijn gevalideerd en gereed zijn; mislukte of geannuleerde, onvoltooide opdrachten geven de reservering vrij. Bij uitvoer met best-effort kunnen kleine hiaten de afgesproken credit gebruiken, terwijl grote hiaten of kritieke fouten de credit vrijgeven. Raadpleeg outcome.creditOutcome en outcome.completion in plaats van ervan uit te gaan dat voor elk gereed resultaat is betaald.

Maak maximaal vijf actieve API-sleutels per account aan. Sleutels worden maar één keer getoond, als hashes opgeslagen en kunnen worden ingetrokken via Account. Een actieve sleutel geeft toegang tot de betaalde vertalingen van dat account, ook tot opdrachten die met een andere sleutel van hetzelfde account zijn aangemaakt. Met sleutels kun je niet inloggen of betalen.

Opnieuw proberen en onderbroken verzoeken

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

Gebruik dezelfde quote-ID, payload en idempotentiesleutel opnieuw nadat een startverzoek onzeker is verlopen. Identieke nieuwe pogingen retourneren de bestaande taak zonder extra kosten. Een gewijzigde payload of een sleutel die voor een andere quote wordt gebruikt, retourneert 409. Taak- en idempotentiemetadata worden zeven dagen na beëindiging bewaard.

Een hervatbare mislukte taak kan opnieuw worden geprobeerd zolang de brontekst beschikbaar blijft. Bij de nieuwe poging blijft de taak-ID behouden en worden voltooide tekstgedeelten hergebruikt. Per taak zijn maximaal drie verwerkingspogingen toegestaan. Mislukte downloads kunnen opnieuw worden geprobeerd via het resultaateindpunt, zonder een nieuwe vertaling te starten.

Status opvragen en 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

De batchstatus accepteert maximaal 100 ID's en retourneert { jobs: [...] } met uitsluitend geautoriseerde, niet-verwijderde taken. Controleer ongeveer elke vijf seconden tijdens de verwerking en elke vijftien seconden terwijl een taak in de wachtrij staat. Wissel batches eerlijk af wanneer u meer dan 100 taken ophaalt. Pauzeer het controleren in verborgen tabbladen en stop bij eindstatussen of permanente autorisatiefouten.

Wanneer de status 'gereed' is, haal je het resultaat op met dezelfde accountautorisatie. Het bevat de vertaalde segmentkoppeling voor lokale reconstructie. Resultaten zijn 24 uur na voltooiing toegankelijk; mislukte invoer verloopt één uur na aanmaak. Verlopen resultaten geven 410 terug. Verwijderde of ontoegankelijke taken geven 404 terug.

queued → processing → ready
                   ↘ failed / cancelled / expired

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

Sla een voltooid bestand op met PUT, met de binaire inhoud, Content-Length en overeenkomende Content-Type. Ondersteunde extensies zijn docx, pptx, xlsx, pdf, txt en md. Per indeling kan één bestand worden opgeslagen, met een maximale uitvoergrootte van 50 MB. Bij herhaling van een geslaagde opslag blijft het bestaande bestand behouden. Met GET download je het opgeslagen bestand; savedFormats in de taakstatus toont de beschikbare indelingen. Opslaan en downloaden gebruiken dezelfde controles voor taakeigenaarschap, kosten geen extra credits en verlengen de deadline van 24 uur niet.

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 annuleert werk dat nog niet is voltooid of verwijdert beschikbare tekst en opgeslagen bestanden. Het verwijderen van een voltooid resultaat geeft geen terugbetaling en verlengt de downloadperiode niet. Deze versie bevat geen webhooks voor voltooide vertalingen.

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

{"version":2,"parserVersion":"document-ir/9","fingerprint":"{original SHA-256}","ocr":[],"scans":[]}

PUT /api/v1/translations/{id}/source
Content-Type: application/octet-stream
Content-Length: {bytes, maximum 25 MiB}
X-Parser-Version: document-ir/9
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

Accountsaldo en geschiedenis

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

De geschiedenis is alleen toegankelijk voor de huidige eigenaar en gebruikt de geretourneerde pagineringscursor. Het saldo-eindpunt gebruikt de accountsessie van de browser en retourneert minimale aanmeldings- en saldo-informatie. Controleer tijdens een wachtende Checkout elke vijf seconden, maximaal tien keer, pauzeer wanneer de pagina verborgen is en stop zodra het tegoed is bijgeschreven of het account is afgemeld.

n8n, Make en Zapier

Gebruik een HTTP-aanvraagstap met een geheime Bearer-inloggegevenswaarde. Extraheer eerst de tekst, stuur de JSON-payload met POST naar het offerte-eindpunt en stuur vervolgens met POST de offerte-ID, payload en een stabiele idempotentiesleutel van 16–80 tekens naar het vertaaleindpunt. Voeg een vertraging toe en gebruik GET om de status op te vragen totdat de vertaling klaar is; haal daarna het resultaat op en stel de vertaalde tekst opnieuw samen of sla deze op. Bewaar de offerte-ID en de nieuwe-pogingsleutel bij je workflowrecord. Een speciale connector of multipart-upload is niet nodig.

Limieten en fouten

• Maximaal 50.000 bronwoorden, 400.000 geëxtraheerde tekens en 12.000 tekstsegmenten per document. De browser beperkt originele bestanden ook tot 25 MB, pdf's tot 300 pagina's en PowerPoint-bestanden tot 300 dia's. Dit zijn bronlimieten die worden gecontroleerd voordat de vertaling start.
• Maximaal 100 documenten per account in de wachtrij of in verwerking. API-sleutels delen een limiet van 120 offertes per minuut en vijf nieuwe starts of nieuwe pogingen per tien seconden per account. Houd je aan Retry-After bij 429-antwoorden en gebruik begrensde back-off bij tijdelijke fouten; vaker pollen versnelt de verwerking niet.
• De strikte uitvoermodus weigert ontbrekende, dubbele of onjuist opgemaakte vertaalde segmenten voordat er kosten in rekening worden gebracht. De uitvoermodus met beste resultaat behoudt gevalideerde vertalingen en kan in niet-opgeloste secties de oorspronkelijke tekst laten staan. De uitkomst en problemen beschrijven het resultaat. Er wordt geen watermerk of naamsvermelding van de dienst aan de documentinhoud toegevoegd.

Fouten bevatten een foutmelding en code. 400 betekent ongeldige invoer, 401 ongeldige autorisatie, 402 onvoldoende tegoed, 404 een niet-beschikbare taak, 409 een conflicterende offerte of status, 410 verlopen, 429 een limiet voor het aantal verzoeken of de capaciteit, en 503 een niet-beschikbare 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. Privacygegevens