API për kthimin e të folurit në tekst

Ky API transkripton skedarë audio të përfunduar si punë në radhë. Dërgoni një skedar, ruani ID-në e kthyer të punës dhe lexojeni punën derisa përpunimi të ketë përfunduar. Dërgoni çdo kërkesë përmes HTTPS me kredencialet e llogarisë suaj, ose kredenciale HTTP Basic si në shembuj, ose një token API, siç përshkruhet te Autentikimi. Mbajini kredencialet në serverin tuaj.

Pikat fundore

Dy hostet API, https://api.multi.tel dhe hosti i përputhshmërisë https://api.multitel.net, ndajnë të njëjtat punë, çelësa idempotence, kufij dhe faturim të lidhur me llogarinë. Ato ndryshojnë në kodimin e ngarkimit dhe mbështjellësin e përgjigjes, prandaj përdorni vazhdimisht një host me analizuesin përkatës të përgjigjeve.

Në api.multi.tel, çdo shteg është gjithashtu i disponueshëm me prefiksin /v1/speech-to-text në vend të /v3/speech_to_text, për shembull POST /v1/speech-to-text/estimate. Në api.multitel.net, përdorni shtigjet /v3/speech_to_text.

Përgjigjja me informacionin e shërbimit raporton mode (batch), realtime (false), paidEnabled (nëse aktualisht pranohen dërgime të reja me pagesë), pricePerMinuteUsd (0.005), billingUnit (audio_second), maxAudioSeconds (7200) dhe maxUploadBytes (26214400), së bashku me një përshkrim të shkurtër te description. Leximi është falas dhe funksionon kur dërgimet me pagesë janë të çaktivizuara; kthen 503 transcription_unavailable vetëm kur shërbimi në tërësi është i padisponueshëm.

Përgatitni një skedar audio

Përdorni një skedar audio të përfunduar me madhësi deri në 25 MiB (26,214,400 bajte) dhe kohëzgjatje deri në 2 orë (7,200 sekonda). Në dërgim, skedari duhet të njihet si media MP3, WAV, Ogg, FLAC, MOV ose Matroska që përmban një rrjedhë audio, me kohëzgjatje në metadatat e tij më të madhe se zero dhe jo më shumë se 7,200 sekonda. Një skedar i njohur që nuk i kalon këto kontrolle refuzohet me 422 unsupported_audio. Një skedar që nuk mund të lexohet si asnjëri prej këtyre formateve aktualisht mund të refuzohet me një gabim serveri (500); mos e dërgoni sërish një skedar të tillë pa e ndryshuar. Vetëm prapashtesa e skedarit nuk vërteton përputhshmërinë.

Kalimi i këtyre kontrolleve nuk garanton që audioja mund të dekodohet. Audioja përpunohet si një ose dy kanale. Një skedar me më shumë se dy kanale audio, një skedar audioja e dekoduar e të cilit është më e gjatë se 2 orë, ose çdo skedar tjetër që nuk dekodohet gjatë përpunimit, përfundon si një punë me status failed, zakonisht me decode_failed, dhe nuk tarifohet. Shndërrojeni audion me shumë kanale në mono ose stereo përpara dërgimit.

Sugjerimi opsional i gjuhës është një kod me dy ose tre shkronja të vogla për gjuhën e folur, si en. Për të mos dhënë sugjerim, mos e përfshini fushën; api.multi.tel refuzon një varg bosh. Sugjerimi udhëzon përpunimin, por nuk kontrollohet kundrejt një liste gjuhësh të mbështetura, prandaj përdorni një kod të vlefshëm për gjuhën e folur.

Dërgoni një punë transkriptimi

Dërgoni JSON me Content-Type: application/json te POST https://api.multi.tel/v3/speech_to_text. Trupi i kërkesës mund të jetë deri në 35 MiB, çka lejon një skedar me madhësi maksimale pas kodimit base64; një trup më i madh refuzohet me 413.

Çdo veti tjetër JSON, përfshirë idempotency_key, refuzohet me 400 invalid_transcription_request. Dërgojeni çelësin si fushë të kreut HTTP.

Çelësi i idempotencës

Çdo dërgim kërkon një fushë të kreut HTTP Idempotency-Key me 1 deri në 190 shenja. Përdorni shkronja ASCII, shifra, -, _, . dhe :, pa hapësira në fillim ose fund: hosti i përputhshmërisë heq karakteret e hapësirës së bardhë përreth dhe e mat çelësin në bajte, kështu që shenja të tjera mund të numërohen ndryshe nga secili host. Një çelës që mungon ose një çelës me 191 a më shumë shenja refuzohet me 400.

Çelësat lidhen me llogarinë tuaj dhe shërbimin e kthimit të të folurit në tekst, në të dy hostet dhe për të gjitha kredencialet e llogarisë suaj. Ridërgimi i të njëjtit çelës me të njëjtin skedar dhe gjuhë kthen punën ekzistuese me HTTP 200 dhe duplicate: true, pavarësisht statusit të saj dhe edhe nëse përpunimi është përditësuar që nga krijimi i punës, pa një tarifë tjetër. Ripërdorimi i një çelësi me skedar ose gjuhë tjetër kthen 409 idempotency_conflict. Një çelës i ri krijon një punë të re edhe për një skedar identik, me tarifë të veçantë nëse përpunimi përfundon me sukses.

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'

Një punë e re kthen HTTP 202 me fushat e paraqitura më poshtë, ndërsa një dërgim i përsëritur kthen HTTP 200 me objektin e plotë të punës të përshkruar te Lexoni transkriptin. Lexojeni ID-në e punës, një UUID, nga data.id. Përgjigjja e një pune të re duket kështu (identifikuesi dhe vlerat janë shembuj):

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

