API di traduzione del testo

Questa API traduce testo tramite attività in coda, con una sola lingua di destinazione per attività. Invia il testo, conserva l’ID dell’attività restituito e consulta l’attività finché l’elaborazione non è terminata. Invia ogni richiesta tramite HTTPS con le credenziali del tuo account: credenziali HTTP Basic come negli esempi oppure un token API, come descritto in Autenticazione. Conserva le credenziali sul tuo server.

Endpoint

I due server API, https://api.multi.tel e il server di compatibilità https://api.multitel.net, condividono attività, chiavi di idempotenza, limiti e fatturazione nell’ambito dello stesso account. Differiscono per la struttura esterna delle risposte: usa quindi sempre lo stesso server con un parser corrispondente.

Su api.multi.tel, ogni percorso è disponibile anche con il prefisso /v1/translate al posto di /v3/translate. Su api.multitel.net, usa i percorsi /v3/translate.

La risposta con le informazioni sul servizio riporta enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000), cpuLanguages e ratesNanosPerCharacter. cpuLanguages elenca i codici delle lingue di base accettate per la traduzione standard. ratesNanosPerCharacter indica il prezzo configurato per punto di codice sorgente di ciascun motore, in miliardesimi di dollaro statunitense: un valore di 5000 significa $5 per milione di punti di codice. La risposta non indica se la traduzione avanzata è attualmente disponibile; una stima avanzata restituisce 503 quando non lo è. La consultazione è gratuita.

Tradurre testo

Invia JSON con Content-Type: application/json a POST https://api.multi.tel/v3/translate. Ogni attività ha una sola lingua di destinazione: invia quindi un’attività separata per ogni destinazione.

I codici locali sono tag BCP 47 da 2 a 63 lettere, cifre e trattini. Vengono convertiti in forma canonica, quindi en-us viene registrato come en-US. I tag non validi, e und, mul o zxx, restituiscono 400 invalid_translation_language. La disponibilità standard è verificata per lingua di base, e nb e nn sono considerati no. Una destinazione regionale come fr-CA è accettata e registrata, ma il risultato standard segue la lingua di base e non è garantito che rispecchi la regione.

Su questo server, mantieni il corpo della richiesta entro 128 KiB. Invia il testo come UTF-8 anziché rappresentare ogni carattere non ASCII con una sequenza \u, che può far superare il limite a una richiesta di 20,000 caratteri.

Il corpo accetta solo questi quattro campi. Qualsiasi altra proprietà viene rifiutata con 400 invalid_translation_request, inclusi idempotency_key, gli ID del proprietario, i flag di elaborazione gratuita e gli array di segmenti.

Idempotenza e riutilizzo

Ogni invio richiede un’intestazione Idempotency-Key di lunghezza compresa tra 1 e 190 caratteri. Usa lettere ASCII, cifre, -, _, . e :, senza spazi iniziali o finali; una chiave assente o di almeno 191 caratteri viene rifiutata con 400. Le chiavi sono limitate al tuo account e alla traduzione, su entrambi i server e per tutte le credenziali dell’account.

• La stessa chiave con lo stesso testo, le stesse lingue in forma canonica e lo stesso motore restituisce l’attività esistente con HTTP 200 e duplicate: true, senza un nuovo addebito.
• La stessa chiave con testo, lingue o motore diversi restituisce 409 idempotency_conflict. La stessa chiave restituisce 409 anche se la versione dell’elaborazione è cambiata da quando è stata creata la sua attività. In tal caso, leggi l’attività originale tramite il suo ID anziché inviarla di nuovo.
• Una nuova chiave con lo stesso testo, le stesse lingue in forma canonica e lo stesso motore restituisce l’attività esistente con HTTP 200 e duplicate: true, senza nuovi addebiti di elaborazione, se un’attività con quel contenuto e la versione attuale dell’elaborazione è in coda, in elaborazione, completata o in attesa di pagamento. Un’attività riutilizzata in attesa di pagamento deve comunque essere saldata. Le attività non riuscite non vengono riutilizzate: viene creata una nuova attività, addebitata al completamento.

API_USER="your-api-username"
API_PASSWORD="your-api-password"

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: translation-example-001" \
  --data '{"text":"Please move my appointment to Tuesday at 3 PM, not 11 AM.","source_language":"en","target_language":"es","engine":"cpu"}' \
  -o translation-job.json \
  https://api.multi.tel/v3/translate

node -p 'JSON.parse(require("node:fs").readFileSync("translation-job.json","utf8")).data.id'

Una nuova attività restituisce HTTP 202. Il testo di esempio contiene 57 punti di codice, quindi a $5 per milione di punti di codice costa $0.000285. Una risposta abbreviata (l’identificatore è un esempio):

{
  "status": "success",
  "data": {
    "id": "8b2e4c71-5d3a-4f09-a6e2-1c7f9d3b5a28",
    "status": "queued",
    "mode": "batch",
    "realtime": false,
    "engine": "cpu",
    "sourceLocale": "en",
    "targetLocale": "es",
    "sourceCharacters": 57,
    "costUsd": "0.000285000",
    "costIsEstimate": true,
    "pricePerMillionCharactersUsd": "5.000000000",
    "progress": null
  }
}

Un invio può anche restituire 402 insufficient_balance quando il saldo prepagato non copre l’attività insieme alle altre attività in sospeso e 429 translation_queue_full quando l’account o il servizio hanno troppe attività in sospeso. Restituisce 503 in questi casi:

• paid_translation_not_enabled quando la traduzione a pagamento è disabilitata.
• translation_unavailable per una richiesta avanzata quando la traduzione avanzata non è disponibile.
• translation_pricing_unavailable quando il motore scelto non ha una tariffa configurata.

