Tekstinkäännös-API

Tämä API kääntää tekstiä jonossa käsiteltävinä töinä, yksi kohdekieli työtä kohti. Lähetä teksti, tallenna palautettu työn tunniste ja hae työn tiedot, kunnes käsittely on valmis. Lähetä kaikki pyynnöt HTTPS-yhteydellä käyttäen tilisi tunnistetietoja: esimerkkien mukaisia HTTP Basic -tunnistetietoja tai API-tunnusta, kuten kuvataan kohdassa Todennus. Säilytä tunnistetiedot palvelimellasi.

Päätepisteet

Kaksi API-palvelinta, https://api.multi.tel ja yhteensopivuuspalvelin https://api.multitel.net, jakavat samat tilikohtaiset työt, idempotenssiavaimet, rajoitukset ja laskutuksen. Vastauksen rakenne eroaa, joten käytä johdonmukaisesti yhtä palvelinta ja siihen sopivaa jäsennintä.

Palvelimella api.multi.tel kaikki polut ovat käytettävissä myös etuliitteellä /v1/translate seuraavan sijasta: /v3/translate. Palvelimella api.multitel.net käytä /v3/translate-polkuja.

Palvelutietovastaus sisältää kentät enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000), cpuLanguages ja ratesNanosPerCharacter. cpuLanguages luettelee peruskielten koodit, jotka hyväksytään vakiokäännöksessä. ratesNanosPerCharacter ilmoittaa kunkin moottorin määritetyn hinnan lähdetekstin koodipistettä kohti Yhdysvaltain dollarin miljardisosina: arvo 5000 tarkoittaa $5 miljoonaa koodipistettä kohti. Vastaus ei ilmoita, onko tehostettu käännös tällä hetkellä käytettävissä; tehostettu arvio palauttaa 503, kun se ei ole käytettävissä. Tietojen haku on maksutonta.

Käännä teksti

Lähetä JSON otsakkeella Content-Type: application/json osoitteeseen POST https://api.multi.tel/v3/translate. Jokaisella työllä on yksi kohdekieli, joten lähetä erillinen työ kutakin kohdekieltä varten.

Kielitunnisteet ovat BCP 47 -tunnisteita, joissa on 2–63 kirjainta, numeroa ja yhdysmerkkiä. Ne kanonisoidaan, joten en-us tallennetaan muodossa en-US. Virheelliset tunnisteet sekä und, mul tai zxx palauttavat 400 invalid_translation_language. Vakiokäännöksen saatavuus tarkistetaan peruskielen perusteella, ja nb ja nn lasketaan kieleksi no. Alueellinen kohdekieli, kuten fr-CA, hyväksytään ja tallennetaan, mutta vakiotulos noudattaa peruskieltä eikä sen taata vastaavan alueellista kielenkäyttöä.

Pidä pyynnön runko tällä palvelimella enintään 128 KiB:n kokoisena. Lähetä teksti UTF-8-muodossa sen sijaan, että esittäisit jokaisen ASCII-merkistöön kuulumattoman merkin \u-sekvenssinä, mikä voi viedä 20,000 merkin pyynnön rajan yli.

Runko hyväksyy vain nämä neljä kenttää. Kaikki muut ominaisuudet hylätään vastauksella 400 invalid_translation_request, mukaan lukien idempotency_key, omistajatunnisteet, maksuttoman käsittelyn liput ja segmenttitaulukot.

Idempotenssi ja uudelleenkäyttö

Jokainen lähetys vaatii Idempotency-Key-otsakkeen, jossa on 1–190 merkkiä. Käytä ASCII-kirjaimia, numeroita, -, _, . ja : ilman alku- tai loppuvälilyöntejä; puuttuva avain tai vähintään 191 merkin avain hylätään vastauksella 400. Avaimet rajataan tiliisi ja käännökseen molemmilla palvelimilla ja kaikilla tilisi tunnistetiedoilla.

