API tłumaczenia tekstu

Ten interfejs API tłumaczy tekst jako zadania w kolejce, z jednym językiem docelowym na zadanie. Prześlij tekst, zachowaj zwrócony identyfikator zadania i pobieraj zadanie do zakończenia przetwarzania. Każde żądanie wysyłaj przez HTTPS z danymi uwierzytelniającymi swojego konta: danymi HTTP Basic jak w przykładach lub tokenem API, zgodnie z opisem w sekcji Uwierzytelnianie. Przechowuj dane uwierzytelniające na swoim serwerze.

Punkty końcowe

Dwa serwery API, https://api.multi.tel i serwer zgodności https://api.multitel.net, współdzielą te same zadania, klucze idempotencji, limity i rozliczenia w obrębie konta. Różnią się zewnętrzną strukturą odpowiedzi, dlatego konsekwentnie używaj jednego serwera z odpowiednim parserem.

Na api.multi.tel każda ścieżka jest również dostępna z prefiksem /v1/translate zamiast /v3/translate. Na api.multitel.net używaj ścieżek /v3/translate.

Odpowiedź z informacjami o usłudze zawiera enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000), cpuLanguages i ratesNanosPerCharacter. cpuLanguages wymienia podstawowe kody języków akceptowane w tłumaczeniu standardowym. ratesNanosPerCharacter podaje skonfigurowaną cenę za punkt kodowy tekstu źródłowego dla każdego silnika, w miliardowych częściach dolara amerykańskiego: wartość 5000 oznacza $5 za milion punktów kodowych. Odpowiedź nie podaje, czy tłumaczenie rozszerzone jest obecnie dostępne; jego wycena zwraca 503, gdy jest niedostępne. Odczyt tych informacji jest bezpłatny.

Tłumaczenie tekstu

Wyślij JSON z nagłówkiem Content-Type: application/json do POST https://api.multi.tel/v3/translate. Każde zadanie ma jeden język docelowy, więc prześlij osobne zadanie dla każdego języka docelowego.

Kody ustawień regionalnych to znaczniki BCP 47 o długości od 2 do 63 liter, cyfr i łączników. Są sprowadzane do postaci kanonicznej, więc en-us jest zapisywane jako en-US. Nieprawidłowe znaczniki oraz und, mul lub zxx zwracają 400 invalid_translation_language. Dostępność tłumaczenia standardowego jest sprawdzana według języka podstawowego, a nb i nn są traktowane jako no. Regionalny język docelowy, taki jak fr-CA, jest przyjmowany i zapisywany, ale wynik standardowy opiera się na języku podstawowym i nie ma gwarancji, że uwzględni region.

Na tym serwerze ogranicz treść żądania do 128 KiB. Wysyłaj tekst jako UTF-8 zamiast zapisywać każdy znak spoza ASCII jako sekwencję \u, co może spowodować przekroczenie limitu przez żądanie z 20,000 znaków.

Treść przyjmuje tylko te cztery pola. Każda inna właściwość jest odrzucana z kodem 400 invalid_translation_request, w tym idempotency_key, identyfikatory właściciela, flagi bezpłatnego przetwarzania i tablice segmentów.

Idempotencja i ponowne wykorzystanie

Każde zgłoszenie wymaga nagłówka Idempotency-Key o długości od 1 do 190 znaków. Używaj liter ASCII, cyfr, -, _, . i : bez spacji na początku i końcu; brak klucza lub klucz o długości 191 znaków lub większej powoduje odrzucenie z kodem 400. Klucze są przypisane do Twojego konta i usługi tłumaczenia, wspólnie dla obu serwerów i wszystkich danych uwierzytelniających konta.