In caso di risposta 429 o 503, riprova più tardi con la stessa chiave.

Scegliere la qualità

Il testo lungo viene elaborato in parti più piccole, poi riunite. Le interruzioni di riga e la spaziatura possono cambiare, e una frase può perdere contesto tra una parte elaborata e l’altra. Conserva il testo originale e rivedi il risultato assemblato. La traduzione standard usa la lingua di base di un tag regionale: accettare e registrare un tag non garantisce una formulazione regionale.

La traduzione standard viene eseguita da processi di elaborazione su CPU. La traduzione avanzata invia il testo al servizio di IA esterno configurato. Anche il suo risultato richiede una revisione: il servizio non garantisce che un motore sia più accurato per ogni coppia di lingue o tipo di testo.

La traduzione standard è una bozza la cui qualità e i cui tempi di elaborazione variano in base alla coppia di lingue. La traduzione avanzata è destinata a testi in cui conta il contesto, ma richiede comunque una revisione di nomi, numeri, negazioni e impegni importanti. Nessuna delle due opzioni corregge errori già presenti in una trascrizione originale: conserva quindi l’originale per il confronto.

Usa GET /v3/translate sullo stesso server API per verificare la disponibilità attuale, le lingue standard supportate e le tariffe configurate. Una richiesta standard la cui lingua di base sorgente o di destinazione non è in cpuLanguages restituisce 422 translation_language_pair_unavailable. Quando source_language è fornito e ha la stessa lingua di base della destinazione, la richiesta restituisce 409 translation_same_language anziché creare un’attività. La traduzione avanzata viene abilitata separatamente: quando non è disponibile, gli invii e le stime avanzati restituiscono 503.

Ottenere prima una stima

Su api.multi.tel, invia lo stesso corpo JSON a POST /v3/translate/estimate. Non serve una chiave di idempotenza. Una stima applica la stessa validazione, inclusi i controlli 422 e 409, ma non crea un’attività, non traduce testo, non riserva fondi, non controlla il saldo e non comporta addebiti sul tuo account. Restituisce HTTP 200 con estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd e costUsd in data. Per l’esempio sopra, costUsd è 0.000285000 alla tariffa standard. Quando la traduzione avanzata non è disponibile, una stima avanzata restituisce 503 service_unavailable. Le stime usano la tariffa attualmente configurata. La tariffa di un’attività è fissata alla creazione e l’addebito usa quella tariffa.

Recuperare la traduzione

Un nuovo invio restituisce HTTP 202, mentre un’attività esistente o riutilizzata restituisce HTTP 200. Conserva data.id e usa il flusso delle attività condiviso. L’oggetto dell’attività contiene questi campi:

• id, status, engine, sourceLocale e targetLocale.
• sourceCharacters, costUsd, costIsEstimate e pricePerMillionCharactersUsd.
• progress e createdAt.
• modelVersion, una stringa opaca che indica la versione dell’elaborazione.
• duplicate nelle risposte riutilizzate.
• failureCode per attività non riuscite: translation_failed, translation_timeout, input_failed o worker_lease_lost.

Un’attività non riuscita mostra un costUsd pari a zero.

Un’attività completata contiene data.result con sourceLocale (vuoto se non è stata indicata una lingua sorgente), targetLocale, il testo tradotto in text (testi dei segmenti uniti da interruzioni di riga) e segments. Per il testo inviato tramite questa API, segments contiene una sola voce con il testo tradotto in text e la lingua di destinazione in language. I risultati delle attività in attesa di pagamento vengono trattenuti fino al saldo.

Usare api.multitel.net

L’endpoint di compatibilità POST https://api.multitel.net/v3/translate accetta gli stessi campi JSON e la stessa intestazione Idempotency-Key. Se l’intestazione manca, accetta anche una stringa idempotency_key nel corpo JSON. Qualsiasi altro campo aggiuntivo viene rifiutato con 400 unsupported_translation_option. Su questo server, il corpo grezzo può arrivare a 256,000 byte e il testo oltre 20,000 punti di codice restituisce 413 translation_too_large anziché 400. Un source_language vuoto viene trattato come omesso. Una risposta 429 include Retry-After: 15. Questo server restituisce anche questi errori:

• 400 json_body_required quando il corpo manca, non è JSON valido o è uno scalare JSON. Invia un oggetto JSON.
• 400 invalid_translation_options quando text, target_language o engine è assente, vuoto o non è una stringa, oppure source_language non è una stringa.
• 400 invalid_translation_text per testo composto solo da spazi bianchi.
• 400 invalid_translation_engine per un motore sconosciuto.
• 400 idempotency_key_required per una chiave assente, vuota o troppo lunga, oppure un idempotency_key che non è una stringa.
• 400 invalid_job per un ID dell’attività non correttamente formato.

Le risposte del servizio di traduzione di questo server usano la struttura esterna {"status":{"code":HTTP_STATUS},"response":{...}}, dove status è un oggetto. Leggi l’ID dell’attività da response.id e il risultato completato da response.result. Gli errori inseriscono il codice in response.code, senza un messaggio o un ID della richiesta. Gli errori di autenticazione (401) vengono restituiti dal controllo generale di accesso del server e possono avere un corpo diverso: controlla quindi lo stato HTTP prima del parsing. Le attività sono condivise con il server principale, ma usa lo stesso server per le interrogazioni periodiche, il saldo e l’utilizzo, così che il parser corrisponda alla struttura esterna. Questo server accetta gli stessi campi JSON anche in /v3/translate/estimate senza una chiave di idempotenza e la sua stima è in response.