Runas pārvēršanas tekstā API

Šis API transkribē pabeigtus audio failus kā rindā ievietotus darbus. Iesniedziet failu, saglabājiet atgriezto darba ID un izgūstiet darbu, līdz apstrāde ir pabeigta. Sūtiet visus pieprasījumus, izmantojot HTTPS un sava konta autentifikācijas datus: piemēros parādītos HTTP Basic datus vai API pilnvaru, kā aprakstīts sadaļā Autentifikācija. Glabājiet autentifikācijas datus savā serverī.

Galapunkti

Abi API serveri — https://api.multi.tel un saderības serveris https://api.multitel.net — koplieto vienus un tos pašus konta darbus, idempotences atslēgas, ierobežojumus un norēķinus. Augšupielādes kodējums un atbildes ietvars atšķiras, tāpēc konsekventi izmantojiet vienu serveri ar atbilstošu parsētāju.

Serverī api.multi.tel visi ceļi ir pieejami arī ar prefiksu /v1/speech-to-text šī prefiksa vietā: /v3/speech_to_text, piemēram, POST /v1/speech-to-text/estimate. Serverī api.multitel.net izmantojiet /v3/speech_to_text ceļus.

Pakalpojuma informācijas atbildē ir norādīti mode (batch), realtime (false), paidEnabled (vai pašlaik tiek pieņemti jauni maksas darbi), pricePerMinuteUsd (0.005), billingUnit (audio_second), maxAudioSeconds (7200) un maxUploadBytes (26214400), kā arī īss apraksts laukā description. Informācijas izgūšana ir bez maksas un darbojas arī tad, kad maksas darbu iesniegšana ir atspējota; tā atgriež 503 transcription_unavailable tikai tad, ja viss pakalpojums nav pieejams.

Sagatavojiet audio failu

Izmantojiet pabeigtu audio failu, kura lielums nepārsniedz 25 MiB (26,214,400 baitus) un ilgums nepārsniedz 2 stundas (7,200 sekundes). Iesniegšanas brīdī failam jābūt atpazīstamam kā MP3, WAV, Ogg, FLAC, MOV vai Matroska multividei ar audio plūsmu, un tā metadatos norādītajam ilgumam jābūt lielākam par nulli un ne lielākam par 7,200 sekundēm. Atpazīts fails, kas neiztur šīs pārbaudes, tiek noraidīts ar 422 unsupported_audio. Fails, ko nevar nolasīt nevienā no šiem formātiem, pašlaik var tikt noraidīts ar servera kļūdu (500); neiesniedziet šādu failu atkārtoti bez izmaiņām. Faila paplašinājums vien nenosaka saderību.

Šo pārbaužu izturēšana negarantē, ka audio varēs dekodēt. Audio tiek apstrādāts vienā vai divos kanālos. Fails ar vairāk nekā diviem audio kanāliem, fails, kura dekodētais audio ir ilgāks par 2 stundām, vai jebkurš cits fails, kura dekodēšana apstrādes laikā neizdodas, beidzas kā darbs ar statusu failed, parasti ar kodu decode_failed, un par to netiek iekasēta maksa. Pirms iesniegšanas pārveidojiet daudzkanālu audio par mono vai stereo.

Neobligātā valodas norāde ir runātās valodas divu vai trīs mazo burtu kods, piemēram, en. Ja nevēlaties sniegt norādi, izlaidiet lauku; api.multi.tel noraida tukšu virkni. Norāde vada apstrādi, taču netiek pārbaudīta atbalstīto valodu sarakstā, tāpēc izmantojiet derīgu runātās valodas kodu.

Iesniedziet transkripcijas darbu

Sūtiet JSON ar galveni Content-Type: application/json uz POST https://api.multi.tel/v3/speech_to_text. Pieprasījuma pamatdaļa var būt līdz 35 MiB, lai tajā ietilptu maksimālā izmēra fails pēc base64 kodēšanas; lielāka pamatdaļa tiek noraidīta ar 413.

Jebkurš cits JSON rekvizīts, tostarp idempotency_key, tiek noraidīts ar 400 invalid_transcription_request. Sūtiet atslēgu galvenē.

Idempotences atslēga

Katram iesniegumam nepieciešama Idempotency-Key galvene ar 1 līdz 190 rakstzīmēm. Izmantojiet ASCII burtus, ciparus, -, _, . un : bez atstarpēm sākumā vai beigās: saderības serveris apgriež apkārtējās atstarpju rakstzīmes un mēra atslēgu baitos, tāpēc citu rakstzīmju skaits abos serveros var atšķirties. Trūkstoša atslēga vai atslēga ar 191 vai vairāk rakstzīmēm tiek noraidīta ar 400.

Atslēgas ir piesaistītas jūsu kontam un runas pārvēršanai tekstā abos serveros un ar visiem jūsu konta autentifikācijas datiem. Atkārtoti nosūtot to pašu atslēgu ar to pašu failu un valodu, tiek atgriezts esošais darbs ar HTTP 200 un duplicate: true neatkarīgi no darba statusa un pat tad, ja apstrāde kopš darba izveides ir atjaunināta, bez atkārtotas maksas. Atkārtoti izmantojot atslēgu ar citu failu vai valodu, tiek atgriezts 409 idempotency_conflict. Jauna atslēga izveido jaunu darbu pat identiskam failam, un par to tiek iekasēta atsevišķa maksa, ja apstrāde tiek veiksmīgi pabeigta.

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'