• Ten sam klucz z tym samym tekstem, językami w postaci kanonicznej i silnikiem zwraca istniejące zadanie z HTTP 200 i duplicate: true bez kolejnej opłaty.
• Ten sam klucz z innym tekstem, językami lub silnikiem zwraca 409 idempotency_conflict. Ten sam klucz zwraca 409 również wtedy, gdy wersja przetwarzania zmieniła się od utworzenia jego zadania. W takiej sytuacji odczytaj pierwotne zadanie według ID zamiast ponownie je przesyłać.
• Nowy klucz z tym samym tekstem, językami w postaci kanonicznej i silnikiem zwraca istniejące zadanie z HTTP 200 i duplicate: true bez nowej opłaty za przetwarzanie, jeśli zadanie z tą treścią i bieżącą wersją przetwarzania jest w kolejce, w trakcie przetwarzania, ukończone lub oczekuje na płatność. Ponownie wykorzystane zadanie oczekujące na płatność nadal wymaga rozliczenia. Zadania zakończone błędem nie są wykorzystywane ponownie: powstaje nowe zadanie, za które opłata jest naliczana po ukończeniu.

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'

Nowe zadanie zwraca HTTP 202. Przykładowy tekst ma 57 punktów kodowych, więc przy cenie $5 za milion punktów kodowych kosztuje $0.000285. Skrócona odpowiedź (identyfikator jest przykładowy):

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

Zgłoszenie może również zwrócić 402 insufficient_balance, gdy saldo przedpłacone nie pokrywa zadania wraz z innymi zadaniami w toku, oraz 429 translation_queue_full, gdy konto lub usługa mają zbyt wiele zadań w toku. W następujących przypadkach zwraca 503:

• paid_translation_not_enabled, gdy płatne tłumaczenie jest wyłączone.
• translation_unavailable dla żądania rozszerzonego, gdy tłumaczenie rozszerzone jest niedostępne.
• translation_pricing_unavailable, gdy wybrany silnik nie ma skonfigurowanej stawki.

Po odpowiedziach 429 i 503 ponów próbę później z tym samym kluczem.

Wybór jakości

Długi tekst jest przetwarzany w mniejszych częściach, a następnie łączony. Podział na wiersze i odstępy mogą się zmienić, a zdanie może stracić kontekst na granicy przetwarzanych części. Zachowaj oryginalny tekst i sprawdź połączony wynik. Tłumaczenie standardowe używa języka podstawowego znacznika regionalnego; przyjęcie i zapisanie znacznika nie gwarantuje regionalnego słownictwa.

Tłumaczenie standardowe działa w procesach roboczych na CPU. Tłumaczenie rozszerzone wysyła tekst do skonfigurowanej zewnętrznej usługi AI. Jego wynik nadal wymaga sprawdzenia; usługa nie gwarantuje, że jeden silnik będzie dokładniejszy dla każdej pary języków lub rodzaju tekstu.

Tłumaczenie standardowe jest wersją roboczą, której jakość i czas przetwarzania zależą od pary języków. Tłumaczenie rozszerzone jest przeznaczone do tekstów, w których ważny jest kontekst, ale nadal wymaga sprawdzenia ważnych nazwisk i nazw, liczb, przeczeń oraz zobowiązań. Żadna opcja nie naprawia błędów już obecnych w oryginalnej transkrypcji, dlatego zachowaj oryginał do porównania.

Użyj GET /v3/translate na tym samym serwerze API, aby sprawdzić bieżącą dostępność, obsługiwane języki standardowe i skonfigurowane stawki. Żądanie standardowe, którego podstawowy język źródłowy lub docelowy nie występuje w cpuLanguages, zwraca 422 translation_language_pair_unavailable. Gdy podano source_language i ma ono ten sam język podstawowy co język docelowy, żądanie zwraca 409 translation_same_language zamiast tworzyć zadanie. Tłumaczenie rozszerzone jest włączane osobno: gdy jest niedostępne, zgłoszenia i wyceny rozszerzone zwracają 503.

Najpierw uzyskaj wycenę