Ndërsa një punë është në radhë ose në ekzekutim, durationSeconds, billedSeconds dhe costUsd janë vlerësime nga metadatat e skedarit. Tarifa përfundimtare përdor kohëzgjatjen e dekoduar.

Një dërgim mund të kthejë edhe 402 insufficient_balance kur bilanci i parapaguar nuk e mbulon punën së bashku me punët tuaja të tjera të papërfunduara, 429 transcription_queue_full kur llogaria juaj ose shërbimi ka tepër punë të papërfunduara, 429 audio_validation_busy kur kapaciteti për verifikimin e skedarëve është i zënë plotësisht, dhe 503 paid_transcription_not_enabled kur transkriptimi me pagesë është i çaktivizuar. Riprovoni më vonë kërkesat me përgjigje 429 dhe 503 duke përdorur të njëjtin çelës.

Vlerësimi pa krijuar një punë

Dërgojeni të njëjtin trup JSON te POST https://api.multi.tel/v3/speech_to_text/estimate. Nuk kërkohet çelës idempotence. Një vlerësim e verifikon dhe e mat skedarin, por nuk e transkripton, nuk krijon një punë, nuk rezervon fonde, nuk kontrollon bilancin tuaj dhe nuk tarifon llogarinë tuaj. Një sugjerim language pranohet, por nuk ndikon në vlerësim.

Një vlerësim i suksesshëm kthen HTTP 200 me estimate: true, charged: false, mode, realtime, durationSeconds, billedSeconds, pricePerMinuteUsd dhe costUsd brenda data. Përdor kohëzgjatjen në metadatat e skedarit, ndërsa një punë e përfunduar tarifohet sipas kohëzgjatjes së dekoduar, e cila mund të ndryshojë. Vlerësimet zbatojnë të njëjtat kontrolle skedari si dërgimet. Ato janë të disponueshme vetëm kur transkriptimi me pagesë është i aktivizuar (përndryshe 503 paid_transcription_not_enabled). Mund të kthejnë 429 audio_validation_busy kur kapaciteti për verifikimin e skedarëve është i zënë plotësisht; riprovoni pas një pritjeje të shkurtër.

Lexoni transkriptin

Bëni kërkesa periodike te GET /v3/speech_to_text/JOB_ID siç përshkruhet në udhëzuesin e rrjedhës së punëve. Objekti i punës përmban këto fusha:

Transkriptet dhe vulat e tyre kohore, etiketat e gjuhës dhe etiketat e kanaleve prodhohen automatikisht dhe saktësia e tyre nuk garantohet. Trajtojeni çdo sinjalizues cilësie si arsye për ta shqyrtuar rezultatin dhe krahasoni emrat, numrat dhe zotimet e rëndësishme me audion origjinale. Heshtjet e gjata dhe pjesët shumë të qeta anashkalohen dhe nuk prodhojnë segmente. Rezultatet nuk identifikojnë folës të veçantë. Kur një rezultat raporton channelCount me vlerë 2, çdo segment ka një channel me vlerë A (kanali i parë, ose i majtë) ose B (kanali i dytë, ose i djathtë). Kjo i ndan folësit vetëm kur secili është regjistruar në një kanal të veçantë. Audioja me dy kanale faturohet një herë sipas kohëzgjatjes së kaluar, jo për çdo kanal. Rezultatet mono nuk kanë etiketa kanalesh.

Përdorimi i api.multitel.net

Pika fundore e përputhshmërisë POST https://api.multitel.net/v3/speech_to_text pranon multipart/form-data me një pjesë skedari audio dhe një fushë opsionale language, në vend të JSON audioBase64. Një vlerë bosh e language trajtohet si mungesë sugjerimi. Dërgojeni të njëjtën fushë të kreut HTTP Idempotency-Key. Nëse kjo fushë mungon, ky host pranon gjithashtu një fushë formulari idempotency_key. Fushat me emrat source, free, billing_source, realtime ose stream refuzohen me 400 unsupported_transcription_option; fushat e tjera të formularit shpërfillen. Ky host kthen edhe këto gabime:

• 400 idempotency_key_required për një çelës që mungon ose është tepër i gjatë.
• 400 audio_upload_required për një ngarkim që mungon ose nuk është marrë plotësisht.
• 400 invalid_language për një gjuhë të pavlefshme.
• 413 invalid_audio_size për një skedar bosh ose tepër të madh.
• 400 invalid_job për një ID pune me format të pavlefshëm.

Përgjigjet nga shërbimi i kthimit të të folurit në tekst i këtij hosti përdorin mbështjellësin {"status":{"code":HTTP_STATUS},"response":{...}}. Vini re se status është një objekt, jo një varg. Në sukses, response përmban të njëjtin objekt si data në hostin kryesor, kështu që ID-ja e punës është response.id. Në gabim, response.code përmban kodin e gabimit; nuk përfshihet mesazh ose ID e kërkesës. Dështimet e autentikimit (401) kthehen nga kontrolli i përgjithshëm i hyrjes së hostit dhe mund të kenë një trup tjetër, prandaj kontrolloni statusin HTTP përpara analizimit të përgjigjes. Mos ndërroni kodimin e ngarkimit ose analizuesin e përgjigjes midis hosteve.

Për një vlerësim në këtë host, dërgoni me POST të njëjtat fusha multipart te /v3/speech_to_text/estimate. Nuk kërkohet çelës idempotence dhe vlerësimi është brenda 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'