Jauns darbs atgriež HTTP 202 ar tālāk parādītajiem laukiem, bet atkārtota nosūtīšana atgriež HTTP 200 ar pilnu darba objektu, kas aprakstīts sadaļā Lasiet transkripciju. Nolasiet darba ID — UUID — no data.id. Jauna darba atbilde izskatās šādi (identifikators un vērtības ir piemēri):

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

Kamēr darbs ir rindā vai tiek apstrādāts, durationSeconds, billedSeconds un costUsd ir aplēses no faila metadatiem. Galīgā maksa tiek aprēķināta pēc dekodētā ilguma.

Iesniegums var atgriezt arī 402 insufficient_balance, ja priekšapmaksas atlikums nevar segt šo darbu kopā ar citiem jūsu nepabeigtajiem darbiem, 429 transcription_queue_full, ja jūsu kontā vai pakalpojumā ir pārāk daudz nepabeigtu darbu, 429 audio_validation_busy, ja failu pārbaudes jauda ir pilnībā noslogota, un 503 paid_transcription_not_enabled, kamēr maksas transkripcija ir atspējota. Pēc atbildēm 429 un 503 mēģiniet vēlāk vēlreiz ar to pašu atslēgu.

Aprēķiniet tāmi, neveidojot darbu

Sūtiet to pašu JSON pamatdaļu uz POST https://api.multi.tel/v3/speech_to_text/estimate. Idempotences atslēga nav nepieciešama. Tāme pārbauda un izmēra failu, bet to netranskribē, neizveido darbu, nerezervē līdzekļus, nepārbauda atlikumu un neiekasē maksu no jūsu konta. Norāde language tiek pieņemta, bet neietekmē tāmi.

Veiksmīga tāme atgriež HTTP 200 ar laukiem estimate: true, charged: false, mode, realtime, durationSeconds, billedSeconds, pricePerMinuteUsd un costUsd objektā data. Tā izmanto faila metadatos norādīto ilgumu, bet par pabeigtu darbu maksa tiek aprēķināta pēc dekodētā ilguma, kas var atšķirties. Tāmēm tiek piemērotas tādas pašas failu pārbaudes kā iesniegumiem. Tās ir pieejamas tikai tad, kad maksas transkripcija ir iespējota (pretējā gadījumā 503 paid_transcription_not_enabled). Tās var atgriezt 429 audio_validation_busy, ja failu pārbaudes jauda ir pilnībā noslogota; pēc īsas pauzes mēģiniet vēlreiz.

Lasiet transkripciju

Periodiski izgūstiet GET /v3/speech_to_text/JOB_ID, kā aprakstīts darbu plūsmas ceļvedī. Darba objekts satur šādus laukus:

Transkripcijas un to laika zīmogi, valodu un kanālu apzīmējumi tiek veidoti automātiski, un to precizitāte netiek garantēta. Uztveriet katru kvalitātes karodziņu kā iemeslu pārskatīt rezultātu un salīdziniet svarīgus vārdus, skaitļus un saistības ar sākotnējo audio. Ilgstoši klusuma un ļoti klusi posmi tiek izlaisti un neveido segmentus. Rezultāti neidentificē atsevišķus runātājus. Ja rezultātā channelCount ir 2, katram segmentam channel ir A (pirmais jeb kreisais kanāls) vai B (otrais jeb labais kanāls). Tas nošķir runātājus tikai tad, ja katrs runātājs ir ierakstīts atsevišķā kanālā. Divkanālu audio tiek apmaksāts vienreiz pēc tā kopējā ilguma, nevis par katru kanālu. Mono rezultātos nav kanālu apzīmējumu.

api.multitel.net izmantošana

Saderības galapunkts POST https://api.multitel.net/v3/speech_to_text pieņem multipart/form-data ar audio faila daļu un neobligātu language lauku JSON lauka audioBase64 vietā. Tukša language vērtība tiek uzskatīta par norādes neesamību. Sūtiet to pašu Idempotency-Key galveni. Ja galvenes nav, šis serveris pieņem arī idempotency_key veidlapas lauku. Lauki ar nosaukumiem source, free, billing_source, realtime vai stream tiek noraidīti ar 400 unsupported_transcription_option; citi veidlapas lauki tiek ignorēti. Šis serveris atgriež arī šādas kļūdas:

• 400 idempotency_key_required, ja atslēgas nav vai tā ir pārāk gara.
• 400 audio_upload_required, ja augšupielādes nav vai tā nav saņemta pilnībā.
• 400 invalid_language nederīgai valodai.
• 413 invalid_audio_size tukšam vai pārāk lielam failam.
• 400 invalid_job nepareizi formatētam darba ID.

Šī servera runas pārvēršanas tekstā pakalpojuma atbildēs tiek izmantots ietvars {"status":{"code":HTTP_STATUS},"response":{...}}. Ņemiet vērā, ka status ir objekts, nevis virkne. Veiksmes gadījumā response satur tādu pašu objektu kā data primārajā serverī, tāpēc darba ID ir response.id. Kļūdas gadījumā response.code satur kļūdas kodu; ziņojums vai pieprasījuma ID netiek iekļauts. Autentifikācijas kļūdas (401) atgriež servera vispārējā pierakstīšanās pārbaude, un to pamatdaļa var atšķirties, tāpēc pirms parsēšanas pārbaudiet HTTP statusu. Nemainiet augšupielādes kodējumu vai atbildes parsētāju starp serveriem.

Lai šajā serverī iegūtu tāmi, ar POST nosūtiet tos pašus multipart laukus uz /v3/speech_to_text/estimate. Idempotences atslēga nav nepieciešama, un tāme atrodas objektā 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'