API til tekstoversættelse

Denne API oversætter tekst som job i en kø med ét målsprog pr. job. Indsend tekst, gem det returnerede job-ID, og hent jobbet, indtil behandlingen er færdig. Send alle anmodninger over HTTPS med legitimationsoplysninger til din konto, enten HTTP Basic-legitimationsoplysninger som vist i eksemplerne eller et API-token som beskrevet under Godkendelse. Opbevar legitimationsoplysninger på din server.

Endpoints

De to API-værter https://api.multi.tel og kompatibilitetsværten https://api.multitel.net deler de samme kontotilknyttede job, idempotensnøgler, grænser og fakturering. De adskiller sig med hensyn til svarstruktur, så brug konsekvent én vært med en parser, der passer til den.

På api.multi.tel er alle stier også tilgængelige med præfikset /v1/translate i stedet for /v3/translate. På api.multitel.net skal du bruge stierne /v3/translate.

Svaret med tjenesteoplysninger angiver enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000), cpuLanguages og ratesNanosPerCharacter. cpuLanguages angiver de grundsprogkoder, der accepteres til standardoversættelse. ratesNanosPerCharacter angiver den konfigurerede pris pr. kodepunkt i kildeteksten for hver motor, i milliarddele af en amerikansk dollar: en værdi på 5000 betyder $5 pr. million kodepunkter. Svaret angiver ikke, om udvidet oversættelse er tilgængelig i øjeblikket; et estimat for udvidet oversættelse returnerer 503, når den ikke er det. Det er gratis at hente oplysningerne.

Oversæt tekst

Send JSON med Content-Type: application/json til POST https://api.multi.tel/v3/translate. Hvert job har ét målsprog, så indsend et separat job for hvert målsprog.

Lokalitetskoder er BCP 47-tags på 2 til 63 bogstaver, cifre og bindestreger. De kanoniseres, så en-us registreres som en-US. Ugyldige tags samt und, mul eller zxx returnerer 400 invalid_translation_language. Tilgængelighed for standardoversættelse kontrolleres efter grundsprog, og nb og nn tæller som no. Et regionalt målsprog som fr-CA accepteres og registreres, men standardresultatet følger grundsproget og afspejler ikke nødvendigvis regionen.

Hold anmodningens body inden for 128 KiB på denne vært. Send tekst som UTF-8 i stedet for at escape hvert ikke-ASCII-tegn som en \u-sekvens, hvilket kan få en anmodning på 20,000 tegn til at overskride grænsen.

Bodyen accepterer kun disse fire felter. Alle andre egenskaber afvises med 400 invalid_translation_request, herunder idempotency_key, ejer-ID’er, flag for gratis behandling og segmentarrays.

Idempotens og genbrug

Hver indsendelse kræver en Idempotency-Key-header på 1 til 190 tegn. Brug ASCII-bogstaver, cifre, -, _, . og :, uden indledende eller afsluttende mellemrum; en manglende nøgle eller en nøgle på 191 tegn eller mere afvises med 400. Nøgler er afgrænset til din konto og til oversættelse på tværs af begge værter og alle kontoens legitimationsoplysninger.

• Den samme nøgle med samme tekst, kanoniserede sprog og motor returnerer det eksisterende job med HTTP 200 og duplicate: true, uden en ny opkrævning.
• Den samme nøgle med en anden tekst, andre sprog eller en anden motor returnerer 409 idempotency_conflict. Den samme nøgle returnerer også 409, hvis behandlingsversionen er ændret, siden jobbet blev oprettet. Hent i så fald det oprindelige job via dets ID i stedet for at indsende det igen.
• En ny nøgle med samme tekst, kanoniserede sprog og motor returnerer det eksisterende job med HTTP 200 og duplicate: true, uden en ny behandlingsopkrævning, hvis der findes et job med dette indhold og den aktuelle behandlingsversion, som er i kø, kører, er fuldført eller afventer betaling. Et genbrugt job, der afventer betaling, skal stadig betales. Mislykkede job genbruges ikke: der oprettes et nyt job, som faktureres, når det fuldfø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'

Et nyt job returnerer HTTP 202. Eksempelteksten har 57 kodepunkter, så ved $5 pr. 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 indsendelse kan også returnere 402 insufficient_balance når en forudbetalt saldo ikke kan dække jobbet sammen med dine øvrige uafsluttede job, og 429 translation_queue_full når din konto eller tjenesten har for mange uafsluttede job. Den returnerer 503 i disse tilfælde:

• paid_translation_not_enabled mens betalt oversættelse er deaktiveret.
• translation_unavailable for en anmodning om udvidet oversættelse, mens udvidet oversættelse er utilgængelig.
• translation_pricing_unavailable mens den valgte motor ikke har en konfigureret takst.

Prøv igen senere efter svar med 429 og 503, og brug den samme nøgle.

Vælg kvaliteten

