API voor tekstvertaling

Deze API vertaalt tekst via taken in een wachtrij, met één doeltaal per taak. Dien tekst in, bewaar de teruggegeven taak-ID en vraag de taak op totdat de verwerking klaar is. Verstuur elk verzoek via HTTPS met inloggegevens voor je account: HTTP Basic-inloggegevens zoals in de voorbeelden, of een API-token zoals beschreven onder Authenticatie. Bewaar inloggegevens op je server.

Endpoints

Twee API-hosts, https://api.multi.tel en de compatibiliteitshost https://api.multitel.net, delen dezelfde accountgebonden taken, idempotentiesleutels, limieten en facturering. Ze verschillen in antwoordstructuur. Gebruik daarom consequent één host met een bijpassende parser.

Op api.multi.tel is elk pad ook beschikbaar met het voorvoegsel /v1/translate in plaats van /v3/translate. Gebruik op api.multitel.net de paden met /v3/translate.

Het antwoord met service-informatie vermeldt enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000), cpuLanguages en ratesNanosPerCharacter. cpuLanguages vermeldt de basistaalcodes die voor standaardvertaling worden geaccepteerd. ratesNanosPerCharacter geeft voor elke vertaalengine de ingestelde prijs per codepunt van de brontekst, in miljardsten van een Amerikaanse dollar: een waarde van 5000 betekent $5 per miljoen codepunten. Het antwoord vermeldt niet of uitgebreide vertaling momenteel beschikbaar is; een schatting voor uitgebreide vertaling geeft 503 terug als dat niet zo is. Het opvragen is gratis.

Tekst vertalen

Verstuur JSON met Content-Type: application/json naar POST https://api.multi.tel/v3/translate. Elke taak heeft één doeltaal, dus dien voor elke doeltaal een afzonderlijke taak in.

Taal- en regiocodes zijn BCP 47-tags van 2 tot 63 letters, cijfers en koppeltekens. Ze worden naar hun canonieke vorm omgezet, dus en-us wordt vastgelegd als en-US. Ongeldige tags en und, mul of zxx geven 400 en invalid_translation_language terug. De beschikbaarheid van standaardvertaling wordt gecontroleerd op basis van de basistaal; nb en nn tellen als no. Een regionale doeltaal zoals fr-CA wordt geaccepteerd en vastgelegd, maar de standaarduitvoer volgt de basistaal en weerspiegelt niet gegarandeerd de regio.

Houd de verzoekbody op deze host binnen 128 KiB. Verstuur tekst als UTF-8 in plaats van elk niet-ASCII-teken te escapen als een \u-reeks, waardoor een verzoek van 20,000 tekens over de limiet kan gaan.

De body accepteert alleen deze vier velden. Elke andere eigenschap wordt geweigerd met 400 en invalid_translation_request, waaronder idempotency_key, eigenaars-ID’s, vlaggen voor gratis verwerking en segmentarrays.

Idempotentie en hergebruik

Elke indiening vereist een Idempotency-Key-header van 1 tot 190 tekens. Gebruik ASCII-letters, cijfers, -, _, . en :, zonder spaties aan het begin of einde; een ontbrekende sleutel of een sleutel van 191 of meer tekens wordt geweigerd met 400. Sleutels gelden voor je account en voor vertaling, over beide hosts en alle inloggegevens van je account heen.

• Dezelfde sleutel met dezelfde tekst, canonieke talen en vertaalengine geeft de bestaande taak terug met HTTP 200 en duplicate: true, zonder nieuwe kosten.
• Dezelfde sleutel met een andere tekst, andere talen of een andere vertaalengine geeft 409 en idempotency_conflict terug. Dezelfde sleutel geeft ook 409 terug als de verwerkingsversie sinds het aanmaken van de taak is veranderd. Vraag in dat geval de oorspronkelijke taak op via de ID in plaats van deze opnieuw in te dienen.
• Een nieuwe sleutel met dezelfde tekst, canonieke talen en vertaalengine geeft de bestaande taak terug met HTTP 200 en duplicate: true, zonder nieuwe verwerkingskosten, als een taak met die inhoud en de huidige verwerkingsversie in de wachtrij staat, wordt uitgevoerd, is voltooid of op betaling wacht. Een hergebruikte taak die op betaling wacht, moet nog steeds worden afgerekend. Mislukte taken worden niet hergebruikt: er wordt een nieuwe taak aangemaakt en bij voltooiing in rekening gebracht.

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'

Een nieuwe taak geeft HTTP 202 terug. De voorbeeldtekst heeft 57 codepunten en kost bij $5 per miljoen codepunten dus $0.000285. Een verkort antwoord (de identificatie is een 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
  }
}

Een indiening kan ook 402 met insufficient_balance teruggeven als het prepaidtegoed niet voldoende is voor de taak samen met je andere openstaande taken, en 429 met translation_queue_full als je account of de service te veel openstaande taken heeft. De service geeft in deze gevallen 503 terug:

• paid_translation_not_enabled als betaalde vertaling is uitgeschakeld.
• translation_unavailable voor een verzoek om uitgebreide vertaling wanneer uitgebreide vertaling niet beschikbaar is.
• translation_pricing_unavailable als voor de gekozen vertaalengine geen tarief is ingesteld.

Probeer na antwoorden met 429 en 503 later opnieuw met dezelfde sleutel.

De kwaliteit kiezen

Lange tekst wordt in kleinere stukken verwerkt en weer samengevoegd. Regeleinden en spaties kunnen veranderen en een zin kan context verliezen over de grens tussen verwerkte stukken. Bewaar de oorspronkelijke tekst en controleer het samengevoegde resultaat. Standaardvertaling gebruikt de basistaal van een regionale tag; het accepteren en vastleggen van een tag garandeert geen regionale formuleringen.

