Szövegfordítási API

Ez az API szöveget fordít sorba állított feladatokként, feladatonként egy célnyelvre. Küldjön be szöveget, őrizze meg a visszakapott feladatazonosítót, és kérdezze le a feladatot a feldolgozás befejezéséig. Minden kérést HTTPS-en, a fiókjához tartozó hitelesítő adatokkal küldjön: a példákban látható HTTP Basic-hitelesítéssel vagy API-tokennel, a következő szakasz szerint: Hitelesítés. Tartsa a hitelesítő adatokat a szerverén.

Végpontok

A két API-hoszt, https://api.multi.tel és a kompatibilitási hoszt, https://api.multitel.net, ugyanazokat a fiókhoz tartozó feladatokat, idempotenciakulcsokat, korlátokat és számlázást használja. A válaszok borítékformátuma eltér, ezért következetesen ugyanazt a hosztot használja a hozzá illő válaszfeldolgozóval.

A(z) api.multi.tel hoszton minden elérési út a következő előtaggal is használható: /v1/translate a következő helyett: /v3/translate. A(z) api.multitel.net hoszton ezeket az elérési utakat használja: /v3/translate.

A szolgáltatásadatokat tartalmazó válasz a következőket adja meg: enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000), cpuLanguages és ratesNanosPerCharacter. cpuLanguages felsorolja a standard fordításhoz elfogadott alapnyelvkódokat. A(z) ratesNanosPerCharacter megadja az egyes motorokhoz beállított, forrásszövegbeli kódpontonkénti árat az amerikai dollár milliárdod részében: az 5000 érték millió kódpontonként $5 díjat jelent. A válasz nem jelzi, hogy jelenleg elérhető-e az emelt szintű fordítás; ha nem érhető el, az emelt szintű becslés 503 választ ad. A lekérdezés ingyenes.

Szöveg fordítása

Küldjön JSON-t a(z) Content-Type: application/json fejléc használatával ide: POST https://api.multi.tel/v3/translate. Minden feladatnak egy célnyelve van, ezért minden célnyelvhez külön feladatot küldjön be.

A nyelvi-területi kódok BCP 47 címkék, amelyek 2 és 63 közötti betűből, számjegyből és kötőjelből állnak. Kanonikus alakra hozzuk őket, így a(z) en-us a következőként kerül tárolásra: en-US. Az érvénytelen címkék, valamint a(z) und, mul vagy zxx érték 400 invalid_translation_language hibát adnak. A standard fordítás elérhetőségét az alapnyelv szerint ellenőrizzük, és a(z) nb és nn a következőnek számít: no. Az olyan regionális célnyelvi címkét, mint a(z) fr-CA, a szolgáltatás elfogadja és tárolja, de a standard eredmény az alapnyelvet követi, és nem garantált, hogy tükrözi a régió sajátosságait.

Ezen a hoszton a kérés törzse legfeljebb 128 KiB legyen. A szöveget UTF-8-ként küldje, ne alakítson minden nem ASCII-karaktert \u escape-szekvenciává, mert ez egy 20,000 karakteres kérésnél a korlát túllépését okozhatja.

A törzs csak ezt a négy mezőt fogadja el. Minden más tulajdonságot 400 invalid_translation_request hibával utasít el a szolgáltatás, beleértve a(z) idempotency_key tulajdonságot, a tulajdonosazonosítókat, az ingyenes feldolgozás jelzőit és a szegmenstömböket.

Idempotencia és újrafelhasználás

Minden beküldéshez szükséges egy Idempotency-Key fejléc 1 és 190 karakter közötti értékkel. ASCII-betűket, számjegyeket, valamint -, _, . és : karaktereket használjon, kezdő és záró szóköz nélkül; a hiányzó vagy legalább 191 karakteres kulcsot 400 válasszal utasítja el a szolgáltatás. A kulcsok az Ön fiókjához és a fordításhoz tartoznak, mindkét hoszton és a fiók összes hitelesítő adatára kiterjedően.

