API za pretvaranje govora u tekst

Ovaj API transkribira dovršene audiodatoteke kao zadatke u redu za obradu. Pošaljite datoteku, sačuvajte vraćeni ID zadatka i dohvaćajte zadatak dok obrada ne završi. Svaki zahtjev šaljite putem HTTPS-a s vjerodajnicama svojeg računa: vjerodajnicama za HTTP Basic kao u primjerima ili API tokenom, kako je opisano u odjeljku Autentifikacija. Vjerodajnice čuvajte na svojem poslužitelju.

Krajnje točke

Dva API poslužitelja, https://api.multi.tel i poslužitelj za kompatibilnost https://api.multitel.net, dijele iste zadatke, ključeve idempotentnosti, ograničenja i naplatu unutar računa. Razlikuju se po kodiranju prijenosa i omotnici odgovora, pa dosljedno koristite jedan poslužitelj s odgovarajućim parserom.

Na poslužitelju api.multi.tel svaka je putanja dostupna i s prefiksom /v1/speech-to-text umjesto /v3/speech_to_text, primjerice POST /v1/speech-to-text/estimate. Na poslužitelju api.multitel.net koristite putanje /v3/speech_to_text.

Odgovor s informacijama o usluzi navodi mode (batch), realtime (false), paidEnabled (prihvaćaju li se trenutačno nova slanja koja se naplaćuju), pricePerMinuteUsd (0.005), billingUnit (audio_second), maxAudioSeconds (7200) i maxUploadBytes (26214400), uz kratak opis u polju description. Dohvat je besplatan i radi dok su slanja koja se naplaćuju onemogućena; vraća 503 transcription_unavailable samo kada je usluga u cijelosti nedostupna.

Priprema audiodatoteke

Koristite dovršenu audiodatoteku veličine najviše 25 MiB (26,214,400 bajtova) i trajanja najviše 2 sata (7,200 sekundi). Pri slanju datoteka mora biti prepoznata kao MP3, WAV, Ogg, FLAC, MOV ili Matroska medijski zapis koji sadrži audiozapis, s trajanjem u metapodacima većim od nule i ne duljim od 7,200 sekundi. Prepoznata datoteka koja ne zadovolji ove provjere odbija se uz 422 unsupported_audio. Datoteka koja se ne može pročitati ni u jednom od tih formata trenutačno se umjesto toga može odbiti uz pogrešku poslužitelja (500); nemojte je ponovno slati bez izmjena. Sam nastavak naziva datoteke ne potvrđuje kompatibilnost.

Prolazak ovih provjera ne jamči da se zvuk može dekodirati. Zvuk se obrađuje kao jedan ili dva kanala. Datoteka s više od dva audiokanala, datoteka čiji je dekodirani zvuk dulji od 2 sata ili bilo koja druga datoteka čije dekodiranje ne uspije tijekom obrade završava kao zadatak sa statusom failed, obično s kodom decode_failed, i ne naplaćuje se. Prije slanja pretvorite višekanalni zvuk u mono ili stereo.

Neobavezna naznaka jezika jest dvoslovni ili troslovni kod malim slovima za jezik koji se govori, primjerice en. Ako ne želite navesti naznaku, izostavite polje; api.multi.tel odbija prazan niz znakova. Naznaka usmjerava obradu, ali se ne provjerava prema popisu podržanih jezika, pa koristite valjan kod za jezik koji se govori.

Slanje zadatka transkripcije

Pošaljite JSON sa zaglavljem Content-Type: application/json na POST https://api.multi.tel/v3/speech_to_text. Tijelo zahtjeva može imati najviše 35 MiB, što omogućuje prijenos datoteke najveće dopuštene veličine nakon kodiranja base64; veće tijelo odbija se uz 413.

Svako drugo JSON svojstvo, uključujući idempotency_key, odbija se uz 400 invalid_transcription_request. Ključ pošaljite kao zaglavlje.

Ključ idempotentnosti

Za svako slanje potrebno je zaglavlje Idempotency-Key duljine od 1 do 190 znakova. Koristite ASCII slova, znamenke, -, _, . i :, bez početnih ili završnih razmaka: poslužitelj za kompatibilnost uklanja okolne bjeline i mjeri ključ u bajtovima, pa se ostali znakovi na svakom poslužitelju mogu brojiti drukčije. Ključ koji nedostaje ili ima 191 ili više znakova odbija se uz 400.

Ključevi su ograničeni na vaš račun i uslugu pretvaranja govora u tekst, na oba poslužitelja i za sve vjerodajnice vašeg računa. Ponovno slanje istog ključa s istom datotekom i jezikom vraća postojeći zadatak uz HTTP 200 i duplicate: true, neovisno o njegovu statusu i čak ako je obrada ažurirana nakon stvaranja zadatka, bez ponovne naplate. Ponovna upotreba ključa s drugom datotekom ili jezikom vraća 409 idempotency_conflict. Novi ključ stvara novi zadatak čak i za istu datoteku, uz zasebnu naplatu ako obrada uspješno završi.

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'

