Teksvertaal-API

Hierdie API vertaal teks as take in ’n verwerkingsry, met een doeltaal per taak. Dien teks in, hou die teruggestuurde taak-ID en vra die taak op totdat verwerking klaar is. Stuur elke versoek oor HTTPS met jou rekening se aanmeldbesonderhede: óf HTTP Basic-aanmeldbesonderhede soos in die voorbeelde, óf ’n API-token, soos beskryf onder Stawing. Hou aanmeldbesonderhede op jou bediener.

Eindpunte

Twee API-gashere, https://api.multi.tel en die versoenbaarheidsgasheer https://api.multitel.net, deel dieselfde rekeninggebonde take, idempotensiesleutels, perke en heffings. Hulle verskil in antwoordomhulsel; gebruik dus deurgaans een gasheer met ’n ooreenstemmende ontleder.

Op api.multi.tel is elke pad ook beskikbaar met die voorvoegsel /v1/translate in plaas van /v3/translate. Op api.multitel.net gebruik jy die /v3/translate-paaie.

Die antwoord met diensinligting bevat enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000), cpuLanguages en ratesNanosPerCharacter. cpuLanguages lys die basistaalkodes wat vir standaardvertaling aanvaar word. ratesNanosPerCharacter gee die ingestelde prys per kodepunt in die bronteks vir elke enjin, in miljardstes van ’n Amerikaanse dollar: ’n waarde van 5000 beteken $5 per miljoen kodepunte. Die antwoord meld nie of verbeterde vertaling tans beskikbaar is nie; ’n raming vir verbeterde vertaling stuur 503 terug wanneer dit nie beskikbaar is nie. Dit is gratis om hierdie inligting te lees.

Vertaal teks

Stuur JSON met Content-Type: application/json na POST https://api.multi.tel/v3/translate. Elke taak het een doeltaal; dien dus ’n afsonderlike taak vir elke doeltaal in.

Lokalekodes is BCP 47-etikette met ’n lengte van 2 tot 63 karakters, bestaande uit letters, syfers en koppeltekens. Hulle word gekanoniseer, dus word en-us aangeteken as en-US. Ongeldige etikette, en und, mul of zxx, stuur 400 invalid_translation_language terug. Standaardbeskikbaarheid word volgens die basistaal nagegaan, en nb en nn tel as no. ’n Streeksdoeltaal soos fr-CA word aanvaar en aangeteken, maar standaarduitvoer volg die basistaal en is nie gewaarborg om die streek te weerspieël nie.

Hou die versoekliggaam op hierdie gasheer binne 128 KiB. Stuur teks as UTF-8 eerder as om elke nie-ASCII-karakter met ’n \u-ontsnappingsreeks voor te stel, wat ’n versoek van 20,000 karakters oor die perk kan stoot.

Die liggaam aanvaar slegs hierdie vier velde. Enige ander eienskap word met 400 invalid_translation_request verwerp, insluitend idempotency_key, eienaar-ID’s, vlae vir gratis verwerking en segmentskikkings.

Idempotensie en hergebruik

Elke indiening vereis ’n Idempotency-Key-kopskrif van 1 tot 190 karakters. Gebruik ASCII-letters, syfers, -, _, . en :, sonder spasies aan die begin of einde; ’n ontbrekende sleutel of ’n sleutel van 191 of meer karakters word met 400 verwerp. Sleutels is tot jou rekening en vertaling beperk, oor albei gashere en al jou rekening se aanmeldbesonderhede heen.

