Puheesta tekstiksi -API

Tämä API litteroi valmiita äänitiedostoja jonossa käsiteltävinä töinä. Lähetä tiedosto, tallenna palautettu työn tunniste ja hae työn tiedot, kunnes käsittely on valmis. Lähetä kaikki pyynnöt HTTPS-yhteydellä käyttäen tilisi tunnistetietoja: esimerkkien mukaisia HTTP Basic -tunnistetietoja tai API-tunnusta, kuten kuvataan kohdassa Todennus. Säilytä tunnistetiedot palvelimellasi.

Päätepisteet

Kaksi API-palvelinta, https://api.multi.tel ja yhteensopivuuspalvelin https://api.multitel.net, jakavat samat tilikohtaiset työt, idempotenssiavaimet, rajoitukset ja laskutuksen. Lähetyksen koodaus ja vastauksen rakenne eroavat, joten käytä johdonmukaisesti yhtä palvelinta ja siihen sopivaa jäsennintä.

Palvelimella api.multi.tel kaikki polut ovat käytettävissä myös etuliitteellä /v1/speech-to-text seuraavan sijasta: /v3/speech_to_text, esimerkiksi POST /v1/speech-to-text/estimate. Palvelimella api.multitel.net käytä /v3/speech_to_text-polkuja.

Palvelutietovastaus sisältää kentät mode (batch), realtime (false), paidEnabled (hyväksytäänkö uusia maksullisia töitä tällä hetkellä), pricePerMinuteUsd (0.005), billingUnit (audio_second), maxAudioSeconds (7200) ja maxUploadBytes (26214400) sekä lyhyen kuvauksen kentässä description. Tietojen haku on maksutonta ja toimii myös silloin, kun maksullisten töiden lähetys on poistettu käytöstä; se palauttaa 503 transcription_unavailable vain, jos koko palvelu on poissa käytöstä.

Valmistele äänitiedosto

Käytä valmista äänitiedostoa, jonka koko on enintään 25 MiB (26,214,400 tavua) ja kesto enintään 2 tuntia (7,200 sekuntia). Lähetettäessä tiedosto on tunnistettava MP3-, WAV-, Ogg-, FLAC-, MOV- tai Matroska-mediaksi, joka sisältää äänivirran ja jonka metatiedoissa kesto on suurempi kuin nolla ja enintään 7,200 sekuntia. Tunnistettu tiedosto, joka ei läpäise näitä tarkistuksia, hylätään vastauksella 422 unsupported_audio. Tiedosto, jota ei voida lukea missään näistä muodoista, voidaan tällä hetkellä hylätä sen sijaan palvelinvirheellä (500); älä lähetä tällaista tiedostoa uudelleen muuttamattomana. Pelkkä tiedostopääte ei osoita yhteensopivuutta.

Näiden tarkistusten läpäisy ei takaa, että ääni voidaan purkaa. Ääni käsitellään yhtenä tai kahtena kanavana. Tiedosto, jossa on enemmän kuin kaksi äänikanavaa, jonka purettu ääni kestää yli 2 tuntia tai jonka purkaminen muutoin epäonnistuu käsittelyssä, päätyy tilaan failed, yleensä virhekoodilla decode_failed, eikä siitä veloiteta. Muunna monikanavainen ääni monoksi tai stereoksi ennen lähettämistä.

Valinnainen kielivihje on puhutun kielen kaksi- tai kolmikirjaiminen pienaakkoskoodi, kuten en. Jos et halua antaa vihjettä, jätä kenttä pois; api.multi.tel hylkää tyhjän merkkijonon. Vihje ohjaa käsittelyä, mutta sitä ei verrata tuettujen kielten luetteloon, joten käytä puhutun kielen kelvollista koodia.

Lähetä litterointityö

Lähetä JSON otsakkeella Content-Type: application/json osoitteeseen POST https://api.multi.tel/v3/speech_to_text. Pyynnön runko voi olla enintään 35 MiB, jotta enimmäiskokoinen tiedosto mahtuu siihen base64-koodauksen jälkeen; suurempi runko hylätään vastauksella 413.

Kaikki muut JSON-ominaisuudet, mukaan lukien idempotency_key, hylätään vastauksella 400 invalid_transcription_request. Lähetä avain otsakkeessa.

Idempotenssiavain

Jokainen lähetys vaatii Idempotency-Key-otsakkeen, jossa on 1–190 merkkiä. Käytä ASCII-kirjaimia, numeroita, -, _, . ja : ilman alku- tai loppuvälilyöntejä: yhteensopivuuspalvelin poistaa ympäröivät tyhjemerkit ja mittaa avaimen tavuina, joten palvelimet voivat laskea muut merkit eri tavoin. Puuttuva avain tai vähintään 191 merkin avain hylätään vastauksella 400.

Avaimet rajataan tiliisi ja puheentunnistukseen molemmilla palvelimilla ja kaikilla tilisi tunnistetiedoilla. Saman avaimen uudelleenlähetys samalla tiedostolla ja kielellä palauttaa olemassa olevan työn vastauksella HTTP 200 ja duplicate: true työn tilasta riippumatta ja vaikka käsittelyä olisi päivitetty työn luomisen jälkeen, ilman uutta veloitusta. Avaimen uudelleenkäyttö eri tiedostolla tai kielellä palauttaa 409 idempotency_conflict. Uusi avain luo uuden työn myös samanlaiselle tiedostolle, ja siitä veloitetaan erikseen, jos käsittely valmistuu onnistuneesti.

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'

