API för textöversättning

Detta API översätter text som köade jobb, med ett målspråk per jobb. Skicka in text, spara det returnerade jobb-ID:t och hämta jobbet tills bearbetningen är klar. Skicka varje begäran via HTTPS med inloggningsuppgifter för ditt konto, antingen HTTP Basic-uppgifter som i exemplen eller en API-token, enligt avsnittet Autentisering. Behåll inloggningsuppgifterna på din server.

Slutpunkter

De två API-värdarna, https://api.multi.tel och kompatibilitetsvärden https://api.multitel.net, delar samma kontobundna jobb, idempotensnycklar, gränser och avgifter. De skiljer sig åt i svarsstruktur, så använd samma värd konsekvent med en matchande svarstolk.

På api.multi.tel finns varje sökväg även med prefixet /v1/translate i stället för /v3/translate. På api.multitel.net använder du sökvägarna med /v3/translate.

Svaret med tjänsteinformation anger enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000), cpuLanguages och ratesNanosPerCharacter. cpuLanguages listar de grundspråkskoder som godtas för standardöversättning. ratesNanosPerCharacter anger det konfigurerade priset per kodpunkt i källtexten för varje motor, i miljarddelar av en amerikansk dollar: värdet 5000 innebär $5 per miljon kodpunkter. Svaret anger inte om förbättrad översättning är tillgänglig för närvarande; en uppskattning för förbättrad översättning returnerar 503 om den inte är det. Det är gratis att läsa informationen.

Översätt text

Skicka JSON med Content-Type: application/json till POST https://api.multi.tel/v3/translate. Varje jobb har ett målspråk, så skicka in ett separat jobb för varje målspråk.

Språkkoderna är BCP 47-taggar med 2 till 63 bokstäver, siffror och bindestreck. De omvandlas till kanonisk form, så en-us registreras som en-US. Ogiltiga taggar samt und, mul eller zxx returnerar 400 invalid_translation_language. Tillgängligheten för standardöversättning kontrolleras efter grundspråk, och nb och nn räknas som no. Ett regionalt mål som fr-CA godtas och registreras, men standardresultatet följer grundspråket och garanteras inte återge den regionala varianten.

Håll begärandekroppen inom 128 KiB på den här värden. Skicka text som UTF-8 i stället för att skriva varje tecken utanför ASCII som en \u-sekvens, vilket kan göra att en begäran med 20,000 tecken överskrider gränsen.

Kroppen godtar endast dessa fyra fält. Alla andra egenskaper avvisas med 400 invalid_translation_request, inklusive idempotency_key, ägar-ID:n, flaggor för kostnadsfri bearbetning och segmentarrayer.

Idempotens och återanvändning

Varje inskickning kräver HTTP-huvudet Idempotency-Key med 1 till 190 tecken. Använd ASCII-bokstäver, siffror, -, _, . och :, utan inledande eller avslutande blanktecken; en nyckel som saknas eller har 191 eller fler tecken avvisas med 400. Nycklarna är knutna till ditt konto och till översättning på båda värdarna och för alla kontots inloggningsuppgifter.

• Samma nyckel med samma text, språk i kanonisk form och motor returnerar det befintliga jobbet med HTTP 200 och duplicate: true, utan ytterligare avgift.
• Samma nyckel med annan text, andra språk eller en annan motor returnerar 409 idempotency_conflict. Samma nyckel returnerar också 409 om bearbetningsversionen har ändrats sedan dess jobb skapades. Hämta i så fall det ursprungliga jobbet med dess ID i stället för att skicka in det igen.
• En ny nyckel med samma text, språk i kanonisk form och motor returnerar det befintliga jobbet med HTTP 200 och duplicate: true, utan ny bearbetningsavgift, om ett jobb med detta innehåll och den aktuella bearbetningsversionen köar, körs, är klart eller väntar på betalning. Ett återanvänt jobb som väntar på betalning måste fortfarande betalas. Misslyckade jobb återanvänds inte: ett nytt jobb skapas och debiteras när det slutförs.

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'

Ett nytt jobb returnerar HTTP 202. Exempeltexten har 57 kodpunkter, så med ett pris på $5 per miljon kodpunkter kostar den $0.000285. Ett förkortat svar (identifieraren är ett exempel):

