Zadania zamiany mowy na tekst i tłumaczenia

Zastąp SERVICE poniżej wartością speech_to_text lub translate, a JOB_ID zwróconym identyfikatorem UUID. Wszystkie operacje wymagają danych uwierzytelniających Twojego konta, jak opisano w sekcji Uwierzytelnianie, i są ograniczone do konta, do którego należą. Zadanie można odczytać z dowolnego hosta API, ale każdy host używa własnej koperty odpowiedzi, dlatego konsekwentnie korzystaj z jednego hosta.

Jeśli korzystasz z hosta api.multitel.net, błędy uwierzytelniania (401) są zwracane przed zastosowaniem tej koperty i mogą mieć inną treść, dlatego przed parsowaniem sprawdź status HTTP.

Uwierzytelnianie

Każde żądanie musi zawierać dane uwierzytelniające Twojego konta. Zadania, klucze idempotencji, limity, użycie i opłaty należą do konta, do którego należą dane uwierzytelniające. Są one wspólne dla wszystkich danych uwierzytelniających tego konta na obu hostach, niezależnie od tego, które z nich wysyłają żądanie.

• HTTP Basic (Authorization: Basic, ewentualnie curl --user). Akceptowane dane uwierzytelniające to konto API typu hasło, subkonto lub dane logowania do Twojego konta. Zalecamy dedykowane konto API. Nazwa użytkownika nie może zawierać dwukropka, a ani nazwa użytkownika, ani hasło nie mogą być puste.
• Token Bearer (Authorization: Bearer YOUR_TOKEN). Akceptowany dla konta API typu token. Konta API typu token muszą mieć ograniczenie IP, a żądania muszą pochodzić z dozwolonego adresu. Oba hosty API akceptują skonfigurowane dla konta adresy IPv4 i zakresy CIDR. Tokenu nie można wysłać jako hasła Basic. Sprawdź, czy Twój token działa na używanym hoście.

API_TOKEN="your-api-token"

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $API_TOKEN" \
  https://api.multi.tel/v3/speech_to_text

Jeśli konto API jest ograniczone według adresu IP, wysyłaj żądania z dozwolonego adresu. Brakujące lub nieprawidłowe dane uwierzytelniające zwracają 401. Jeśli korzystasz z hosta api.multitel.net, dane uwierzytelniające, które są prawidłowe, ale nie mogą korzystać z tych usług, np. dane konta typu token wysłane jako Basic, zwracają 403 unsupported_transcription_principal lub unsupported_translation_principal. Powtarzające się nieudane próby uwierzytelnienia z jednego adresu na hoście api.multitel.net mogą spowodować zablokowanie tego adresu, dlatego przed ponowieniem prób popraw dane uwierzytelniające.

Odpytywanie o zakończenie

Wyślij żądanie GET /v3/SERVICE/JOB_ID. Zalecamy odpytywanie nie częściej niż raz na 3 sekundy. Zewnętrzna koperta opisuje żądanie; sprawdź pole status wewnętrznego zadania, aby ustalić, czy przetwarzanie się zakończyło.

API_USER="your-api-username"
API_PASSWORD="your-api-password"
SERVICE="speech_to_text"
HOST="https://api.multi.tel"
JOB_ID=$(node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).data.id')

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/$JOB_ID"

Jeśli korzystasz z hosta api.multitel.net, ustaw HOST na https://api.multitel.net i odczytuj .response.id zamiast .data.id.

Bezpieczne ponawianie niepewnych żądań

Jeśli przesłanie przekroczy limit czasu lub zwróci 429 albo status 5xx, wyślij ponownie te same dane wejściowe z tym samym kluczem idempotencji. Odpowiedź z dowolnego hosta może zostać utracona lub zastąpiona błędem już po przyjęciu zadania; ponowne wysłanie z tym samym kluczem zwraca zadanie, jeśli ono istnieje. Klucz użyty ponownie z innymi danymi wejściowymi zwraca 409 idempotency_conflict. Niektóre błędy powtarzają się przy każdej próbie, np. 503, gdy płatna usługa jest wyłączona, lub 500 dla pliku audio, którego nie można odczytać, dlatego przerwij po kilku próbach.

Zmiana klucza ma różne skutki w zależności od usługi.

• W przypadku zamiany mowy na tekst nowy klucz tworzy nowe zadanie z osobną opłatą, jeśli przetwarzanie zakończy się pomyślnie. Pierwotny klucz nadal zwraca pierwotne zadanie, nawet po aktualizacji przetwarzania.
• W przypadku tłumaczenia nowy klucz z identyczną treścią zwraca bez nowej opłaty pasujące zadanie, które oczekuje w kolejce, jest przetwarzane, zostało zakończone lub oczekuje na płatność. Tworzy nowe zadanie, jeśli wcześniejsze zadanie zakończyło się niepowodzeniem lub zmieniła się wersja przetwarzania. Ponowienie tłumaczenia z pierwotnym kluczem zwraca 409 po zmianie wersji przetwarzania, dlatego zachowaj identyfikator pierwotnego zadania i odczytuj zadanie bezpośrednio.

Udostępnianie wyniku po zasileniu konta

