API voor spraak-naar-tekst

Deze API verwerkt voltooide audiobestanden als transcriptietaken in een wachtrij. Dien een bestand in, bewaar de teruggegeven taak-ID en vraag de taak op totdat de verwerking klaar is. Verstuur elk verzoek via HTTPS met inloggegevens voor je account: HTTP Basic-inloggegevens zoals in de voorbeelden, of een API-token zoals beschreven onder Authenticatie. Bewaar inloggegevens op je server.

Endpoints

Twee API-hosts, https://api.multi.tel en de compatibiliteitshost https://api.multitel.net, delen dezelfde accountgebonden taken, idempotentiesleutels, limieten en facturering. Ze verschillen in uploadcodering en antwoordstructuur. Gebruik daarom consequent één host met een bijpassende parser.

Op api.multi.tel is elk pad ook beschikbaar met het voorvoegsel /v1/speech-to-text in plaats van /v3/speech_to_text, bijvoorbeeld POST /v1/speech-to-text/estimate. Gebruik op api.multitel.net de paden met /v3/speech_to_text.

Het antwoord met service-informatie vermeldt mode (batch), realtime (false), paidEnabled (of nieuwe betaalde aanvragen momenteel worden geaccepteerd), pricePerMinuteUsd (0.005), billingUnit (audio_second), maxAudioSeconds (7200) en maxUploadBytes (26214400), samen met een korte beschrijving in description. Het opvragen is gratis en werkt ook wanneer betaalde aanvragen zijn uitgeschakeld; het geeft alleen 503 met transcription_unavailable terug als de hele service niet beschikbaar is.

Een audiobestand voorbereiden

Gebruik een voltooid audiobestand van maximaal 25 MiB (26,214,400 bytes) en maximaal 2 uur (7,200 seconden). Bij indiening moet het bestand worden herkend als MP3-, WAV-, Ogg-, FLAC-, MOV- of Matroska-media met een audiostream en een duur in de metadata van meer dan nul en maximaal 7,200 seconden. Een herkend bestand dat niet aan deze controles voldoet, wordt geweigerd met 422 en unsupported_audio. Een bestand dat niet als een van deze formaten kan worden gelezen, kan momenteel in plaats daarvan worden geweigerd met een serverfout (500); dien zo’n bestand niet ongewijzigd opnieuw in. Alleen een bestandsextensie bewijst geen compatibiliteit.

Deze controles doorstaan garandeert niet dat de audio kan worden gedecodeerd. Audio wordt verwerkt als één of twee kanalen. Een bestand met meer dan twee audiokanalen, een bestand waarvan de gedecodeerde audio langer is dan 2 uur, of een ander bestand dat tijdens de verwerking niet kan worden gedecodeerd, eindigt als een taak met de status failed, meestal met decode_failed, en wordt niet in rekening gebracht. Zet meerkanaalsaudio vóór indiening om naar mono of stereo.

De optionele taalhint is een taalcode van twee of drie kleine letters voor de gesproken taal, zoals en. Laat het veld weg als je geen hint wilt geven; api.multi.tel weigert een lege tekenreeks. De hint stuurt de verwerking, maar wordt niet gecontroleerd aan de hand van een lijst met ondersteunde talen. Gebruik daarom een geldige code voor de gesproken taal.

Een transcriptietaak indienen

Verstuur JSON met Content-Type: application/json naar POST https://api.multi.tel/v3/speech_to_text. De verzoekbody mag maximaal 35 MiB zijn, zodat een bestand van de maximale grootte na base64-codering past; een grotere body wordt geweigerd met 413.

Elke andere JSON-eigenschap, waaronder idempotency_key, wordt geweigerd met 400 en invalid_transcription_request. Verstuur de sleutel als header.

Idempotentiesleutel

Elke indiening vereist een Idempotency-Key-header van 1 tot 190 tekens. Gebruik ASCII-letters, cijfers, -, _, . en :, zonder spaties aan het begin of einde: de compatibiliteitshost verwijdert omringende witruimte en meet de sleutel in bytes, waardoor andere tekens per host anders kunnen worden geteld. Een ontbrekende sleutel of een sleutel van 191 of meer tekens wordt geweigerd met 400.

Sleutels gelden voor je account en voor spraak-naar-tekst, over beide hosts en alle inloggegevens van je account heen. Dezelfde sleutel opnieuw versturen met hetzelfde bestand en dezelfde taal geeft de bestaande taak terug met HTTP 200 en duplicate: true, ongeacht de status en ook als de verwerking sinds het aanmaken van de taak is bijgewerkt, zonder nieuwe kosten. Hergebruik van een sleutel met een ander bestand of een andere taal geeft 409 en idempotency_conflict. Een nieuwe sleutel maakt zelfs voor een identiek bestand een nieuwe taak aan, met afzonderlijke kosten als de verwerking slaagt.

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'

Een nieuwe taak geeft HTTP 202 met de hieronder getoonde velden terug. Een herhaald verzoek geeft HTTP 200 met het volledige taakobject beschreven onder Het transcript opvragen. Lees de taak-ID, een UUID, uit data.id. Het antwoord voor een nieuwe taak ziet er zo uit (de identificatie en waarden zijn voorbeelden):

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

