API pentru transcrierea vorbirii în text

Acest API transcrie fișiere audio finalizate prin sarcini puse în coadă. Trimiteți un fișier, păstrați ID-ul sarcinii returnate și interogați sarcina până la încheierea procesării. Trimiteți fiecare cerere prin HTTPS cu datele de autentificare ale contului dvs., fie prin HTTP Basic, ca în exemple, fie cu un token API, conform secțiunii Autentificare. Păstrați datele de autentificare pe serverul dvs.

Endpointuri

Cele două gazde API, https://api.multi.tel și gazda de compatibilitate https://api.multitel.net, folosesc în comun aceleași sarcini, chei de idempotență, limite și date de facturare la nivel de cont. Diferă prin codificarea încărcării și structura exterioară a răspunsului, așadar folosiți consecvent o singură gazdă, cu un parser corespunzător.

Pe api.multi.tel, toate căile sunt disponibile și cu prefixul /v1/speech-to-text în loc de /v3/speech_to_text, de exemplu POST /v1/speech-to-text/estimate. Pe api.multitel.net, folosiți căile /v3/speech_to_text.

Răspunsul cu informații despre serviciu include mode (batch), realtime (false), paidEnabled (dacă sunt acceptate în prezent sarcini noi cu plată), pricePerMinuteUsd (0.005), billingUnit (audio_second), maxAudioSeconds (7200) și maxUploadBytes (26214400), împreună cu o scurtă description. Citirea acestor informații este gratuită și funcționează și când trimiterea sarcinilor cu plată este dezactivată; returnează 503 transcription_unavailable doar când serviciul în ansamblu nu este disponibil.

Pregătiți un fișier audio

Folosiți un fișier audio finalizat de cel mult 25 MiB (26,214,400 octeți) și cel mult 2 ore (7,200 secunde). La trimitere, fișierul trebuie recunoscut drept conținut MP3, WAV, Ogg, FLAC, MOV sau Matroska cu un flux audio, având în metadate o durată mai mare decât zero și de cel mult 7,200 secunde. Un fișier recunoscut care nu trece aceste verificări este respins cu 422 unsupported_audio. Un fișier care nu poate fi citit în niciunul dintre aceste formate poate fi respins în prezent cu o eroare de server (500); nu retrimiteți un asemenea fișier fără modificări. Extensia fișierului nu dovedește singură compatibilitatea.

Trecerea acestor verificări nu garantează că sunetul poate fi decodat. Sunetul este procesat pe unul sau două canale. Un fișier cu mai mult de două canale audio, un fișier al cărui sunet decodat depășește 2 ore sau orice alt fișier care nu poate fi decodat în timpul procesării produce o sarcină failed, de regulă cu decode_failed, fără a fi taxat. Convertiți sunetul multicanal în mono sau stereo înainte de trimitere.

Indicația opțională de limbă este un cod de două sau trei litere mici pentru limba vorbită, de exemplu en. Dacă nu doriți să indicați limba, omiteți câmpul; api.multi.tel respinge un șir gol. Indicația ghidează procesarea, dar nu este verificată față de o listă de limbi acceptate, așadar folosiți un cod valid pentru limba vorbită.

Trimiteți o sarcină de transcriere

Trimiteți JSON cu Content-Type: application/json la POST https://api.multi.tel/v3/speech_to_text. Corpul cererii poate avea cel mult 35 MiB, suficient pentru un fișier de dimensiune maximă după codificarea base64; un corp mai mare este respins cu 413.

Orice altă proprietate JSON, inclusiv idempotency_key, este respinsă cu 400 invalid_transcription_request. Trimiteți cheia într-un antet.

Cheia de idempotență

Fiecare trimitere necesită un antet Idempotency-Key de 1 până la 190 de caractere. Folosiți litere ASCII, cifre, -, _, . și :, fără spații la început sau la sfârșit: gazda de compatibilitate elimină spațiile albe din jur și măsoară cheia în octeți, așa că alte caractere pot fi numărate diferit de cele două gazde. O cheie lipsă sau de 191 ori mai multe caractere este respinsă cu 400.

Cheile sunt limitate la contul dvs. și la serviciul de transcriere, pe ambele gazde și pentru toate datele de autentificare ale contului. Retrimiterea aceleiași chei cu același fișier și aceeași limbă returnează sarcina existentă cu HTTP 200 și duplicate: true, indiferent de starea sa și chiar dacă procesarea a fost actualizată de la crearea sarcinii, fără o nouă taxare. Refolosirea unei chei cu un alt fișier sau altă limbă returnează 409 idempotency_conflict. O cheie nouă creează o sarcină nouă chiar și pentru un fișier identic, cu taxare separată dacă procesarea se încheie cu succes.

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'