Lang tekst behandles i mindre dele og samles igen. Linjeskift og mellemrum kan ændre sig, og en sætning kan miste kontekst ved en grænse mellem behandlingsdele. Behold originalteksten, og gennemgå det samlede resultat. Standardoversættelse bruger grundsproget i et regionalt tag; at et tag accepteres og registreres, garanterer ikke regional ordlyd.

Standardoversættelse kører på CPU-baserede arbejdsprocesser. Udvidet oversættelse sender tekst til den konfigurerede eksterne AI-tjeneste. Resultatet skal stadig gennemgås; tjenesten garanterer ikke, at én motor er mere nøjagtig for alle sprogpar eller teksttyper.

Standardoversættelse er et udkast, hvis kvalitet og behandlingstid varierer efter sprogpar. Udvidet oversættelse er beregnet til tekst, hvor kontekst er vigtig, men kræver stadig kontrol af vigtige navne, tal, negationer og tilsagn. Ingen af mulighederne retter fejl, som allerede findes i en oprindelig transskription, så behold originalen til sammenligning.

Brug GET /v3/translate på den samme API-vært til at kontrollere aktuel tilgængelighed, understøttede standardsprog og konfigurerede takster. En standardanmodning, hvis kilde- eller målgrundsprog ikke findes i cpuLanguages, returnerer 422 translation_language_pair_unavailable. Når source_language er angivet og har samme grundsprog som målsproget, returnerer anmodningen 409 translation_same_language i stedet for at oprette et job. Udvidet oversættelse aktiveres separat: mens den er utilgængelig, returnerer indsendelser og estimater for udvidet oversættelse 503.

Beregn et estimat først

På api.multi.tel skal du sende den samme JSON-body til POST /v3/translate/estimate. Der kræves ingen idempotensnøgle. Et estimat anvender samme validering, inklusive kontrollerne med 422 og 409, men opretter ikke et job, oversætter ikke tekst, reserverer ikke penge, kontrollerer ikke din saldo og opkræver ikke betaling fra din konto. 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 lig med 0.000285000 ved standardtaksten. Mens udvidet oversættelse er utilgængelig, returnerer et estimat for udvidet oversættelse 503 service_unavailable. Estimater bruger den aktuelt konfigurerede takst. Et jobs takst fastlægges, når jobbet oprettes, og opkrævningen bruger denne takst.

Hent oversættelsen

En ny indsendelse returnerer HTTP 202, og et eksisterende eller genbrugt job returnerer HTTP 200. Gem data.id, og brug det fælles jobforløb. Jobobjektet indeholder disse felter:

• id, status, engine, sourceLocale og targetLocale.
• sourceCharacters, costUsd, costIsEstimate og pricePerMillionCharactersUsd.
• progress og createdAt.
• modelVersion, en uigennemsigtig streng, der angiver behandlingsversionen.
• duplicate i svar med genbrugte job.
• failureCode for mislykkede job: translation_failed, translation_timeout, input_failed eller worker_lease_lost.

Et mislykket job viser costUsd som nul.

Et fuldført job har data.result med sourceLocale (tomt, hvis intet kildesprog blev angivet), targetLocale, den oversatte text (segmenttekster samlet med linjeskift) og segments. For tekst indsendt via denne API indeholder segments én post med den oversatte text og målsproget i language. Resultater for job, der afventer betaling, tilbageholdes, indtil betalingen er gennemført.

Brug af api.multitel.net

Kompatibilitetsendpointet POST https://api.multitel.net/v3/translate accepterer de samme JSON-felter og den samme Idempotency-Key-header. Hvis headeren mangler, accepterer den også en streng i idempotency_key i JSON-bodyen. Alle andre ekstra felter afvises med 400 unsupported_translation_option. På denne vært kan den rå body være op til 256,000 byte, og tekst over 20,000 kodepunkter returnerer 413 translation_too_large i stedet for 400. En tom source_language behandles som udeladt. Et 429-svar indeholder Retry-After: 15. Denne vært returnerer også disse fejl:

• 400 json_body_required når bodyen 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, der kun består af blanktegn.
• 400 invalid_translation_engine ved en ukendt motor.
• 400 idempotency_key_required ved en manglende, tom eller for lang nøgle eller en værdi, der ikke er en streng, i idempotency_key.
• 400 invalid_job ved et forkert formateret job-ID.

Svar fra denne værts oversættelsestjeneste bruger svarstrukturen {"status":{"code":HTTP_STATUS},"response":{...}}, hvor status er et objekt. Hent jobbets ID fra response.id og det fuldførte resultat fra response.result. Fejl placerer koden i response.code, uden en meddelelse eller et anmodnings-ID. Godkendelsesfejl (401) returneres af værtens generelle loginkontrol og kan have en anden body, så kontrollér HTTP-status før parsing. Job deles med den primære vært, men brug den samme vært til gentagne forespørgsler, betaling og forbrug, så din parser passer til svarstrukturen. Denne vært accepterer også de samme JSON-felter på /v3/translate/estimate uden en idempotensnøgle, og estimatet findes under response.