API di traduzione di documenti

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."
    }
  ]
}

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."
      }
    ]
  }
}

// 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.

Crediti di traduzione e chiavi API

Ogni documento API consuma un credito dell’account, entro i limiti di caricamento. I crediti vengono riservati all’avvio e addebitati quando è pronta una traduzione completa e convalidata. I crediti bonus di registrazione possono essere usati tramite API; la quota gratuita giornaliera è disponibile solo sul sito.

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

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 dieci 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 dieci 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.

Salva un file completato con PUT usando il corpo binario, Content-Length e un Content-Type corrispondente. Le estensioni supportate sono docx, 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.

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.

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.

Limiti ed errori

• Fino a 50,000 parole di origine, 400,000 caratteri estratti e 12,000 segmenti di testo per documento. Il browser limita inoltre i file originali a 25 MB e i PDF a 100 pagine.
• Fino a 100 documenti in coda o in elaborazione per account. Avvii e tentativi condividono i limiti di frequenza. Rispetta Retry-After nelle risposte 429 e usa un backoff limitato in caso di errori temporanei.
• Segmenti tradotti mancanti, duplicati o malformati non superano la convalida prima della pubblicazione e dell’addebito. I crediti riservati vengono restituiti per i lavori non completati, non riusciti o annullati.

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.

I documenti originali restano sul tuo client. Il testo estratto viene elaborato dal nostro provider di traduzione e i file tradotti salvati vengono conservati in privato per il download. La memoria temporanea viene ripulita secondo una pianificazione; si applicano anche le politiche di conservazione del provider. Dettagli sulla privacy