Jeśli zadanie ma stan awaiting_payment, zasil konto tak, aby saldo wynosiło co najmniej wartość costUsd zadania zaokrągloną w górę do następnej wielokrotności $0.00001, a następnie wyślij POST /v3/SERVICE/JOB_ID/settle. Obciążenia są dokonywane w pełnych krokach po $0.00001 i obejmują ewentualną resztę przeniesioną z wcześniejszych zadań tej samej usługi, dlatego obciążona kwota może przekroczyć costUsd o mniej niż $0.00001. Jeśli korzystasz z hosta api.multi.tel, wyślij JSON {} lub pustą treść; każda właściwość w treści jest odrzucana z kodem 400. api.multitel.net ignoruje treść. Rozliczenie udostępnia zapisany wynik bez ponownego uruchamiania transkrypcji lub tłumaczenia. Odpowiedź zawiera zadanie; sprawdź, czy jego status to completed. Jeśli saldo nadal jest niewystarczające, zadanie pozostaje w stanie awaiting_payment i odpowiedź nadal ma status HTTP 200.

W przypadku zamiany mowy na tekst rozliczenie już zakończonego zadania zwraca je z polem duplicate: true, a rozliczenie zadania oczekującego w kolejce, przetwarzanego lub nieudanego zwraca 409 transcription_not_awaiting_payment. W przypadku tłumaczenia rozliczenie zadania w dowolnym innym stanie zwraca zadanie bez zmian. Rozliczenie jest dostępne tylko wtedy, gdy płatne przetwarzanie jest włączone (w przeciwnym razie 503). Zadania oczekujące na płatność są liczone jako zarezerwowany koszt, dlatego na kontach przedpłaconych mogą blokować nowe płatne przesłania kodem 402 do czasu ich rozliczenia.

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -X POST -H "Content-Type: application/json" --data '{}' \
  "$HOST/v3/$SERVICE/$JOB_ID/settle"

Sprawdzanie użycia

Użyj GET /v3/SERVICE/usage. Opcjonalne parametry from i to to daty UTC w formacie YYYY-MM-DD (obie daty graniczne są uwzględniane). Jeśli ich nie podasz, from domyślnie przyjmuje datę 30 dni przed dniem dzisiejszym, a to domyślnie przyjmuje dzisiejszą datę (UTC). to nie może być wcześniejszy niż from, a daty mogą dzielić maksymalnie 366 dni (do 367 dat). Nieprawidłowe daty kalendarzowe albo odwrócony lub dłuższy zakres zwracają 400, podobnie jak inne parametry zapytania na hoście api.multi.tel.

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/usage?from=2026-10-01&to=2026-10-31"

Odpowiedź zawiera mode, currency (USD), from, to i days, czyli listę uporządkowaną od najnowszych wpisów.

• Wpisy zamiany mowy na tekst są grupowane według daty i źródła. Zawierają date, source (api, ewentualnie hpbx w przypadku nagrań Hosted PBX), files, audioSeconds, billedSeconds, accruedUsd i debitedUsd.
• Wpisy tłumaczenia są grupowane według daty, źródła i silnika. Zawierają date, source, engine, jobs, sourceCharacters, accruedUsd i debitedUsd.

accruedUsd to dokładny koszt z dziewięcioma miejscami po przecinku, a debitedUsd to obciążona kwota z pięcioma. Użycie jest rejestrowane według daty UTC rozliczenia opłaty za dane zadanie, dlatego zadania oczekujące w kolejce, przetwarzane, nieudane i oczekujące na płatność nie są w nim widoczne.

Limity

Każde konto może mieć łącznie maksymalnie 50 niezakończonych zadań zamiany mowy na tekst i tłumaczenia: oczekujących w kolejce, przetwarzanych lub oczekujących na płatność, w tym przetwarzania nagrań Hosted PBX. Po osiągnięciu tego limitu lub ogólnej przepustowości usługi przesłania zwracają 429 transcription_queue_full lub translation_queue_full. api.multi.tel ogranicza też każdy adres IP klienta do 300 żądań na minutę łącznie dla wszystkich żądań do tego hosta. Ten limit zwraca 429 z nagłówkami limitu szybkości i treścią w postaci zwykłego tekstu zamiast koperty błędu JSON.

Obsługa błędów żądań

Na hoście głównym błędy zwracają status błędu HTTP oraz JSON z polami status: "error", code, message i requestId. Każda odpowiedź zawiera również nagłówek X-Request-ID z identyfikatorem żądania. Możesz podać własną wartość; wartości dłuższe niż 128 znaków są obcinane. Host zgodności zwraca tylko kod błędu w polu response.code. Rejestruj identyfikator żądania (jeśli jest dostępny) oraz kod błędu i nie zapisuj w logach audio, tekstu ani danych uwierzytelniających.

Typowe statusy:

Kieruj się zwróconym kodem błędu, zamiast zakładać, że każdy błąd walidacji ma jeden status.

W przypadku 429 lub 503 odczekaj i ponów próbę ze stopniowo wydłużanymi odstępami oraz tym samym kluczem przesłania; uwzględniaj nagłówek Retry-After (jeśli jest obecny). W przypadku nieprawidłowych danych wejściowych lub uwierzytelniających najpierw usuń przyczynę. Nie przesyłaj wielokrotnie nowych kluczy, gdy wcześniejsze zadania nadal oczekują w kolejce.