• Dieselfde sleutel met dieselfde teks, kanonieke tale en enjin stuur die bestaande taak met HTTP 200 en duplicate: true terug, sonder nog ’n heffing.
• Dieselfde sleutel met ander teks, tale of ’n ander enjin stuur 409 idempotency_conflict terug. Dieselfde sleutel stuur ook 409 terug as die verwerkingsweergawe sedert die skepping van sy taak verander het. Lees in daardie geval die oorspronklike taak volgens sy ID eerder as om dit weer in te dien.
• ’n Nuwe sleutel met dieselfde teks, kanonieke tale en enjin stuur die bestaande taak met HTTP 200 en duplicate: true terug, sonder ’n nuwe verwerkingsheffing, as ’n taak met daardie inhoud en die huidige verwerkingsweergawe in die ry wag, loop, voltooi is of op betaling wag. ’n Hergebruikte taak wat op betaling wag, moet steeds vereffen word. Mislukte take word nie hergebruik nie: ’n nuwe taak word geskep en gehef wanneer dit voltooi word.

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'

’n Nuwe taak stuur HTTP 202 terug. Die voorbeeldteks het 57 kodepunte, dus kos dit teen $5 per miljoen kodepunte $0.000285. ’n Verkorte antwoord (die identifiseerder is ’n voorbeeld):

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

’n Indiening kan ook 402 insufficient_balance terugstuur wanneer ’n voorafbetaalde saldo nie die taak saam met jou ander uitstaande take kan dek nie, en 429 translation_queue_full wanneer jou rekening of die diens te veel uitstaande take het. Dit stuur in hierdie gevalle 503 terug:

• paid_translation_not_enabled terwyl betaalde vertaling gedeaktiveer is.
• translation_unavailable vir ’n versoek vir verbeterde vertaling terwyl verbeterde vertaling onbeskikbaar is.
• translation_pricing_unavailable terwyl die gekose enjin geen ingestelde tarief het nie.

Probeer antwoorde met 429 en 503 later weer met dieselfde sleutel.

Kies die gehalte

Lang teks word in kleiner stukke verwerk en weer saamgevoeg. Reëlbreuke en spasiëring kan verander, en ’n sin kan konteks oor ’n verwerkingsgrens heen verloor. Hou die oorspronklike teks en hersien die saamgestelde resultaat. Standaardvertaling gebruik die basistaal van ’n streeksetiket; die aanvaarding en aantekening van ’n etiket waarborg nie streekspesifieke bewoording nie.

Standaardvertaling loop op CPU-werkers. Verbeterde vertaling stuur teks na die ingestelde eksterne KI-diens. Die uitvoer daarvan moet steeds hersien word; die diens waarborg nie dat een enjin akkurater vir elke taalpaar of soort teks is nie.

Standaardvertaling is ’n konsep waarvan die gehalte en verwerkingstyd volgens taalpaar wissel. Verbeterde vertaling is bedoel vir teks waar konteks belangrik is, maar vereis steeds hersiening van belangrike name, getalle, ontkennings en verbintenisse. Nie een van die opsies herstel foute wat reeds in ’n oorspronklike transkripsie voorkom nie; hou dus die oorspronklike vir vergelyking.

Gebruik GET /v3/translate op dieselfde API-gasheer om huidige beskikbaarheid, ondersteunde standaardtale en ingestelde tariewe na te gaan. ’n Standaardversoek waarvan die bron- of doelbasistaal nie in cpuLanguages is nie, stuur 422 translation_language_pair_unavailable terug. Wanneer source_language verskaf word en dieselfde basistaal as die doeltaal het, stuur die versoek 409 translation_same_language terug in plaas daarvan om ’n taak te skep. Verbeterde vertaling word afsonderlik geaktiveer: terwyl dit onbeskikbaar is, stuur indienings en ramings vir verbeterde vertaling 503 terug.

Kry eers ’n raming

