API pentru traducerea textului

Acest API traduce text prin sarcini puse în coadă, cu o singură limbă țintă per sarcină. Trimiteți textul, păstrați ID-ul sarcinii returnate și interogați sarcina până la încheierea procesării. Trimiteți fiecare cerere prin HTTPS cu datele de autentificare ale contului dvs., fie prin HTTP Basic, ca în exemple, fie cu un token API, conform secțiunii Autentificare. Păstrați datele de autentificare pe serverul dvs.

Endpointuri

Cele două gazde API, https://api.multi.tel și gazda de compatibilitate https://api.multitel.net, folosesc în comun aceleași sarcini, chei de idempotență, limite și date de facturare la nivel de cont. Structura exterioară a răspunsului diferă, așadar folosiți consecvent o singură gazdă, cu un parser corespunzător.

Pe api.multi.tel, toate căile sunt disponibile și cu prefixul /v1/translate în loc de /v3/translate. Pe api.multitel.net, folosiți căile /v3/translate.

Răspunsul cu informații despre serviciu include enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000), cpuLanguages și ratesNanosPerCharacter. cpuLanguages enumeră codurile limbilor de bază acceptate pentru traducerea standard. ratesNanosPerCharacter indică prețul configurat pentru fiecare motor, per punct de cod sursă, în miliardimi de dolar SUA: valoarea 5000 înseamnă $5 per milion de puncte de cod. Răspunsul nu indică dacă traducerea îmbunătățită este disponibilă în prezent; o estimare îmbunătățită returnează 503 când aceasta nu este disponibilă. Citirea acestor informații este gratuită.

Traduceți text

Trimiteți JSON cu Content-Type: application/json la POST https://api.multi.tel/v3/translate. Fiecare sarcină are o singură limbă țintă, deci trimiteți o sarcină separată pentru fiecare țintă.

Codurile de limbă și localizare sunt etichete BCP 47 cu 2 până la 63 de litere, cifre și cratime. Sunt aduse la forma canonică, deci en-us este înregistrat ca en-US. Etichetele nevalide și und, mul sau zxx returnează 400 invalid_translation_language. Disponibilitatea traducerii standard este verificată după limba de bază, iar nb și nn sunt considerate no. O țintă regională precum fr-CA este acceptată și înregistrată, dar rezultatul standard urmează limba de bază și nu este garantat că reflectă regiunea.

Păstrați corpul cererii în limita de 128 KiB pe această gazdă. Trimiteți textul ca UTF-8, în loc să reprezentați fiecare caracter non-ASCII printr-o secvență \u, ceea ce poate duce o cerere de 20,000 de caractere peste limită.

Corpul acceptă doar aceste patru câmpuri. Orice altă proprietate este respinsă cu 400 invalid_translation_request, inclusiv idempotency_key, ID-uri de proprietar, marcaje pentru procesare gratuită și liste de segmente.

Idempotență și reutilizare

Fiecare trimitere necesită un antet Idempotency-Key de 1 până la 190 de caractere. Folosiți litere ASCII, cifre, -, _, . și :, fără spații la început sau la sfârșit; o cheie lipsă sau de 191 ori mai multe caractere este respinsă cu 400. Cheile sunt limitate la contul dvs. și la traducere, pe ambele gazde și pentru toate datele de autentificare ale contului.

• Aceeași cheie cu același text, aceleași limbi în formă canonică și același motor returnează sarcina existentă cu HTTP 200 și duplicate: true, fără o nouă taxare.
• Aceeași cheie cu alt text, alte limbi sau alt motor returnează 409 idempotency_conflict. Aceeași cheie returnează 409 și dacă versiunea procesării s-a schimbat de la crearea sarcinii sale. În acest caz, citiți sarcina originală după ID, în loc să o retrimiteți.
• O cheie nouă cu același text, aceleași limbi în formă canonică și același motor returnează sarcina existentă cu HTTP 200 și duplicate: true, fără o nouă taxă de procesare, dacă există o sarcină cu acel conținut și versiunea actuală a procesării, în coadă, în curs de procesare, finalizată sau care așteaptă plata. O sarcină reutilizată care așteaptă plata necesită în continuare decontare. Sarcinile eșuate nu sunt reutilizate: se creează o sarcină nouă, taxată la finalizare.

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'

O sarcină nouă returnează HTTP 202. Textul exemplului are 57 de puncte de cod, deci la $5 per milion de puncte de cod costă $0.000285. Un răspuns prescurtat (identificatorul este un exemplu):

{
  "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
  }
}

Trimiterea poate returna și 402 insufficient_balance când soldul preplătit nu poate acoperi sarcina împreună cu celelalte sarcini restante și 429 translation_queue_full când contul dvs. sau serviciul are prea multe sarcini restante. Returnează 503 în aceste cazuri:

• paid_translation_not_enabled cât timp traducerea cu plată este dezactivată.
• translation_unavailable pentru o cerere îmbunătățită când traducerea îmbunătățită nu este disponibilă.
• translation_pricing_unavailable cât timp motorul ales nu are un tarif configurat.

Reîncercați mai târziu cererile care au primit 429 și 503, cu aceeași cheie.

Alegeți calitatea

Textul lung este procesat în bucăți mai mici și apoi reunit. Sfârșiturile de linie și spațierea se pot schimba, iar o propoziție poate pierde context la limita dintre bucățile procesate. Păstrați textul original și verificați rezultatul reunit. Traducerea standard folosește limba de bază a unei etichete regionale; acceptarea și înregistrarea etichetei nu garantează formulări regionale.