Uusi työ palauttaa HTTP 202 ja alla esitetyt kentät. Uudelleenlähetys palauttaa HTTP 200 ja koko työobjektin, joka kuvataan kohdassa Lue litterointi. Lue työn UUID-tunniste kentästä data.id. Uuden työn vastaus näyttää tältä (tunniste ja arvot ovat esimerkkejä):

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

Kun työ on jonossa tai käynnissä, durationSeconds, billedSeconds ja costUsd ovat arvioita tiedoston metatiedoista. Lopullinen veloitus perustuu purettuun kestoon.

Lähetys voi palauttaa myös 402 insufficient_balance, kun ennakkomaksusaldo ei riitä työn ja muiden keskeneräisten töidesi kattamiseen, 429 transcription_queue_full, kun tililläsi tai palvelussa on liikaa keskeneräisiä töitä, 429 audio_validation_busy, kun tiedostojen tarkistuskapasiteetti on täynnä, ja 503 paid_transcription_not_enabled, kun maksullinen litterointi on poistettu käytöstä. Yritä 429- ja 503-vastausten jälkeen myöhemmin uudelleen samalla avaimella.

Arvioi luomatta työtä

Lähetä sama JSON-runko osoitteeseen POST https://api.multi.tel/v3/speech_to_text/estimate. Idempotenssiavainta ei tarvita. Arvio tarkistaa ja mittaa tiedoston, mutta ei litteroi sitä, luo työtä, varaa varoja, tarkista saldoasi eikä veloita tiliäsi. language-vihje hyväksytään, mutta se ei vaikuta arvioon.

Onnistunut arvio palauttaa HTTP 200 ja kentät estimate: true, charged: false, mode, realtime, durationSeconds, billedSeconds, pricePerMinuteUsd ja costUsd objektin data sisällä. Se käyttää tiedoston metatietojen kestoa, kun taas valmistuneen työn veloitus perustuu purettuun kestoon, joka voi poiketa siitä. Arvioinnissa käytetään samoja tiedostotarkistuksia kuin lähetyksissä. Arviot ovat käytettävissä vain, kun maksullinen litterointi on käytössä (muutoin 503 paid_transcription_not_enabled). Ne voivat palauttaa 429 audio_validation_busy, kun tiedostojen tarkistuskapasiteetti on täynnä; yritä lyhyen odotuksen jälkeen uudelleen.

Lue litterointi

Kysy toistuvasti GET /v3/speech_to_text/JOB_ID seuraavan ohjeen mukaisesti: Työnkulun opas. Työobjekti sisältää nämä kentät:

Litteroinnit sekä niiden aikaleimat, kielimerkinnät ja kanavamerkinnät tuotetaan automaattisesti, eikä niiden tarkkuutta taata. Pidä jokaista laatumerkintää syynä tuloksen tarkistamiseen ja vertaa tärkeitä nimiä, numeroita ja sitoumuksia alkuperäiseen ääneen. Pitkät hiljaisuudet ja hyvin hiljaiset kohdat ohitetaan, eikä niistä muodostu segmenttejä. Tulokset eivät tunnista yksittäisiä puhujia. Kun tuloksen channelCount on 2, jokaisen segmentin channel on A (ensimmäinen eli vasen kanava) tai B (toinen eli oikea kanava). Tämä erottaa puhujat vain, jos kukin puhuja on tallennettu erilliselle kanavalle. Kaksikanavaisesta äänestä laskutetaan kerran sen kuluneen keston perusteella, ei kanavakohtaisesti. Monotuloksissa ei ole kanavamerkintöjä.

api.multitel.net-palvelimen käyttö

Yhteensopivuuspäätepiste POST https://api.multitel.net/v3/speech_to_text hyväksyy multipart/form-data-pyynnön, jossa on audio-tiedosto-osa ja valinnainen language-kenttä, JSON-kentän audioBase64 sijasta. Tyhjä language-arvo käsitellään vihjeen puuttumisena. Lähetä sama Idempotency-Key-otsake. Jos otsake puuttuu, tämä palvelin hyväksyy myös idempotency_key-lomakekentän. Kentät nimeltä source, free, billing_source, realtime tai stream hylätään vastauksella 400 unsupported_transcription_option; muut lomakekentät ohitetaan. Tämä palvelin palauttaa myös nämä virheet:

• 400 idempotency_key_required, jos avain puuttuu tai on liian pitkä.
• 400 audio_upload_required, jos lähetettävä tiedosto puuttuu tai sitä ei ole vastaanotettu kokonaan.
• 400 invalid_language virheelliselle kielelle.
• 413 invalid_audio_size tyhjälle tai liian suurelle tiedostolle.
• 400 invalid_job virheellisesti muotoillulle työn tunnisteelle.

Tämän palvelimen puheentunnistuspalvelun vastaukset käyttävät rakennetta {"status":{"code":HTTP_STATUS},"response":{...}}. Huomaa, että status on objekti, ei merkkijono. Onnistuneessa vastauksessa response sisältää saman objektin kuin data ensisijaisella palvelimella, joten työn tunniste on response.id. Virhetilanteessa response.code sisältää virhekoodin; viestiä tai pyynnön tunnistetta ei ole mukana. Todennusvirheet (401) palautetaan palvelimen yleisestä kirjautumistarkistuksesta, ja niiden runko voi olla erilainen, joten tarkista HTTP-tila ennen jäsentämistä. Älä vaihda lähetyskoodausta tai vastauksen jäsennintä palvelinten välillä.

Tämän palvelimen arviota varten lähetä samat multipart-kentät POST-pyynnöllä osoitteeseen /v3/speech_to_text/estimate. Idempotenssiavainta ei tarvita, ja arvio on objektissa 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'