• Sama avain samalla tekstillä, kanonisoiduilla kielillä ja moottorilla palauttaa olemassa olevan työn vastauksella HTTP 200 ja duplicate: true ilman uutta veloitusta.
• Sama avain eri tekstillä, kielillä tai moottorilla palauttaa 409 idempotency_conflict. Sama avain palauttaa 409 myös, jos käsittelyversio on muuttunut työn luomisen jälkeen. Hae tällöin alkuperäinen työ sen tunnisteella sen sijaan, että lähettäisit sen uudelleen.
• Uusi avain samalla tekstillä, kanonisoiduilla kielillä ja moottorilla palauttaa olemassa olevan työn vastauksella HTTP 200 ja duplicate: true ilman uutta käsittelyveloitusta, jos samansisältöinen ja nykyistä käsittelyversiota käyttävä työ on jonossa, käynnissä, valmistunut tai odottaa maksua. Uudelleenkäytetty maksua odottava työ on edelleen maksettava. Epäonnistuneita töitä ei käytetä uudelleen: uusi työ luodaan ja veloitetaan sen valmistuessa.

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'

Uusi työ palauttaa HTTP 202. Esimerkkitekstissä on 57 koodipistettä, joten hinnalla $5 miljoonaa koodipistettä kohti sen hinta on $0.000285. Lyhennetty vastaus (tunniste on esimerkki):

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

Lähetys voi palauttaa myös 402 insufficient_balance, kun ennakkomaksusaldo ei riitä työn ja muiden keskeneräisten töidesi kattamiseen, ja 429 translation_queue_full, kun tililläsi tai palvelussa on liikaa keskeneräisiä töitä. Se palauttaa 503 näissä tapauksissa:

• paid_translation_not_enabled, kun maksullinen käännös on poistettu käytöstä.
• translation_unavailable tehostetulle pyynnölle, kun tehostettu käännös ei ole käytettävissä.
• translation_pricing_unavailable, kun valitulle moottorille ei ole määritetty hintaa.

Yritä 429- ja 503-vastausten jälkeen myöhemmin uudelleen samalla avaimella.

Valitse laatu

Pitkä teksti käsitellään pienemmissä osissa ja yhdistetään uudelleen. Rivinvaihdot ja välit voivat muuttua, ja lauseen konteksti voi kadota käsittelyrajan kohdalla. Säilytä alkuperäinen teksti ja tarkista koottu tulos. Vakiokäännös käyttää alueellisen tunnisteen peruskieltä; tunnisteen hyväksyminen ja tallentaminen ei takaa alueellista sanamuotoa.

Vakiokäännös suoritetaan CPU-työprosesseissa. Tehostettu käännös lähettää tekstin määritettyyn ulkoiseen tekoälypalveluun. Myös sen tulos on tarkistettava; palvelu ei takaa, että yksi moottori olisi tarkempi jokaiselle kieliparille tai tekstityypille.

Vakiokäännös on luonnos, jonka laatu ja käsittelyaika vaihtelevat kieliparin mukaan. Tehostettu käännös on tarkoitettu tekstiin, jossa konteksti on tärkeä, mutta myös siitä on tarkistettava tärkeät nimet, numerot, kieltomuodot ja sitoumukset. Kumpikaan vaihtoehto ei korjaa alkuperäisessä litteroinnissa jo olevia virheitä, joten säilytä alkuperäinen vertailua varten.

Käytä GET /v3/translate samalla API-palvelimella tarkistaaksesi nykyisen saatavuuden, tuetut vakiokielet ja määritetyt hinnat. Vakiopyyntö, jonka lähde- tai kohdeperuskieli ei ole luettelossa cpuLanguages, palauttaa 422 translation_language_pair_unavailable. Kun source_language on annettu ja sillä on sama peruskieli kuin kohteella, pyyntö palauttaa 409 translation_same_language työn luomisen sijasta. Tehostettu käännös otetaan käyttöön erikseen: kun se ei ole käytettävissä, tehostetut lähetykset ja arviot palauttavat 503.

Pyydä ensin arvio

