API for tekstoversettelse

Dette API-et oversetter tekst som jobber i en kø, med ett målspråk per jobb. Send inn tekst, ta vare på den returnerte jobb-ID-en, og hent jobben til behandlingen er ferdig. Send alle forespørsler over HTTPS med påloggingsopplysninger for kontoen din, enten HTTP Basic-opplysninger som vist i eksemplene eller et API-token som beskrevet under Autentisering. Oppbevar påloggingsopplysninger på serveren din.

Endepunkter

De to API-vertene https://api.multi.tel og kompatibilitetsverten https://api.multitel.net deler de samme kontoavgrensede jobbene, idempotensnøklene, grensene og faktureringen. De bruker ulik svarstruktur, så bruk én vert konsekvent med en parser som passer til den.

På api.multi.tel er alle stier også tilgjengelige med prefikset /v1/translate i stedet for /v3/translate. På api.multitel.net bruker du stiene /v3/translate.

Svaret med tjenesteinformasjon oppgir enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000), cpuLanguages og ratesNanosPerCharacter. cpuLanguages viser grunnspråkkodene som godtas for standardoversettelse. ratesNanosPerCharacter oppgir den konfigurerte prisen per kodepunkt i kildeteksten for hver motor, i milliarddeler av en amerikansk dollar: en verdi på 5000 betyr $5 per million kodepunkter. Svaret oppgir ikke om utvidet oversettelse er tilgjengelig for øyeblikket; et estimat for utvidet oversettelse returnerer 503 når den ikke er det. Det er gratis å hente informasjonen.

Oversett tekst

Send JSON med Content-Type: application/json til POST https://api.multi.tel/v3/translate. Hver jobb har ett målspråk, så send inn en separat jobb for hvert målspråk.

Lokalitetskoder er BCP 47-tagger på 2 til 63 bokstaver, sifre og bindestreker. De kanoniseres, slik at en-us registreres som en-US. Ugyldige tagger, samt und, mul eller zxx, returnerer 400 invalid_translation_language. Tilgjengelighet for standardoversettelse kontrolleres etter grunnspråk, og nb og nn regnes som no. Et regionalt målspråk som fr-CA godtas og registreres, men standardresultatet følger grunnspråket og gjenspeiler ikke nødvendigvis regionen.

Hold forespørselskroppen innenfor 128 KiB på denne verten. Send tekst som UTF-8 i stedet for å escape hvert ikke-ASCII-tegn som en \u-sekvens, noe som kan få en forespørsel på 20,000 tegn til å overskride grensen.

Kroppen godtar bare disse fire feltene. Alle andre egenskaper avvises med 400 invalid_translation_request, inkludert idempotency_key, eier-ID-er, flagg for gratis behandling og segmentarrayer.

Idempotens og gjenbruk

Hver innsending krever en Idempotency-Key-header på 1 til 190 tegn. Bruk ASCII-bokstaver, sifre, -, _, . og :, uten innledende eller avsluttende mellomrom; en manglende nøkkel eller en nøkkel på 191 tegn eller mer avvises med 400. Nøkler er avgrenset til kontoen din og til oversettelse, på tvers av begge verter og alle kontoens påloggingsopplysninger.

• Den samme nøkkelen med samme tekst, kanoniserte språk og motor returnerer den eksisterende jobben med HTTP 200 og duplicate: true, uten en ny belastning.
• Den samme nøkkelen med en annen tekst, andre språk eller en annen motor returnerer 409 idempotency_conflict. Den samme nøkkelen returnerer også 409 hvis behandlingsversjonen er endret siden jobben ble opprettet. Hent i så fall den opprinnelige jobben via ID-en i stedet for å sende den inn på nytt.
• En ny nøkkel med samme tekst, kanoniserte språk og motor returnerer den eksisterende jobben med HTTP 200 og duplicate: true, uten en ny belastning for behandling, hvis en jobb med dette innholdet og den gjeldende behandlingsversjonen står i kø, kjører, er fullført eller venter på betaling. En gjenbrukt jobb som venter på betaling, må fortsatt betales. Mislykkede jobber gjenbrukes ikke: en ny jobb opprettes og faktureres når den fullføres.

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'

En ny jobb returnerer HTTP 202. Eksempelteksten har 57 kodepunkter, så ved $5 per million kodepunkter koster den $0.000285. Et forkortet svar (identifikatoren er et eksempel):

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

En innsending kan også returnere 402 insufficient_balance når en forhåndsbetalt saldo ikke kan dekke jobben sammen med de andre utestående jobbene dine, og 429 translation_queue_full når kontoen din eller tjenesten har for mange utestående jobber. Den returnerer 503 i disse tilfellene:

• paid_translation_not_enabled mens betalt oversettelse er deaktivert.
• translation_unavailable for en forespørsel om utvidet oversettelse mens utvidet oversettelse er utilgjengelig.
• translation_pricing_unavailable mens den valgte motoren ikke har en konfigurert sats.

Prøv igjen senere etter svar med 429 og 503, og bruk den samme nøkkelen.

Velg kvalitet

Lang tekst behandles i mindre deler og settes sammen igjen. Linjeskift og mellomrom kan endres, og en setning kan miste kontekst ved en grense mellom behandlingsdeler. Behold originalteksten, og gjennomgå det samlede resultatet. Standardoversettelse bruker grunnspråket i en regional tagg; at en tagg godtas og registreres, garanterer ikke regional ordlyd.