Na api.multi.tel wyślij tę samą treść JSON do POST /v3/translate/estimate. Klucz idempotencji nie jest wymagany. Wycena przeprowadza tę samą walidację, w tym kontrole 422 i 409, ale nie tworzy zadania, nie tłumaczy tekstu, nie rezerwuje środków, nie sprawdza salda i nie obciąża konta. Zwraca HTTP 200 z polami estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd i costUsd w data. Dla powyższego przykładu costUsd wynosi 0.000285000 według standardowej stawki. Gdy tłumaczenie rozszerzone jest niedostępne, wycena rozszerzona zwraca 503 service_unavailable. Wyceny używają aktualnie skonfigurowanej stawki. Stawka zadania jest ustalana w chwili jego utworzenia i według niej naliczana jest opłata.

Pobranie tłumaczenia

Nowe zgłoszenie zwraca HTTP 202, a istniejące lub ponownie wykorzystane zadanie zwraca HTTP 200. Zachowaj data.id i użyj wspólnego przebiegu obsługi zadań. Obiekt zadania zawiera następujące pola:

• id, status, engine, sourceLocale i targetLocale.
• sourceCharacters, costUsd, costIsEstimate i pricePerMillionCharactersUsd.
• progress i createdAt.
• modelVersion, nieprzezroczysty ciąg identyfikujący wersję przetwarzania.
• duplicate w odpowiedziach wykorzystujących istniejące zadanie.
• failureCode dla zadań zakończonych błędem: translation_failed, translation_timeout, input_failed lub worker_lease_lost.

Zadanie zakończone błędem pokazuje costUsd o wartości zero.

Ukończone zadanie zawiera data.result. Obiekt ten zawiera sourceLocale (puste, jeśli nie podano języka źródłowego), targetLocale, pole text z tłumaczeniem (teksty segmentów połączone znakami nowego wiersza) oraz segments. Dla tekstu przesłanego przez to API segments zawiera jeden wpis z polem text zawierającym tłumaczenie i docelowym kodem języka w polu language. Wyniki zadań oczekujących na płatność są wstrzymywane do rozliczenia.

Korzystanie z api.multitel.net

Punkt końcowy zgodności POST https://api.multitel.net/v3/translate przyjmuje te same pola JSON i ten sam nagłówek Idempotency-Key. Jeśli nagłówka nie ma, przyjmuje także ciąg idempotency_key w treści JSON. Każde inne dodatkowe pole jest odrzucane z kodem 400 unsupported_translation_option. Na tym serwerze surowa treść może mieć do 256,000 bajtów, a tekst przekraczający 20,000 punktów kodowych zwraca 413 translation_too_large zamiast 400. Puste source_language jest traktowane jako pominięte. Odpowiedź 429 zawiera Retry-After: 15. Ten serwer zwraca również te błędy:

• 400 json_body_required przy braku treści, nieprawidłowym JSON lub skalarze JSON. Wyślij obiekt JSON.
• 400 invalid_translation_options gdy brakuje któregoś z pól text, target_language lub engine, jest ono puste lub nie jest ciągiem znaków albo gdy source_language nie jest ciągiem znaków.
• 400 invalid_translation_text dla tekstu złożonego wyłącznie z białych znaków.
• 400 invalid_translation_engine dla nieznanego silnika.
• 400 idempotency_key_required przy braku klucza, pustym lub zbyt długim kluczu albo gdy idempotency_key nie jest ciągiem znaków.
• 400 invalid_job dla identyfikatora zadania o nieprawidłowym formacie.

Odpowiedzi usługi tłumaczenia na tym serwerze używają zewnętrznej struktury {"status":{"code":HTTP_STATUS},"response":{...}}, w której status jest obiektem. Odczytaj identyfikator zadania z response.id i ukończony wynik z response.result. Przy błędach kod znajduje się w response.code bez komunikatu i identyfikatora żądania. Błędy uwierzytelniania (401) zwraca ogólna kontrola logowania serwera i mogą mieć inną treść odpowiedzi, dlatego przed parsowaniem sprawdź status HTTP. Zadania są współdzielone z głównym serwerem, ale używaj tego samego serwera do odpytywania, rozliczeń i wykorzystania, aby parser odpowiadał zewnętrznej strukturze. Ten serwer przyjmuje również te same pola JSON w /v3/translate/estimate bez klucza idempotencji, a wycena jest w response.