Palvelimella api.multi.tel lähetä sama JSON-runko osoitteeseen POST /v3/translate/estimate. Idempotenssiavainta ei tarvita. Arvio käyttää samaa validointia, mukaan lukien 422- ja 409-tarkistukset, mutta ei luo työtä, käännä tekstiä, varaa varoja, tarkista saldoasi eikä veloita tiliäsi. Se palauttaa HTTP 200 ja kentät estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd ja costUsd objektin data sisällä. Yllä olevassa esimerkissä costUsd on 0.000285000 vakiohinnalla. Kun tehostettu käännös ei ole käytettävissä, tehostettu arvio palauttaa 503 service_unavailable. Arviot käyttävät sillä hetkellä määritettyä hintaa. Työn hinta kiinnitetään työn luomishetkellä, ja veloitus käyttää tätä hintaa.

Hae käännös

Uusi lähetys palauttaa HTTP 202, ja olemassa oleva tai uudelleenkäytetty työ palauttaa HTTP 200. Tallenna data.id ja käytä yhteistä työnkulkua. Työobjekti sisältää nämä kentät:

• id, status, engine, sourceLocale ja targetLocale.
• sourceCharacters, costUsd, costIsEstimate ja pricePerMillionCharactersUsd.
• progress ja createdAt.
• modelVersion, läpinäkymätön käsittelyversion merkkijono.
• duplicate uudelleenkäytettyjen töiden vastauksissa.
• failureCode epäonnistuneille töille: translation_failed, translation_timeout, input_failed tai worker_lease_lost.

Epäonnistuneen työn costUsd on nolla.

Valmistunut työ sisältää objektin data.result, jossa on sourceLocale (tyhjä, jos lähdekieltä ei annettu), targetLocale, käännetty text (segmenttitekstit yhdistettyinä rivinvaihdoilla) ja segments. Tämän API:n kautta lähetetylle tekstille segments sisältää yhden alkion, jossa on käännetty text ja kohdekielen language. Maksua odottavien töiden tulokset pidätetään maksamiseen asti.

api.multitel.net-palvelimen käyttö

Yhteensopivuuspäätepiste POST https://api.multitel.net/v3/translate hyväksyy samat JSON-kentät ja saman Idempotency-Key-otsakkeen. Jos otsake puuttuu, se hyväksyy myös idempotency_key-merkkijonon JSON-rungossa. Kaikki muut lisäkentät hylätään vastauksella 400 unsupported_translation_option. Tällä palvelimella raakarunko voi olla enintään 256,000 tavua, ja yli 20,000 koodipisteen teksti palauttaa 413 translation_too_large vastauksen 400 sijasta. Tyhjä source_language käsitellään pois jätettynä. 429-vastaus sisältää Retry-After: 15. Tämä palvelin palauttaa myös nämä virheet:

• 400 json_body_required, jos runko puuttuu, on virheellistä JSON:ia tai JSON-skalaari. Lähetä JSON-objekti.
• 400 invalid_translation_options, kun text, target_language tai engine puuttuu, on tyhjä tai ei ole merkkijono, tai source_language ei ole merkkijono.
• 400 invalid_translation_text tekstille, joka koostuu vain tyhjemerkeistä.
• 400 invalid_translation_engine tuntemattomalle moottorille.
• 400 idempotency_key_required puuttuvalle, tyhjälle tai liian pitkälle avaimelle tai jos idempotency_key ei ole merkkijono.
• 400 invalid_job virheellisesti muotoillulle työn tunnisteelle.

Tämän palvelimen käännöspalvelun vastaukset käyttävät rakennetta {"status":{"code":HTTP_STATUS},"response":{...}}, jossa status on objekti. Lue työn tunniste kentästä response.id ja valmistunut tulos kentästä response.result. Virheissä koodi on kentässä response.code ilman viestiä tai pyynnön tunnistetta. Todennusvirheet (401) palautetaan palvelimen yleisestä kirjautumistarkistuksesta, ja niiden runko voi olla erilainen, joten tarkista HTTP-tila ennen jäsentämistä. Työt jaetaan ensisijaisen palvelimen kanssa, mutta käytä samaa palvelinta toistuviin kyselyihin, maksamiseen ja käyttöön, jotta jäsentimesi vastaa vastauksen rakennetta. Tämä palvelin hyväksyy samat JSON-kentät myös osoitteessa /v3/translate/estimate ilman idempotenssiavainta, ja arvio on objektissa response.