API pro převod řeči na text

Toto API přepisuje dokončené zvukové soubory jako úlohy ve frontě. Odešli soubor, ulož si vrácené ID úlohy a načítej úlohu, dokud zpracování neskončí. Každý požadavek posílej přes HTTPS s přihlašovacími údaji svého účtu: buď pomocí HTTP Basic jako v příkladech, nebo pomocí tokenu API, jak popisuje část Ověřování. Přihlašovací údaje uchovávej na svém serveru.

Koncové body

Dva servery API, https://api.multi.tel a server pro kompatibilitu https://api.multitel.net, sdílejí stejné úlohy, klíče idempotence, limity a účtování v rámci účtu. Liší se kódováním nahrávaných dat a vnější strukturou odpovědi, proto důsledně používej jeden server s odpovídajícím parserem.

Na api.multi.tel je každá cesta dostupná také s prefixem /v1/speech-to-text místo /v3/speech_to_text, například POST /v1/speech-to-text/estimate. Na api.multitel.net používej cesty /v3/speech_to_text.

Odpověď s informacemi o službě uvádí mode (batch), realtime (false), paidEnabled (zda se právě přijímají nové placené úlohy), pricePerMinuteUsd (0.005), billingUnit (audio_second), maxAudioSeconds (7200) a maxUploadBytes (26214400) spolu s krátkým popisem description. Načtení je zdarma a funguje i při zakázaném odesílání placených úloh; vrací 503 s kódem transcription_unavailable pouze tehdy, když je nedostupná celá služba.

Příprava zvukového souboru

Použij dokončený zvukový soubor o velikosti nejvýše 25 MiB (26,214,400 bajtů) a délce nejvýše 2 hodiny (7,200 sekund). Při odeslání musí být soubor rozpoznán jako médium MP3, WAV, Ogg, FLAC, MOV nebo Matroska obsahující zvukový proud, s délkou v metadatech větší než nula a nejvýše 7,200 sekund. Rozpoznaný soubor, který těmito kontrolami neprojde, je odmítnut s 422 a kódem unsupported_audio. Soubor, který nelze přečíst v žádném z těchto formátů, může být nyní místo toho odmítnut chybou serveru (500); takový soubor neposílej znovu beze změny. Samotná přípona souboru kompatibilitu nedokládá.

Úspěšné absolvování těchto kontrol nezaručuje, že lze zvuk dekódovat. Zvuk se zpracovává jako jeden nebo dva kanály. Soubor s více než dvěma zvukovými kanály, s dekódovaným zvukem delším než 2 hodiny nebo s jinou chybou dekódování během zpracování skončí jako úloha se stavem failed, obvykle s kódem decode_failed, a neúčtuje se. Před odesláním převeď vícekanálový zvuk na mono nebo stereo.

Volitelná jazyková nápověda je kód mluveného jazyka o dvou nebo třech malých písmenech, například en. Pokud nechceš jazyk napovědět, pole vynech; api.multi.tel odmítá prázdný řetězec. Nápověda řídí zpracování, ale nekontroluje se podle seznamu podporovaných jazyků, proto použij platný kód mluveného jazyka.

Odeslání úlohy přepisu

Pošli JSON s hlavičkou Content-Type: application/json na POST https://api.multi.tel/v3/speech_to_text. Tělo požadavku může mít až 35 MiB, což pojme soubor maximální velikosti po zakódování do base64; větší tělo je odmítnuto s 413.

Jakákoli jiná vlastnost JSON, včetně idempotency_key, je odmítnuta s 400 a kódem invalid_transcription_request. Klíč posílej jako hlavičku.

Klíč idempotence

Každé odeslání vyžaduje hlavičku Idempotency-Key o délce 1 až 190 znaků. Používej písmena ASCII, číslice, -, _, . a : bez mezer na začátku a konci: server pro kompatibilitu odstraňuje okolní bílé znaky a měří klíč v bajtech, takže jiné znaky se mohou na obou serverech počítat odlišně. Chybějící klíč nebo klíč o délce 191 či více znaků je odmítnut s 400.

Klíče platí pro tvůj účet a přepis řeči, napříč oběma servery a všemi přihlašovacími údaji účtu. Opětovné odeslání stejného klíče se stejným souborem a jazykem vrátí existující úlohu s HTTP 200 a duplicate: true, bez ohledu na její stav a i tehdy, když se zpracování od vytvoření úlohy aktualizovalo, bez dalšího poplatku. Opětovné použití klíče s jiným souborem nebo jazykem vrátí 409 a kód idempotency_conflict. Nový klíč vytvoří novou úlohu i pro totožný soubor, se samostatným poplatkem při úspěšném dokončení zpracování.

API_USER="your-api-username"
API_PASSWORD="your-api-password"

node -e 'process.stdout.write(JSON.stringify({audioBase64:require("node:fs").readFileSync("completed-call.mp3").toString("base64"),language:"en"}))' > completed-call.json

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: speech-call-001" \
  --data-binary @completed-call.json \
  -o speech-job.json \
  https://api.multi.tel/v3/speech_to_text

node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).data.id'

Nová úloha vrátí HTTP 202 s níže uvedenými poli a opakování požadavku vrátí HTTP 200 s celým objektem úlohy popsaným v části Načtení přepisu. ID úlohy, tedy UUID, načti z data.id. Odpověď nové úlohy vypadá takto (identifikátor a hodnoty jsou příklady):