{
  "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 inskickning kan också returnera 402 insufficient_balance när ett förbetalt saldo inte täcker jobbet tillsammans med dina andra utestående jobb och 429 translation_queue_full när ditt konto eller tjänsten har för många utestående jobb. Den returnerar 503 i följande fall:

• paid_translation_not_enabled när betald översättning är avstängd.
• translation_unavailable för en begäran om förbättrad översättning när förbättrad översättning inte är tillgänglig.
• translation_pricing_unavailable när den valda motorn saknar ett konfigurerat pris.

Försök igen senare med samma nyckel efter svar med 429 och 503.

Välj kvalitet

Lång text bearbetas i mindre delar och sammanfogas igen. Radbrytningar och mellanrum kan ändras, och en mening kan förlora sitt sammanhang vid en gräns mellan delar. Spara originaltexten och granska det sammanfogade resultatet. Standardöversättning använder grundspråket i en regional tagg; att en tagg godtas och registreras garanterar inte regionala formuleringar.

Standardöversättning körs av CPU-baserade arbetsprocesser. Förbättrad översättning skickar text till den konfigurerade externa AI-tjänsten. Resultatet behöver fortfarande granskas; tjänsten garanterar inte att en motor är mer korrekt för varje språkpar eller typ av text.

Standardöversättning är ett utkast vars kvalitet och bearbetningstid varierar mellan språkpar. Förbättrad översättning är avsedd för text där sammanhanget är viktigt, men viktiga namn, tal, negationer och utfästelser måste fortfarande granskas. Inget av alternativen rättar fel som redan finns i en ursprunglig transkription, så spara originalet för jämförelse.

Använd GET /v3/translate på samma API-värd för att kontrollera aktuell tillgänglighet, standardspråk som stöds och konfigurerade priser. En standardbegäran där källspråkets eller målspråkets grundspråk inte finns i cpuLanguages returnerar 422 translation_language_pair_unavailable. När source_language anges och har samma grundspråk som målet returnerar begäran 409 translation_same_language i stället för att skapa ett jobb. Förbättrad översättning aktiveras separat: när den är otillgänglig returnerar inskickningar och uppskattningar för förbättrad översättning 503.

Beräkna en uppskattning först

På api.multi.tel skickar du samma JSON-kropp till POST /v3/translate/estimate. Ingen idempotensnyckel krävs. En uppskattning tillämpar samma validering, inklusive kontrollerna för 422 och 409, men skapar inget jobb, översätter ingen text, reserverar inga medel, kontrollerar inte ditt saldo och debiterar inte ditt konto. Den returnerar HTTP 200 med estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd och costUsd under data. För exemplet ovan är costUsd lika med 0.000285000 med standardpriset. När förbättrad översättning inte är tillgänglig returnerar en uppskattning för förbättrad översättning 503 service_unavailable. Uppskattningar använder det aktuella konfigurerade priset. Priset för ett jobb fastställs när jobbet skapas, och avgiften beräknas med det priset.

Hämta översättningen

En ny inskickning returnerar HTTP 202 och ett befintligt eller återanvänt jobb returnerar HTTP 200. Spara data.id och använd det gemensamma jobbflödet. Jobbobjektet innehåller följande fält:

• id, status, engine, sourceLocale och targetLocale.
• sourceCharacters, costUsd, costIsEstimate och pricePerMillionCharactersUsd.
• progress och createdAt.
• modelVersion, en ogenomskinlig versionssträng för bearbetningen.
• duplicate i svar med återanvända jobb.
• failureCode för misslyckade jobb: translation_failed, translation_timeout, input_failed eller worker_lease_lost.

Ett misslyckat jobb har costUsd lika med noll.

Ett slutfört jobb har data.result med sourceLocale (tomt om inget källspråk angavs), targetLocale, den översatta texten i text (segmenttexter sammanfogade med radbrytningar) och segments. För text som skickas in via detta API innehåller segments en post med den översatta texten i text och målspråket i language. Resultat för jobb som väntar på betalning lämnas inte ut förrän betalningen är klar.

Använda api.multitel.net

Kompatibilitetsslutpunkten POST https://api.multitel.net/v3/translate tar emot samma JSON-fält och samma HTTP-huvud Idempotency-Key. Om huvudet saknas godtar den även en idempotency_key-sträng i JSON-kroppen. Alla andra extra fält avvisas med 400 unsupported_translation_option. På den här värden får den råa kroppen vara högst 256,000 byte, och text över 20,000 kodpunkter returnerar 413 translation_too_large i stället för 400. Ett tomt source_language behandlas som utelämnat. Ett 429-svar innehåller Retry-After: 15. Värden returnerar även följande fel:

• 400 json_body_required när kroppen saknas, är ogiltig JSON eller är ett skalärt JSON-värde. Skicka ett JSON-objekt.
• 400 invalid_translation_options när text, target_language eller engine saknas, är tomt eller inte är en sträng, eller när source_language inte är en sträng.
• 400 invalid_translation_text för text som enbart består av blanktecken.
• 400 invalid_translation_engine för en okänd motor.
• 400 idempotency_key_required när nyckeln saknas, är tom eller för lång, eller när följande värde inte är en sträng: idempotency_key.
• 400 invalid_job när jobb-ID:t har fel format.

Svar från värdens översättningstjänst använder strukturen {"status":{"code":HTTP_STATUS},"response":{...}}, där status är ett objekt. Läs jobb-ID:t från response.id och det slutförda resultatet från response.result. Vid fel finns koden i response.code, utan meddelande eller begärande-ID. Autentiseringsfel (401) returneras av värdens allmänna inloggningskontroll och kan ha en annan kropp, så kontrollera HTTP-statusen innan svaret tolkas. Jobben delas med den primära värden, men använd samma värd för statuskontroller, betalning och användning så att svarstolken matchar strukturen. Värden tar även emot samma JSON-fält på /v3/translate/estimate utan idempotensnyckel, och uppskattningen finns under response.