O sarcină nouă returnează HTTP 202 cu câmpurile de mai jos, iar repetarea cererii returnează HTTP 200 cu obiectul complet al sarcinii descris în Citiți transcrierea. Citiți ID-ul sarcinii, un UUID, din data.id. Răspunsul unei sarcini noi arată astfel (identificatorul și valorile sunt exemple):

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

Cât timp sarcina este în coadă sau în curs de procesare, durationSeconds, billedSeconds și costUsd sunt estimări din metadatele fișierului. Taxa finală folosește durata decodată.

Trimiterea poate returna și 402 insufficient_balance când soldul preplătit nu poate acoperi sarcina împreună cu celelalte sarcini restante, 429 transcription_queue_full când contul dvs. sau serviciul are prea multe sarcini restante, 429 audio_validation_busy când capacitatea de validare a fișierelor este epuizată și 503 paid_transcription_not_enabled cât timp transcrierea cu plată este dezactivată. Reîncercați mai târziu cererile care au primit 429 și 503, cu aceeași cheie.

Obțineți o estimare fără a crea o sarcină

Trimiteți același corp JSON la POST https://api.multi.tel/v3/speech_to_text/estimate. Nu este necesară o cheie de idempotență. Estimarea validează și măsoară fișierul, dar nu îl transcrie, nu creează o sarcină, nu rezervă fonduri, nu verifică soldul și nu taxează contul. O indicație language este acceptată, dar nu afectează estimarea.

O estimare reușită returnează HTTP 200 cu estimate: true, charged: false, mode, realtime, durationSeconds, billedSeconds, pricePerMinuteUsd și costUsd în data. Folosește durata din metadatele fișierului, în timp ce o sarcină finalizată este taxată după durata decodată, care poate fi diferită. Estimările aplică aceleași verificări de fișier ca trimiterile. Sunt disponibile doar când transcrierea cu plată este activată (altfel 503 paid_transcription_not_enabled). Pot returna 429 audio_validation_busy când capacitatea de validare a fișierelor este epuizată; reîncercați după o scurtă așteptare.

Citiți transcrierea

Interogați periodic GET /v3/speech_to_text/JOB_ID conform descrierii din ghidul fluxului de lucru al sarcinilor. Obiectul sarcinii conține aceste câmpuri:

Transcrierile, marcajele temporale și etichetele de limbă și canal sunt produse automat, fără garanția acurateței. Considerați orice marcaj de calitate un motiv pentru verificarea rezultatului și comparați numele importante, numerele și angajamentele cu înregistrarea originală. Pauzele lungi și pasajele cu volum foarte scăzut sunt omise și nu produc segmente. Rezultatele nu identifică vorbitori individuali. Când un rezultat raportează channelCount egal cu 2, fiecare segment are un channel egal cu A (primul canal, sau canalul din stânga) ori B (al doilea canal, sau canalul din dreapta). Aceasta separă vorbitorii doar dacă fiecare a fost înregistrat pe un canal separat. Sunetul cu două canale este facturat o singură dată după durata scursă, nu pe canal. Rezultatele mono nu au etichete de canal.

Utilizarea api.multitel.net

Endpointul de compatibilitate POST https://api.multitel.net/v3/speech_to_text acceptă multipart/form-data cu o parte de fișier audio și un câmp opțional language, în loc de JSON audioBase64. O valoare goală pentru language este tratată ca absența indicației de limbă. Trimiteți același antet Idempotency-Key. Dacă antetul lipsește, această gazdă acceptă și un câmp de formular idempotency_key. Câmpurile numite source, free, billing_source, realtime sau stream sunt respinse cu 400 unsupported_transcription_option; celelalte câmpuri de formular sunt ignorate. Această gazdă returnează și următoarele erori:

• 400 idempotency_key_required pentru o cheie lipsă sau prea lungă.
• 400 audio_upload_required pentru o încărcare lipsă sau primită incomplet.
• 400 invalid_language pentru o limbă nevalidă.
• 413 invalid_audio_size pentru un fișier gol sau prea mare.
• 400 invalid_job pentru un ID de sarcină cu format incorect.

Răspunsurile serviciului de transcriere de pe această gazdă folosesc structura exterioară {"status":{"code":HTTP_STATUS},"response":{...}}. Rețineți că status este un obiect, nu un șir. La succes, response conține același obiect ca data pe gazda principală, deci ID-ul sarcinii este response.id. La eroare, response.code conține codul erorii; nu sunt incluse un mesaj sau un ID de cerere. Erorile de autentificare (401) sunt returnate de verificarea generală de conectare a gazdei și pot avea alt corp, așadar verificați starea HTTP înainte de parsare. Nu interschimbați codificarea încărcării sau parserul de răspunsuri între gazde.

Pentru o estimare pe această gazdă, trimiteți prin POST aceleași câmpuri multipart la /v3/speech_to_text/estimate. Nu este necesară o cheie de idempotență, iar estimarea este în 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'