{
  "status": "success",
  "data": {
    "id": "3f6c1b2e-8a4d-4e7f-9c21-5b0d7e4a9f13",
    "status": "queued",
    "mode": "batch",
    "realtime": false,
    "source": "api",
    "durationSeconds": 90.5,
    "billedSeconds": 91,
    "costUsd": "0.007583334",
    "pricePerMinuteUsd": "0.005"
  }
}

Dokud úloha čeká ve frontě nebo se zpracovává, jsou durationSeconds, billedSeconds a costUsd odhady z metadat souboru. Konečný poplatek se řídí dekódovanou délkou.

Odeslání může také vrátit 402 a kód insufficient_balance, když předplacený zůstatek nepokryje úlohu spolu s ostatními nevyřízenými úlohami, 429 a kód transcription_queue_full, když má účet nebo služba příliš mnoho nevyřízených úloh, 429 a kód audio_validation_busy, když je kapacita ověřování souborů vyčerpána, a 503 a kód paid_transcription_not_enabled, když je placený přepis vypnutý. Po odpovědích 429 a 503 to zkus později se stejným klíčem.

Odhad bez vytvoření úlohy

Pošli stejné tělo JSON na POST https://api.multi.tel/v3/speech_to_text/estimate. Klíč idempotence není potřeba. Odhad ověří a změří soubor, ale nepřepisuje jej, nevytváří úlohu, nerezervuje prostředky, nekontroluje zůstatek ani neúčtuje poplatek. Nápověda v poli language se přijímá, ale odhad neovlivní.

Úspěšný odhad vrátí HTTP 200 s poli estimate: true, charged: false, mode, realtime, durationSeconds, billedSeconds, pricePerMinuteUsd a costUsd pod data. Používá délku z metadat souboru, zatímco dokončená úloha se účtuje podle dekódované délky, která se může lišit. Odhady provádějí stejné kontroly souborů jako odeslání úloh. Jsou dostupné jen při zapnutém placeném přepisu (jinak 503 s kódem paid_transcription_not_enabled). Mohou vrátit 429 s kódem audio_validation_busy, když je kapacita ověřování souborů vyčerpána; po krátkém čekání to zkus znovu.

Načtení přepisu

Pravidelně se dotazuj na GET /v3/speech_to_text/JOB_ID podle popisu v průvodci zpracováním úloh. Objekt úlohy obsahuje tato pole:

Přepisy a jejich časové značky, jazykové a kanálové štítky vznikají automaticky a jejich přesnost není zaručena. Každý příznak kvality ber jako důvod ke kontrole výsledku a porovnej důležitá jména, čísla a závazky s původním zvukem. Dlouhá ticha a velmi tiché pasáže se přeskakují a nevytvářejí segmenty. Výsledky nerozpoznávají jednotlivé mluvčí. Když výsledek uvádí channelCount s hodnotou 2, má každý segment channel s hodnotou A (první neboli levý kanál) nebo B (druhý neboli pravý kanál). To oddělí mluvčí pouze tehdy, když byl každý nahrán na samostatný kanál. Dvoukanálový zvuk se účtuje jednou podle celkové uplynulé délky, nikoli za každý kanál. Výsledky mono nemají kanálové štítky.

Použití api.multitel.net

Koncový bod pro kompatibilitu POST https://api.multitel.net/v3/speech_to_text přijímá multipart/form-data se souborovou částí audio a volitelným polem language místo pole JSON audioBase64. Prázdná hodnota language se bere jako žádná nápověda. Pošli stejnou hlavičku Idempotency-Key. Pokud hlavička chybí, přijímá tento server také pole formuláře idempotency_key. Pole s názvy source, free, billing_source, realtime nebo stream se odmítají s 400 a kódem unsupported_transcription_option; ostatní pole formuláře se ignorují. Tento server vrací také tyto chyby:

• 400 idempotency_key_required při chybějícím nebo příliš dlouhém klíči.
• 400 audio_upload_required pokud soubor nebyl nahrán nebo nebyl přijat celý.
• 400 invalid_language při neplatném jazyku.
• 413 invalid_audio_size při prázdném nebo příliš velkém souboru.
• 400 invalid_job při nesprávném formátu ID úlohy.

Odpovědi služby přepisu na tomto serveru používají vnější strukturu {"status":{"code":HTTP_STATUS},"response":{...}}. Pozor: status je objekt, nikoli řetězec. Při úspěchu response obsahuje stejný objekt jako data na hlavním serveru, takže ID úlohy je response.id. Při chybě response.code obsahuje kód chyby; zpráva ani ID požadavku nejsou zahrnuty. Chyby ověřování (401) vrací obecná kontrola přihlášení serveru a mohou mít jiné tělo, proto před parsováním zkontroluj stav HTTP. Nezaměňuj mezi servery kódování nahrávání ani parser odpovědí.

Pro odhad na tomto serveru pošli metodou POST stejná multipart pole na /v3/speech_to_text/estimate. Klíč idempotence není potřeba a odhad je pod response.

API_USER="your-api-username"
API_PASSWORD="your-api-password"

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Idempotency-Key: speech-call-001" \
  -F "audio=@completed-call.mp3" -F "language=en" \
  -o speech-job.json \
  https://api.multitel.net/v3/speech_to_text

node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).response.id'