Op api.multi.tel, stuur dieselfde JSON-liggaam na POST /v3/translate/estimate. Geen idempotensiesleutel word vereis nie. ’n Raming pas dieselfde validering toe, met inbegrip van die kontroles vir 422 en 409, maar skep nie ’n taak nie, vertaal nie teks nie, reserveer nie geld nie, gaan nie jou saldo na nie en hef nie jou rekening nie. Dit stuur HTTP 200 terug met estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd en costUsd onder data. Vir die voorbeeld hierbo is costUsd gelyk aan 0.000285000 teen die standaardtarief. Terwyl verbeterde vertaling onbeskikbaar is, stuur ’n raming vir verbeterde vertaling 503 service_unavailable terug. Ramings gebruik die tans ingestelde tarief. ’n Taak se tarief word by die skepping van die taak vasgestel, en sy heffing gebruik daardie tarief.

Kry die vertaling

’n Nuwe indiening stuur HTTP 202 terug, en ’n bestaande of hergebruikte taak stuur HTTP 200 terug. Hou data.id en gebruik die gedeelde taakwerkvloei. Die taakobjek bevat hierdie velde:

• id, status, engine, sourceLocale en targetLocale.
• sourceCharacters, costUsd, costIsEstimate en pricePerMillionCharactersUsd.
• progress en createdAt.
• modelVersion, ’n ondeursigtige string vir die verwerkingsweergawe.
• duplicate op antwoorde vir hergebruikte take.
• failureCode vir mislukte take: translation_failed, translation_timeout, input_failed of worker_lease_lost.

’n Mislukte taak toon ’n costUsd van nul.

’n Voltooide taak het data.result met sourceLocale (leeg as geen brontaal verskaf is nie), targetLocale, die vertaalde text (segmenttekste wat met reëlbreuke saamgevoeg is), en segments. Vir teks wat deur hierdie API ingedien is, bevat segments een inskrywing met die vertaalde text en die doelveld language. Resultate van take wat op betaling wag, word teruggehou totdat hulle vereffen is.

Gebruik van api.multitel.net

Die versoenbaarheidseindpunt POST https://api.multitel.net/v3/translate aanvaar dieselfde JSON-velde en dieselfde Idempotency-Key-kopskrif. As die kopskrif ontbreek, aanvaar dit ook ’n idempotency_key-string in die JSON-liggaam. Enige ander ekstra veld word met 400 unsupported_translation_option verwerp. Op hierdie gasheer kan die rou liggaam tot 256,000 grepe wees, en teks van meer as 20,000 kodepunte stuur 413 translation_too_large terug eerder as 400. ’n Leë source_language word as weggelaat behandel. ’n Antwoord met 429 sluit Retry-After: 15 in. Hierdie gasheer stuur ook hierdie foute terug:

• 400 json_body_required wanneer die liggaam ontbreek, ongeldige JSON of ’n JSON-skalaar is. Stuur ’n JSON-objek.
• 400 invalid_translation_options wanneer text, target_language of engine ontbreek, leeg of nie ’n string is nie, of source_language nie ’n string is nie.
• 400 invalid_translation_text vir teks wat slegs uit witspasie bestaan.
• 400 invalid_translation_engine vir ’n onbekende enjin.
• 400 idempotency_key_required vir ’n ontbrekende, leë of te lang sleutel, of ’n idempotency_key wat nie ’n string is nie.
• 400 invalid_job vir ’n verkeerd gevormde taak-ID.

Antwoorde van hierdie gasheer se vertaaldiens gebruik die omhulsel {"status":{"code":HTTP_STATUS},"response":{...}}, waar status ’n objek is. Lees die taak-ID uit response.id en die voltooide resultaat uit response.result. Foute plaas die kode in response.code, sonder ’n boodskap of versoek-ID. Stawingsfoute (401) word deur die gasheer se algemene aanmeldkontrole teruggestuur en kan ’n ander liggaam hê; gaan dus die HTTP-status na voordat jy die antwoord ontleed. Take word met die primêre gasheer gedeel, maar gebruik dieselfde gasheer vir herhaalde statusnavrae, vereffening en gebruik sodat jou ontleder by die omhulsel pas. Hierdie gasheer aanvaar ook dieselfde JSON-velde by /v3/translate/estimate sonder ’n idempotensiesleutel, en sy raming is onder response.