• Ugyanaz a kulcs ugyanazzal a szöveggel, kanonikus nyelvekkel és motorral a meglévő feladatot adja vissza HTTP 200 válasszal és duplicate: true jelzéssel, újabb díj nélkül.
• Ugyanaz a kulcs eltérő szöveggel, nyelvekkel vagy motorral 409 idempotency_conflict hibát ad. Ugyanaz a kulcs akkor is 409 választ ad, ha a feldolgozási verzió a feladat létrehozása óta megváltozott. Ilyenkor az eredeti feladatot az azonosítója alapján kérdezze le az újraküldés helyett.
• Új kulcs ugyanazzal a szöveggel, kanonikus nyelvekkel és motorral a meglévő feladatot adja vissza HTTP 200 válasszal és duplicate: true jelzéssel, új feldolgozási díj nélkül, ha az adott tartalmú és jelenlegi feldolgozási verziójú feladat sorban áll, fut, befejeződött vagy fizetésre vár. Az újrafelhasznált, fizetésre váró feladat díját továbbra is rendezni kell. A sikertelen feladatokat nem használjuk újra: új feladat jön létre, amelynek befejezésekor díjat számítunk fel.

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'

Az új feladat HTTP 202 választ ad. A példaszöveg 57 kódpontból áll, így millió kódpontonként $5 árral számolva $0.000285 a díja. Rövidített válasz (az azonosító példa):

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

A beküldés 402 insufficient_balance hibát is adhat, ha a feltöltött egyenleg nem fedezi a feladatot a többi függőben lévő feladattal együtt, valamint 429 translation_queue_full hibát, ha a fiókban vagy a szolgáltatásban túl sok függőben lévő feladat van. Az alábbi esetekben 503 választ ad:

• paid_translation_not_enabled amíg a fizetős fordítás le van tiltva.
• translation_unavailable emelt szintű kérés esetén, amíg az emelt szintű fordítás nem érhető el.
• translation_pricing_unavailable amíg a választott motorhoz nincs díjszabás beállítva.

429 és 503 válasz esetén később, ugyanazzal a kulccsal próbálkozzon újra.

A minőség kiválasztása

A hosszú szöveget kisebb részekben dolgozzuk fel, majd újra összefűzzük. A sortörések és térközök megváltozhatnak, és a feldolgozási határokon átívelő mondat elveszítheti a szövegkörnyezetét. Őrizze meg az eredeti szöveget, és ellenőrizze az összeállított eredményt. A standard fordítás a regionális címke alapnyelvét használja; a címke elfogadása és tárolása nem garantál régiónak megfelelő szóhasználatot.

A standard fordítás CPU-alapú feldolgozókon fut. Az emelt szintű fordítás a beállított külső AI-szolgáltatásnak küldi a szöveget. Az eredménye továbbra is ellenőrzést igényel; a szolgáltatás nem garantálja, hogy az egyik motor minden nyelvpárnál vagy szövegtípusnál pontosabb.

A standard fordítás vázlat, amelynek minősége és feldolgozási ideje nyelvpáronként változik. Az emelt szintű fordítás olyan szövegekhez készült, ahol fontos a szövegkörnyezet, de a fontos neveket, számokat, tagadásokat és vállalásokat ebben is ellenőrizni kell. Egyik lehetőség sem javítja ki az eredeti átiratban már meglévő hibákat, ezért tartsa meg az eredetit az összehasonlításhoz.

Használja a(z) GET /v3/translate végpontot ugyanazon az API-hoszton a jelenlegi elérhetőség, a standard módban támogatott nyelvek és a beállított díjak ellenőrzéséhez. Ha egy standard kérés forrás- vagy célnyelvének alapnyelve nem szerepel a(z) cpuLanguages listában, a válasz 422 translation_language_pair_unavailable. Ha a(z) source_language meg van adva, és alapnyelve megegyezik a célnyelv alapnyelvével, a kérés 409 translation_same_language hibát ad feladat létrehozása helyett. Az emelt szintű fordítás külön engedélyezhető: amíg nem érhető el, az emelt szintű beküldések és becslések 503 választ adnak.

Először kérjen becslést

A(z) api.multi.tel hoszton ugyanazt a JSON-törzset küldje ide: POST /v3/translate/estimate. Idempotenciakulcs nem szükséges. A becslésnél ugyanazokat az ellenőrzéseket végezzük el, beleértve a 422 és 409 válaszokat kiváltó ellenőrzéseket, de nem hozunk létre feladatot, nem fordítunk szöveget, nem foglalunk le összeget, nem ellenőrizzük az egyenlegét, és nem terheljük meg a fiókját. HTTP 200 választ ad a következő mezőkkel: estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd és costUsd, a következő objektumban: data. A fenti példában a(z) costUsd értéke 0.000285000 a standard díjszabás szerint. Amíg az emelt szintű fordítás nem érhető el, az emelt szintű becslés 503 service_unavailable hibát ad. A becslések az aktuálisan beállított díjszabást használják. A feladat díjszabása létrehozáskor rögzül, és a díját ezzel a díjszabással számítjuk ki.

