API di traduzione di documenti

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
}

Una richiesta di preventivo con cURL

Salva il JSON del preventivo qui sopra come payload.json e imposta DOCUMENT_TRANSLATOR_API_KEY nella shell. Questo comando richiede solo un preventivo. Per iniziare, invia il JSON di avvio con l’ID del preventivo restituito e il payload identico all’endpoint delle traduzioni.

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, usa curl.exe e $env:DOCUMENT_TRANSLATOR_API_KEY; scrivi il comando su un’unica riga invece di usare la barra rovesciata per andare a capo mostrata sopra.

Crediti di traduzione e chiavi API

Ogni documento inviato all’API prenota un credito dell’account, entro i limiti previsti. I processi rigorosi addebitano il credito solo dopo la convalida e quando il risultato è pronto; i processi incompleti non riusciti o annullati liberano la prenotazione. Con l’output con tolleranza agli errori, piccole lacune possono comportare l’addebito del credito concordato, mentre lacune importanti o errori critici lo liberano. Consulta outcome.creditOutcome e outcome.completion invece di presumere che ogni risultato pronto sia stato addebitato.

Crea fino a cinque chiavi API attive per account. Le chiavi vengono mostrate una sola volta, archiviate sotto forma di hash e possono essere revocate dalla sezione Account. Una chiave attiva può accedere alle traduzioni a pagamento dell’account, compresi i lavori creati con un’altra chiave dello stesso account. Le chiavi non autorizzano l’accesso all’account né i pagamenti.

Nuovi tentativi e richieste interrotte

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

Se non sai se la richiesta iniziale è andata a buon fine, riutilizza lo stesso ID del preventivo, lo stesso payload e la stessa chiave di idempotenza. I nuovi tentativi identici restituiscono il lavoro esistente senza un ulteriore addebito. Un payload modificato o una chiave riutilizzata per un altro preventivo restituisce 409. I metadati del lavoro e dell’idempotenza vengono conservati per sette giorni dopo la conclusione.

Un lavoro non riuscito ma riprendibile può essere ritentato finché il testo sorgente è disponibile. Il nuovo tentativo mantiene lo stesso ID del lavoro e riutilizza i segmenti completati. Sono consentiti al massimo tre tentativi di elaborazione per lavoro. In caso di errori di download, è possibile riprovare dall’endpoint del risultato senza avviare un’altra traduzione.

Interrogazioni e download

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

Lo stato batch accetta al massimo 100 ID e restituisce { jobs: [...] }, contenente solo i lavori autorizzati e non eliminati. Durante l’elaborazione, controlla lo stato circa ogni cinque secondi; mentre è in coda, ogni quindici secondi. Se devi recuperare più di 100 lavori, alterna i batch in modo equo. Sospendi i controlli nelle schede nascoste e interrompili quando lo stato è terminale o si verificano errori di autorizzazione permanenti.

Quando lo stato è pronto, recupera il risultato usando la stessa autorizzazione dell’account. Contiene la mappatura dei segmenti tradotti per ricostruire il documento localmente. I risultati sono accessibili per 24 ore dal completamento; gli input non riusciti scadono un’ora dopo la creazione. I risultati scaduti restituiscono 410. I job eliminati o inaccessibili restituiscono 404.

queued → processing → ready
                   ↘ failed / cancelled / expired

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

Salva un file completato con PUT usando il corpo binario, Content-Length e un Content-Type corrispondente. Le estensioni supportate sono docx, pptx, xlsx, pdf, txt e md; è possibile salvare un file per formato, fino a 50 MB. Ripetere un salvataggio riuscito mantiene il file esistente. GET scarica il file salvato; savedFormats nello stato del job elenca i formati disponibili. Salvataggio e download applicano gli stessi controlli di proprietà del job, non consumano crediti aggiuntivi e non prolungano mai la scadenza di 24 ore.

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 annulla le operazioni non concluse o rimuove il testo disponibile e i file salvati. L’eliminazione di un risultato completato non dà diritto a un rimborso né prolunga il periodo di download. In questa versione non sono disponibili webhook di completamento.

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

Saldo e cronologia dell’account

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

La cronologia è limitata al proprietario attuale e utilizza il cursore di paginazione restituito. L’endpoint del saldo usa la sessione dell’account nel browser e restituisce solo le informazioni essenziali su accesso e saldo. Durante un Checkout in sospeso, interroga l’endpoint ogni cinque secondi per un massimo di dieci tentativi; sospendi il polling quando la pagina è nascosta e interrompilo quando vengono accreditati i crediti o l’account esce.

n8n, Make e Zapier

Usa un passaggio di richiesta HTTP con credenziali Bearer segrete. Estrai prima il testo, invia il payload JSON all’endpoint dei preventivi con POST, quindi invia l’ID del preventivo, il payload e una chiave di idempotenza stabile di 16–80 caratteri all’endpoint delle traduzioni con POST. Aggiungi un ritardo e controlla lo stato con GET finché non è pronto, recupera il risultato e ricostruisci o salva il testo tradotto. Conserva l’ID del preventivo e la chiave di ripetizione insieme ai dati del flusso di lavoro. Non è richiesto alcun connettore dedicato né un caricamento multipart.

Limiti ed errori

• Fino a 50.000 parole sorgente, 400.000 caratteri estratti e 12.000 segmenti di testo per documento. Il browser limita inoltre i file originali a 25 MB, i PDF a 300 pagine e i file PowerPoint a 300 diapositive. Questi limiti riguardano il file sorgente e vengono verificati prima dell’avvio della traduzione.
• Fino a 100 documenti in coda o in elaborazione per account. Le chiavi API condividono un limite di 120 preventivi al minuto e cinque nuovi avvii o tentativi ogni dieci secondi per account. Rispetta Retry-After nelle risposte 429 e usa un backoff limitato per gli errori temporanei; aumentare la frequenza dei controlli non accelera l’elaborazione.
• L’output rigoroso rifiuta i segmenti tradotti mancanti, duplicati o malformati prima dell’addebito. L’output con tolleranza agli errori conserva le traduzioni convalidate e può mantenere il testo originale nelle sezioni irrisolte; outcome e issues descrivono il risultato. Non vengono aggiunti watermark né attribuzioni al servizio al contenuto del documento.

Gli errori includono un messaggio e un codice. 400 indica un input non valido, 401 un’autorizzazione non valida, 402 crediti insufficienti, 404 un lavoro non disponibile, 409 un preventivo o uno stato in conflitto, 410 una scadenza, 429 un limite di frequenza o di capacità e 503 un servizio non disponibile.

Conserviamo una copia privata del documento originale fino a 24 ore dopo il completamento della traduzione, per consentirti di recuperare i download. Puoi rimuoverla prima eliminando la traduzione. Al nostro fornitore di traduzione viene inviato solo il testo estratto. Dettagli sulla privacy