Novi zadatak vraća HTTP 202 s poljima prikazanima u nastavku, a ponovljeni zahtjev vraća HTTP 200 s cijelim objektom zadatka opisanim u odjeljku Dohvat transkripta. ID zadatka, koji je UUID, pročitajte iz polja data.id. Odgovor za novi zadatak izgleda ovako (identifikator i vrijednosti služe kao primjeri):

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

Dok je zadatak u redu za obradu ili se izvršava, durationSeconds, billedSeconds i costUsd su procjene iz metapodataka datoteke. Konačna naplata koristi dekodirano trajanje.

Slanje može vratiti i 402 insufficient_balance kada unaprijed plaćeno stanje ne može pokriti zadatak zajedno s vašim ostalim nedovršenim zadacima, 429 transcription_queue_full kada vaš račun ili usluga ima previše nedovršenih zadataka, 429 audio_validation_busy kada su kapaciteti za provjeru datoteka popunjeni te 503 paid_transcription_not_enabled dok je transkripcija koja se naplaćuje onemogućena. Za odgovore 429 i 503 pokušajte ponovno kasnije s istim ključem.

Procjena bez stvaranja zadatka

Pošaljite isto JSON tijelo na POST https://api.multi.tel/v3/speech_to_text/estimate. Ključ idempotentnosti nije potreban. Procjena provjerava i mjeri datoteku, ali je ne transkribira, ne stvara zadatak, ne rezervira sredstva, ne provjerava vaše stanje i ne tereti vaš račun. Naznaka language prihvaća se, ali ne utječe na procjenu.

Uspješna procjena vraća HTTP 200 s poljima estimate: true, charged: false, mode, realtime, durationSeconds, billedSeconds, pricePerMinuteUsd i costUsd unutar objekta data. Koristi trajanje iz metapodataka datoteke, dok se dovršeni zadatak naplaćuje prema dekodiranom trajanju, koje se može razlikovati. Procjene primjenjuju iste provjere datoteke kao i slanja zadataka. Dostupne su samo dok je transkripcija koja se naplaćuje omogućena (u suprotnom 503 paid_transcription_not_enabled). Mogu vratiti 429 audio_validation_busy kada su kapaciteti za provjeru datoteka popunjeni; pokušajte ponovno nakon kratkog čekanja.

Dohvat transkripta

Periodično dohvaćajte GET /v3/speech_to_text/JOB_ID kako je opisano u vodiču kroz tijek rada sa zadacima. Objekt zadatka sadrži ova polja:

Transkripti i njihove vremenske oznake, oznake jezika i oznake kanala izrađuju se automatski i njihova točnost nije zajamčena. Svaku oznaku kvalitete smatrajte razlogom za provjeru rezultata te usporedite važna imena, brojeve i obveze s izvornim zvukom. Duge tišine i vrlo tihi dijelovi preskaču se i ne proizvode segmente. Rezultati ne identificiraju pojedine govornike. Kada rezultat navodi channelCount s vrijednošću 2, svaki segment ima channel s vrijednošću A (prvi, odnosno lijevi kanal) ili B (drugi, odnosno desni kanal). To razdvaja govornike samo kada je svaki snimljen na zasebnom kanalu. Dvokanalni zvuk naplaćuje se jednom prema proteklom trajanju, a ne po kanalu. Mono rezultati nemaju oznake kanala.

Korištenje poslužitelja api.multitel.net

Krajnja točka za kompatibilnost POST https://api.multitel.net/v3/speech_to_text prihvaća multipart/form-data s dijelom datoteke nazvanim audio i neobaveznim poljem language, umjesto JSON polja audioBase64. Prazna vrijednost polja language smatra se izostankom naznake. Pošaljite isto zaglavlje Idempotency-Key. Ako zaglavlje nedostaje, ovaj poslužitelj prihvaća i polje obrasca idempotency_key. Polja s nazivima source, free, billing_source, realtime ili stream odbijaju se uz 400 unsupported_transcription_option; ostala polja obrasca zanemaruju se. Ovaj poslužitelj vraća i sljedeće pogreške:

• 400 idempotency_key_required ako ključ nedostaje ili je predugačak.
• 400 audio_upload_required ako prijenos nedostaje ili nije primljen u cijelosti.
• 400 invalid_language za nevaljan jezik.
• 413 invalid_audio_size za praznu ili preveliku datoteku.
• 400 invalid_job za neispravno oblikovan ID zadatka.

Odgovori usluge pretvaranja govora u tekst s ovog poslužitelja koriste omotnicu {"status":{"code":HTTP_STATUS},"response":{...}}. Imajte na umu da je status objekt, a ne niz znakova. U slučaju uspjeha, response sadrži isti objekt kao data na primarnom poslužitelju, pa je ID zadatka response.id. U slučaju pogreške, response.code sadrži kod pogreške; poruka i ID zahtjeva nisu uključeni. Neuspjelu autentifikaciju (401) vraća opća provjera prijave na poslužitelju i tijelo odgovora može biti drukčije, pa provjerite HTTP status prije parsiranja. Nemojte zamjenjivati kodiranje prijenosa ili parser odgovora između poslužitelja.

Za procjenu na ovom poslužitelju pošaljite ista multipart polja metodom POST na /v3/speech_to_text/estimate. Ključ idempotentnosti nije potreban, a procjena je unutar objekta 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'