A fordítás lekérdezése

Új beküldésnél HTTP 202, meglévő vagy újrafelhasznált feladatnál HTTP 200 a válasz. Őrizze meg a(z) data.id értékét, és kövesse a közös útmutatót: feladatok munkafolyamata. A feladatobjektum a következő mezőket tartalmazza:

• id, status, engine, sourceLocale és targetLocale.
• sourceCharacters, costUsd, costIsEstimate és pricePerMillionCharactersUsd.
• progress és createdAt.
• modelVersion, egy átlátszatlan, feldolgozási verziót azonosító karakterlánc.
• duplicate az újrafelhasznált feladatot visszaadó válaszokban.
• failureCode sikertelen feladatoknál: translation_failed, translation_timeout, input_failed vagy worker_lease_lost.

A sikertelen feladat costUsd értéke nulla.

A befejezett feladat tartalmaz egy data.result objektumot a következő mezőkkel: sourceLocale (üres, ha nem adott meg forrásnyelvet), targetLocale, a lefordított text (a szegmensek szövege sortörésekkel összefűzve), valamint segments. Az ezen API-n keresztül beküldött szövegnél a(z) segments egy bejegyzést tartalmaz a lefordított text és a cél language mezővel. A fizetésre váró feladatok eredménye a díj rendezéséig nem érhető el.

Az api.multitel.net használata

A kompatibilitási végpont, POST https://api.multitel.net/v3/translate, ugyanazokat a JSON-mezőket és ugyanazt a(z) Idempotency-Key fejlécet fogadja el. Ha a fejléc hiányzik, a JSON-törzsben egy idempotency_key karakterláncot is elfogad. Minden más további mezőt 400 unsupported_translation_option hibával utasít el. Ezen a hoszton a nyers törzs legfeljebb 256,000 bájt lehet, és a 20,000 kódpontnál hosszabb szöveg 413 translation_too_large hibát ad 400 helyett. Az üres source_language értéket kihagyottként kezeli. A 429 válasz tartalmazza a(z) Retry-After: 15 fejlécet. Ez a hoszt a következő hibákat is visszaadja:

• 400 json_body_required ha a törzs hiányzik, érvénytelen JSON, vagy JSON-skalár. JSON-objektumot küldjön.
• 400 invalid_translation_options ha a(z) text, target_language vagy engine hiányzik, üres vagy nem karakterlánc, illetve ha a(z) source_language nem karakterlánc.
• 400 invalid_translation_text csak térközkarakterekből álló szöveg esetén.
• 400 invalid_translation_engine ismeretlen motor esetén.
• 400 idempotency_key_required hiányzó, üres vagy túl hosszú kulcs, illetve nem karakterlánc típusú idempotency_key esetén.
• 400 invalid_job hibás formátumú feladatazonosító esetén.

Az ezen a hoszton futó fordítási szolgáltatás válaszai a következő borítékot használják: {"status":{"code":HTTP_STATUS},"response":{...}}, ahol a(z) status egy objektum. A feladat azonosítóját a(z) response.id mezőből, a befejezett eredményt pedig a(z) response.result mezőből olvassa ki. Hibánál a kód a(z) response.code mezőbe kerül, üzenet vagy kérésazonosító nélkül. A hitelesítési hibákat (401) a hoszt általános bejelentkezési ellenőrzése adja vissza, és eltérő törzsük lehet, ezért a feldolgozás előtt ellenőrizze a HTTP-állapotkódot. A feladatok közösek az elsődleges hoszttal, de a lekérdezéshez, a fizetés rendezéséhez és a használati adatokhoz ugyanazt a hosztot használja, hogy a válaszfeldolgozó megfeleljen a borítékformátumnak. Ez a hoszt ugyanezeket a JSON-mezőket a következő végponton is elfogadja: /v3/translate/estimate idempotenciakulcs nélkül, és a becslést a(z) response objektumban adja vissza.