Standardoversettelse kjører på CPU-baserte arbeidsprosesser. Utvidet oversettelse sender tekst til den konfigurerte eksterne KI-tjenesten. Resultatet må fortsatt gjennomgås; tjenesten garanterer ikke at én motor er mer nøyaktig for alle språkpar eller teksttyper.

Standardoversettelse er et utkast der kvalitet og behandlingstid varierer etter språkpar. Utvidet oversettelse er beregnet på tekst der kontekst er viktig, men krever fortsatt kontroll av viktige navn, tall, negasjoner og forpliktelser. Ingen av alternativene retter feil som allerede finnes i en opprinnelig transkripsjon, så behold originalen til sammenligning.

Bruk GET /v3/translate på den samme API-verten for å sjekke gjeldende tilgjengelighet, støttede standardspråk og konfigurerte satser. En standardforespørsel der kilde- eller målgrunnspråket ikke er i cpuLanguages, returnerer 422 translation_language_pair_unavailable. Når source_language er oppgitt og har samme grunnspråk som målspråket, returnerer forespørselen 409 translation_same_language i stedet for å opprette en jobb. Utvidet oversettelse aktiveres separat: mens den er utilgjengelig, returnerer innsendelser og estimater for utvidet oversettelse 503.

Beregn et estimat først

På api.multi.tel sender du den samme JSON-kroppen til POST /v3/translate/estimate. Ingen idempotensnøkkel er nødvendig. Et estimat bruker samme validering, inkludert kontrollene med 422 og 409, men oppretter ikke en jobb, oversetter ikke tekst, reserverer ikke penger, kontrollerer ikke saldoen din og belaster ikke kontoen din. Det returnerer HTTP 200 med estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd og costUsd under data. For eksemplet ovenfor er costUsd lik 0.000285000 ved standardsatsen. Mens utvidet oversettelse er utilgjengelig, returnerer et estimat for utvidet oversettelse 503 service_unavailable. Estimater bruker den gjeldende konfigurerte satsen. Satsen for en jobb fastsettes når jobben opprettes, og belastningen bruker denne satsen.

Hent oversettelsen

En ny innsending returnerer HTTP 202, og en eksisterende eller gjenbrukt jobb returnerer HTTP 200. Ta vare på data.id og bruk det felles jobbforløpet. Jobbobjektet inneholder disse feltene:

• id, status, engine, sourceLocale og targetLocale.
• sourceCharacters, costUsd, costIsEstimate og pricePerMillionCharactersUsd.
• progress og createdAt.
• modelVersion, en ugjennomsiktig streng som angir behandlingsversjonen.
• duplicate i svar med gjenbrukte jobber.
• failureCode for mislykkede jobber: translation_failed, translation_timeout, input_failed eller worker_lease_lost.

En mislykket jobb viser costUsd som null.

En fullført jobb har data.result med sourceLocale (tomt hvis ikke noe kildespråk ble oppgitt), targetLocale, oversatt tekst i text (segmenttekster satt sammen med linjeskift), og segments. For tekst sendt inn gjennom dette API-et inneholder segments én oppføring med oversatt tekst i text og målspråket i language. Resultater fra jobber som venter på betaling, holdes tilbake til betalingen er gjennomført.

Bruk av api.multitel.net

Kompatibilitetsendepunktet POST https://api.multitel.net/v3/translate godtar de samme JSON-feltene og den samme Idempotency-Key-headeren. Hvis headeren mangler, godtar den også en streng i idempotency_key i JSON-kroppen. Alle andre ekstra felter avvises med 400 unsupported_translation_option. På denne verten kan den rå kroppen være opptil 256,000 byte, og tekst over 20,000 kodepunkter returnerer 413 translation_too_large i stedet for 400. En tom source_language behandles som utelatt. Et 429-svar inkluderer Retry-After: 15. Denne verten returnerer også disse feilene:

• 400 json_body_required når kroppen mangler, er ugyldig JSON eller en JSON-skalar. Send et JSON-objekt.
• 400 invalid_translation_options når text, target_language eller engine mangler, er tom eller ikke er en streng, eller source_language ikke er en streng.
• 400 invalid_translation_text ved tekst som bare består av blanktegn.
• 400 invalid_translation_engine ved en ukjent motor.
• 400 idempotency_key_required ved en manglende, tom eller for lang nøkkel, eller en verdi som ikke er en streng, i idempotency_key.
• 400 invalid_job ved en feilformatert jobb-ID.

Svar fra denne vertens oversettelsestjeneste bruker svarstrukturen {"status":{"code":HTTP_STATUS},"response":{...}}, der status er et objekt. Hent jobb-ID-en fra response.id og det fullførte resultatet fra response.result. Ved feil legges koden i response.code, uten en melding eller forespørsels-ID. Autentiseringsfeil (401) returneres av vertens generelle påloggingskontroll og kan ha en annen kropp, så kontroller HTTP-statusen før parsing. Jobber deles med primærverten, men bruk samme vert for gjentatte forespørsler, betaling og forbruk, slik at parseren passer til svarstrukturen. Denne verten godtar også de samme JSON-feltene på /v3/translate/estimate uten en idempotensnøkkel, og estimatet ligger under response.