Standaardvertaling wordt uitgevoerd door CPU-workers. Uitgebreide vertaling verstuurt tekst naar de ingestelde externe AI-service. Ook die uitvoer moet worden gecontroleerd; de service garandeert niet dat één vertaalengine voor elk talenpaar of teksttype nauwkeuriger is.

Standaardvertaling levert een concept waarvan de kwaliteit en verwerkingstijd per talenpaar verschillen. Uitgebreide vertaling is bedoeld voor tekst waarbij context belangrijk is, maar vereist nog steeds controle van belangrijke namen, getallen, ontkenningen en toezeggingen. Geen van beide opties herstelt fouten die al in een oorspronkelijk transcript staan. Bewaar daarom het origineel ter vergelijking.

Gebruik GET /v3/translate op dezelfde API-host om de huidige beschikbaarheid, ondersteunde standaardtalen en ingestelde tarieven te controleren. Een standaardverzoek waarvan de basistaal van de bron of het doel niet in cpuLanguages staat, geeft 422 en translation_language_pair_unavailable terug. Wanneer source_language is opgegeven en dezelfde basistaal heeft als het doel, geeft het verzoek 409 en translation_same_language terug in plaats van een taak aan te maken. Uitgebreide vertaling wordt afzonderlijk ingeschakeld: zolang deze niet beschikbaar is, geven indieningen en schattingen voor uitgebreide vertaling 503 terug.

Eerst een schatting opvragen

Verstuur op api.multi.tel dezelfde JSON-body naar POST /v3/translate/estimate. Een idempotentiesleutel is niet nodig. Een schatting voert dezelfde validatie uit, inclusief de controles voor 422 en 409, maar maakt geen taak aan, vertaalt geen tekst, reserveert geen tegoed, controleert je saldo niet en brengt geen kosten in rekening. De schatting geeft HTTP 200 terug met estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd en costUsd onder data. In het bovenstaande voorbeeld is costUsd gelijk aan 0.000285000 bij het standaardtarief. Zolang uitgebreide vertaling niet beschikbaar is, geeft een schatting daarvoor 503 met service_unavailable terug. Schattingen gebruiken het momenteel ingestelde tarief. Het tarief van een taak wordt bij het aanmaken vastgelegd en de kosten worden op dat tarief gebaseerd.

De vertaling opvragen

Een nieuwe indiening geeft HTTP 202 terug en een bestaande of hergebruikte taak geeft HTTP 200 terug. Bewaar data.id en gebruik de gezamenlijke taakworkflow. Het taakobject bevat deze velden:

• id, status, engine, sourceLocale en targetLocale.
• sourceCharacters, costUsd, costIsEstimate en pricePerMillionCharactersUsd.
• progress en createdAt.
• modelVersion, een ondoorzichtige tekenreeks die de verwerkingsversie aanduidt.
• duplicate in antwoorden die een bestaande taak hergebruiken.
• failureCode voor mislukte taken: translation_failed, translation_timeout, input_failed of worker_lease_lost.

Een mislukte taak toont voor costUsd een waarde van nul.

Een voltooide taak bevat data.result met sourceLocale (leeg als geen brontaal is opgegeven), targetLocale, het veld text met de vertaling (segmentteksten verbonden met regeleinden) en segments. Voor tekst die via deze API is ingediend, bevat segments één item met de vertaling in text en de doeltaal in language. Resultaten van taken die op betaling wachten worden pas na afrekening vrijgegeven.

api.multitel.net gebruiken

Het compatibiliteitseindpunt POST https://api.multitel.net/v3/translate accepteert dezelfde JSON-velden en dezelfde Idempotency-Key-header. Als de header ontbreekt, accepteert het ook een tekenreeks idempotency_key in de JSON-body. Elk ander extra veld wordt geweigerd met 400 en unsupported_translation_option. Op deze host mag de ruwe body maximaal 256,000 bytes zijn en geeft tekst van meer dan 20,000 codepunten 413 met translation_too_large terug in plaats van 400. Een lege waarde voor source_language geldt als weggelaten. Een antwoord met 429 bevat Retry-After: 15. Deze host geeft ook de volgende fouten terug:

• 400 json_body_required als de body ontbreekt, ongeldige JSON is of een scalaire JSON-waarde is. Verstuur een JSON-object.
• 400 invalid_translation_options als text, target_language of engine ontbreekt, leeg is of geen tekenreeks is, of als source_language geen tekenreeks is.
• 400 invalid_translation_text bij tekst die uitsluitend uit witruimte bestaat.
• 400 invalid_translation_engine bij een onbekende vertaalengine.
• 400 idempotency_key_required bij een ontbrekende, lege of te lange sleutel, of bij een waarde voor idempotency_key die geen tekenreeks is.
• 400 invalid_job bij een onjuist gevormde taak-ID.

Antwoorden van de vertaalservice op deze host gebruiken de antwoordstructuur {"status":{"code":HTTP_STATUS},"response":{...}}, waarbij status een object is. Lees de taak-ID uit response.id en het voltooide resultaat uit response.result. Bij fouten staat de code in response.code, zonder bericht of verzoek-ID. Authenticatiefouten (401) komen van de algemene aanmeldcontrole van de host en kunnen een andere body hebben. Controleer daarom de HTTP-status voordat je het antwoord parseert. Taken worden gedeeld met de primaire host, maar gebruik dezelfde host voor het opvragen, afrekenen en opvragen van gebruik, zodat je parser bij de antwoordstructuur past. Deze host accepteert dezelfde JSON-velden ook op /v3/translate/estimate zonder idempotentiesleutel en de schatting staat onder response.