Zolang een taak in de wachtrij staat of wordt uitgevoerd, zijn durationSeconds, billedSeconds en costUsd schattingen uit de metadata van het bestand. De uiteindelijke kosten worden gebaseerd op de gedecodeerde duur.

Een indiening kan ook 402 met insufficient_balance teruggeven als het prepaidtegoed niet voldoende is voor de taak samen met je andere openstaande taken, 429 met transcription_queue_full als je account of de service te veel openstaande taken heeft, 429 met audio_validation_busy als de capaciteit voor bestandsvalidatie volledig wordt gebruikt, en 503 met paid_transcription_not_enabled als betaalde transcriptie is uitgeschakeld. Probeer na antwoorden met 429 en 503 later opnieuw met dezelfde sleutel.

Een schatting zonder een taak aan te maken

Verstuur dezelfde JSON-body naar POST https://api.multi.tel/v3/speech_to_text/estimate. Een idempotentiesleutel is niet nodig. Een schatting valideert en meet het bestand, maar transcribeert het niet, maakt geen taak aan, reserveert geen tegoed, controleert je saldo niet en brengt geen kosten in rekening. Een hint in language wordt geaccepteerd, maar heeft geen invloed op de schatting.

Een geslaagde schatting geeft HTTP 200 met estimate: true, charged: false, mode, realtime, durationSeconds, billedSeconds, pricePerMinuteUsd en costUsd onder data terug. Hiervoor wordt de duur uit de metadata van het bestand gebruikt, terwijl een voltooide taak wordt afgerekend op basis van de gedecodeerde duur, die kan afwijken. Schattingen voeren dezelfde bestandscontroles uit als indieningen. Ze zijn alleen beschikbaar wanneer betaalde transcriptie is ingeschakeld (anders 503 met paid_transcription_not_enabled). Ze kunnen 429 met audio_validation_busy teruggeven als de capaciteit voor bestandsvalidatie volledig wordt gebruikt; probeer het na kort wachten opnieuw.

Het transcript opvragen

Vraag regelmatig GET /v3/speech_to_text/JOB_ID op zoals beschreven in de handleiding voor de taakworkflow. Het taakobject bevat deze velden:

Transcripten en hun tijdstempels, taal- en kanaallabels worden automatisch gemaakt en zijn niet gegarandeerd nauwkeurig. Zie elke kwaliteitsmarkering als een reden om het resultaat te controleren en vergelijk belangrijke namen, getallen en toezeggingen met de oorspronkelijke audio. Lange stiltes en zeer stille passages worden overgeslagen en leveren geen segmenten op. Resultaten identificeren geen afzonderlijke sprekers. Wanneer een resultaat een channelCount van 2 vermeldt, heeft elk segment een channel met de waarde A (het eerste, of linker, kanaal) of B (het tweede, of rechter, kanaal). Dit scheidt sprekers alleen als elke spreker op een afzonderlijk kanaal is opgenomen. Tweekanaalsaudio wordt één keer gefactureerd op basis van de verstreken duur, niet per kanaal. Monoresultaten hebben geen kanaallabels.

api.multitel.net gebruiken

Het compatibiliteitseindpunt POST https://api.multitel.net/v3/speech_to_text accepteert multipart/form-data met een bestandsdeel genaamd audio en een optioneel veld language, in plaats van JSON met audioBase64. Een lege waarde voor language geldt als geen hint. Verstuur dezelfde Idempotency-Key-header. Als de header ontbreekt, accepteert deze host ook een formulierveld idempotency_key. Velden met de naam source, free, billing_source, realtime of stream worden geweigerd met 400 en unsupported_transcription_option; andere formuliervelden worden genegeerd. Deze host geeft ook de volgende fouten terug:

• 400 idempotency_key_required bij een ontbrekende of te lange sleutel.
• 400 audio_upload_required als het bestand ontbreekt of niet volledig is ontvangen.
• 400 invalid_language bij een ongeldige taal.
• 413 invalid_audio_size bij een leeg of te groot bestand.
• 400 invalid_job bij een onjuist gevormde taak-ID.

Antwoorden van de spraak-naar-tekstservice op deze host gebruiken de antwoordstructuur {"status":{"code":HTTP_STATUS},"response":{...}}. Let op: status is een object, geen tekenreeks. Bij succes bevat response hetzelfde object als data op de primaire host. De taak-ID is dus response.id. Bij een fout bevat response.code de foutcode; er wordt geen bericht of verzoek-ID opgenomen. Authenticatiefouten (401) komen van de algemene aanmeldcontrole van de host en kunnen een andere body hebben. Controleer daarom de HTTP-status voordat je het antwoord parseert. Verwissel de uploadcodering of antwoordparser niet tussen hosts.

Verstuur voor een schatting op deze host dezelfde multipart-velden via POST naar /v3/speech_to_text/estimate. Een idempotentiesleutel is niet nodig en de schatting staat onder 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'