Traducerea standard rulează pe procese de lucru CPU. Traducerea îmbunătățită trimite textul către serviciul AI extern configurat. Rezultatul necesită în continuare verificare; serviciul nu garantează că un motor este mai precis pentru fiecare pereche de limbi sau tip de text.

Traducerea standard este o ciornă a cărei calitate și durată de procesare variază în funcție de perechea de limbi. Traducerea îmbunătățită este destinată textelor în care contează contextul, dar necesită totuși verificarea numelor importante, numerelor, negațiilor și angajamentelor. Niciuna dintre opțiuni nu repară erorile deja prezente într-o transcriere originală, așadar păstrați originalul pentru comparație.

Folosiți GET /v3/translate pe aceeași gazdă API pentru a verifica disponibilitatea actuală, limbile standard acceptate și tarifele configurate. O cerere standard a cărei limbă de bază sursă sau țintă nu se află în cpuLanguages returnează 422 translation_language_pair_unavailable. Când source_language este furnizat și are aceeași limbă de bază ca ținta, cererea returnează 409 translation_same_language în loc să creeze o sarcină. Traducerea îmbunătățită este activată separat: cât timp nu este disponibilă, trimiterile și estimările îmbunătățite returnează 503.

Obțineți mai întâi o estimare

Pe api.multi.tel, trimiteți același corp JSON la POST /v3/translate/estimate. Nu este necesară o cheie de idempotență. Estimarea aplică aceleași validări, inclusiv verificările 422 și 409, dar nu creează o sarcină, nu traduce text, nu rezervă fonduri, nu verifică soldul și nu taxează contul. Returnează HTTP 200 cu estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd și costUsd în data. Pentru exemplul de mai sus, costUsd este 0.000285000 la tariful standard. Când traducerea îmbunătățită nu este disponibilă, o estimare îmbunătățită returnează 503 service_unavailable. Estimările folosesc tariful configurat în prezent. Tariful unei sarcini este fixat la crearea ei, iar taxa folosește acel tarif.

Obțineți traducerea

O trimitere nouă returnează HTTP 202, iar o sarcină existentă sau reutilizată returnează HTTP 200. Păstrați data.id și urmați fluxul de lucru al sarcinilor folosit în comun. Obiectul sarcinii conține aceste câmpuri:

• id, status, engine, sourceLocale și targetLocale.
• sourceCharacters, costUsd, costIsEstimate și pricePerMillionCharactersUsd.
• progress și createdAt.
• modelVersion, un șir opac care indică versiunea procesării.
• duplicate în răspunsurile reutilizate.
• failureCode pentru sarcini eșuate: translation_failed, translation_timeout, input_failed sau worker_lease_lost.

O sarcină eșuată afișează costUsd egal cu zero.

O sarcină finalizată are data.result cu sourceLocale (gol dacă nu a fost furnizată limba sursă), targetLocale, câmpul tradus text (textele segmentelor unite prin sfârșituri de linie) și segments. Pentru text trimis prin acest API, segments conține o singură intrare cu text tradus și limba țintă language. Rezultatele sarcinilor care așteaptă plata sunt reținute până la decontare.

Utilizarea api.multitel.net

Endpointul de compatibilitate POST https://api.multitel.net/v3/translate acceptă aceleași câmpuri JSON și același antet Idempotency-Key. Dacă antetul lipsește, acceptă și un șir idempotency_key în corpul JSON. Orice alt câmp suplimentar este respins cu 400 unsupported_translation_option. Pe această gazdă, corpul brut poate avea cel mult 256,000 de octeți, iar textul de peste 20,000 de puncte de cod returnează 413 translation_too_large în loc de 400. Un source_language gol este tratat ca omis. Un răspuns 429 include Retry-After: 15. Această gazdă returnează și următoarele erori:

• 400 json_body_required când corpul lipsește, nu este JSON valid sau este o valoare scalară JSON. Trimiteți un obiect JSON.
• 400 invalid_translation_options când text, target_language sau engine lipsește, este gol sau nu este un șir ori când source_language nu este un șir.
• 400 invalid_translation_text pentru text care conține doar spații albe.
• 400 invalid_translation_engine pentru un motor necunoscut.
• 400 idempotency_key_required pentru o cheie lipsă, goală sau prea lungă ori pentru un idempotency_key care nu este un șir.
• 400 invalid_job pentru un ID de sarcină cu format incorect.

Răspunsurile serviciului de traducere de pe această gazdă folosesc structura exterioară {"status":{"code":HTTP_STATUS},"response":{...}}, în care status este un obiect. Citiți ID-ul sarcinii din response.id și rezultatul finalizat din response.result. Erorile plasează codul în response.code, fără mesaj sau ID de cerere. Erorile de autentificare (401) sunt returnate de verificarea generală de conectare a gazdei și pot avea alt corp, așadar verificați starea HTTP înainte de parsare. Sarcinile sunt comune cu gazda principală, dar folosiți aceeași gazdă pentru interogarea periodică, decontare și utilizare, astfel încât parserul să corespundă structurii exterioare. Această gazdă acceptă aceleași câmpuri JSON și la /v3/translate/estimate fără cheie de idempotență, iar estimarea se află în response.