API för tal-till-text

Detta API transkriberar färdiga ljudfiler som köade jobb. Skicka in en fil, spara det returnerade jobb-ID:t och hämta jobbet tills bearbetningen är klar. Skicka varje begäran via HTTPS med inloggningsuppgifter för ditt konto, antingen HTTP Basic-uppgifter som i exemplen eller en API-token, enligt avsnittet Autentisering. Behåll inloggningsuppgifterna på din server.

Slutpunkter

De två API-värdarna, https://api.multi.tel och kompatibilitetsvärden https://api.multitel.net, delar samma kontobundna jobb, idempotensnycklar, gränser och avgifter. De skiljer sig åt i uppladdningskodning och svarsstruktur, så använd samma värd konsekvent med en matchande svarstolk.

På api.multi.tel finns varje sökväg även med prefixet /v1/speech-to-text i stället för /v3/speech_to_text, till exempel POST /v1/speech-to-text/estimate. På api.multitel.net använder du sökvägarna med /v3/speech_to_text.

Svaret med tjänsteinformation anger mode (batch), realtime (false), paidEnabled (om nya betalda jobb för närvarande kan skickas in), pricePerMinuteUsd (0.005), billingUnit (audio_second), maxAudioSeconds (7200) och maxUploadBytes (26214400), tillsammans med en kort description. Det är gratis att läsa informationen, och det fungerar även när inskickning av betalda jobb är avstängd; svaret blir 503 transcription_unavailable endast när hela tjänsten är otillgänglig.

Förbered en ljudfil

Använd en färdig ljudfil på högst 25 MiB (26,214,400 byte) och högst 2 timmar (7,200 sekunder). Vid inskickning måste filen kännas igen som MP3-, WAV-, Ogg-, FLAC-, MOV- eller Matroska-media med en ljudström och en längd i metadata som är större än noll och högst 7,200 sekunder. En igenkänd fil som inte klarar kontrollerna avvisas med 422 unsupported_audio. En fil som inte kan läsas som något av dessa format kan för närvarande i stället avvisas med ett serverfel (500); skicka inte in en sådan fil igen utan att ändra den. Filändelsen räcker inte för att avgöra kompatibilitet.

Godkända kontroller garanterar inte att ljudet går att avkoda. Ljud bearbetas som en eller två kanaler. En fil med fler än två ljudkanaler, en fil vars avkodade ljud är längre än 2 timmar eller en annan fil som inte kan avkodas under bearbetningen slutar som ett jobb med status failed, vanligen med decode_failed, och debiteras inte. Konvertera flerkanalsljud till mono eller stereo innan du skickar in det.

Den valfria språkledtråden är en kod med två eller tre gemener för det talade språket, till exempel en. Utelämna fältet om du inte vill ange någon ledtråd; api.multi.tel avvisar en tom sträng. Ledtråden vägleder bearbetningen men kontrolleras inte mot en lista över språk som stöds, så använd en giltig kod för det talade språket.

Skicka in ett transkriberingsjobb

Skicka JSON med Content-Type: application/json till POST https://api.multi.tel/v3/speech_to_text. Begärandekroppen får vara högst 35 MiB, vilket rymmer en fil av maximal storlek efter base64-kodning; en större kropp avvisas med 413.

Alla andra JSON-egenskaper, inklusive idempotency_key, avvisas med 400 invalid_transcription_request. Skicka nyckeln som ett HTTP-huvud.

Idempotensnyckel

Varje inskickning kräver HTTP-huvudet Idempotency-Key med 1 till 190 tecken. Använd ASCII-bokstäver, siffror, -, _, . och :, utan inledande eller avslutande blanktecken: kompatibilitetsvärden tar bort omgivande blanktecken och mäter nyckeln i byte, så andra tecken kan räknas olika av värdarna. En nyckel som saknas eller har 191 eller fler tecken avvisas med 400.

Nycklarna är knutna till ditt konto och till tal-till-text på båda värdarna och för alla kontots inloggningsuppgifter. Om du skickar samma nyckel igen med samma fil och språk returneras det befintliga jobbet med HTTP 200 och duplicate: true, oavsett status och även om bearbetningen har uppdaterats sedan jobbet skapades, utan ytterligare avgift. Om en nyckel återanvänds med en annan fil eller ett annat språk returneras 409 idempotency_conflict. En ny nyckel skapar ett nytt jobb även för en identisk fil, med en separat avgift om bearbetningen slutförs utan fel.

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'

Ett nytt jobb returnerar HTTP 202 med fälten nedan, och en upprepad begäran returnerar HTTP 200 med det fullständiga jobbobjektet som beskrivs i Läs transkriptionen. Läs jobb-ID:t, ett UUID, från data.id. Ett nytt jobbs svar ser ut så här (identifieraren och värdena är exempel):

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

Medan ett jobb köar eller körs är durationSeconds, billedSeconds och costUsd uppskattningar från filens metadata. Den slutliga avgiften baseras på den avkodade längden.

En inskickning kan också returnera 402 insufficient_balance när ett förbetalt saldo inte täcker jobbet tillsammans med dina andra utestående jobb, 429 transcription_queue_full när ditt konto eller tjänsten har för många utestående jobb, 429 audio_validation_busy när filvalideringen har nått sin kapacitet och 503 paid_transcription_not_enabled när betald transkribering är avstängd. Försök igen senare med samma nyckel efter svar med 429 och 503.

Beräkna en uppskattning utan att skapa ett jobb

Skicka samma JSON-kropp till POST https://api.multi.tel/v3/speech_to_text/estimate. Ingen idempotensnyckel krävs. En uppskattning validerar och mäter filen men transkriberar den inte, skapar inget jobb, reserverar inga medel, kontrollerar inte ditt saldo och debiterar inte ditt konto. En ledtråd i language godtas men påverkar inte uppskattningen.

En lyckad uppskattning returnerar HTTP 200 med estimate: true, charged: false, mode, realtime, durationSeconds, billedSeconds, pricePerMinuteUsd och costUsd under data. Den använder längden i filens metadata, medan ett slutfört jobb debiteras efter den avkodade längden, som kan skilja sig. Uppskattningar använder samma filkontroller som inskickade jobb. De är endast tillgängliga när betald transkribering är aktiverad (annars 503 paid_transcription_not_enabled). De kan returnera 429 audio_validation_busy när filvalideringen har nått sin kapacitet; vänta en kort stund och försök igen.

Läs transkriptionen

Kontrollera regelbundet GET /v3/speech_to_text/JOB_ID enligt guiden för jobbflödet. Jobbobjektet innehåller följande fält:

Transkriptioner och deras tidsstämplar, språkmarkeringar och kanalmarkeringar skapas automatiskt och garanteras inte vara korrekta. Se varje kvalitetsflagga som en anledning att granska resultatet och jämför viktiga namn, tal och utfästelser med originalljudet. Långa tystnader och mycket svaga passager hoppas över och ger inga segment. Resultaten identifierar inte enskilda talare. När ett resultat anger channelCount som 2 har varje segment channel som A (den första eller vänstra kanalen) eller B (den andra eller högra kanalen). Detta skiljer talare åt endast när varje talare har spelats in på en separat kanal. Tvåkanalsljud debiteras en gång efter förfluten tid, inte per kanal. Monoresultat har inga kanalmarkeringar.

Använda api.multitel.net

Kompatibilitetsslutpunkten POST https://api.multitel.net/v3/speech_to_text tar emot multipart/form-data med en fildel som heter audio och ett valfritt fält som heter language i stället för JSON-fältet audioBase64. Ett tomt värde för language behandlas som att ingen ledtråd anges. Skicka samma HTTP-huvud Idempotency-Key. Om huvudet saknas godtar värden även formulärfältet idempotency_key. Fält med namnen source, free, billing_source, realtime eller stream avvisas med 400 unsupported_transcription_option; andra formulärfält ignoreras. Värden returnerar även följande fel:

• 400 idempotency_key_required när nyckeln saknas eller är för lång.
• 400 audio_upload_required när uppladdningen saknas eller inte har tagits emot helt.
• 400 invalid_language när språket är ogiltigt.
• 413 invalid_audio_size när filen är tom eller för stor.
• 400 invalid_job när jobb-ID:t har fel format.

Svar från värdens tal-till-text-tjänst använder strukturen {"status":{"code":HTTP_STATUS},"response":{...}}. Observera att status är ett objekt, inte en sträng. Vid ett lyckat svar innehåller response samma objekt som data på den primära värden, så jobb-ID:t är response.id. Vid fel innehåller response.code felkoden; inget meddelande eller begärande-ID ingår. Autentiseringsfel (401) returneras av värdens allmänna inloggningskontroll och kan ha en annan kropp, så kontrollera HTTP-statusen innan svaret tolkas. Byt inte uppladdningskodning eller svarstolk mellan värdarna.

För en uppskattning på den här värden skickar du samma multipart-fält med POST till /v3/speech_to_text/estimate. Ingen idempotensnyckel krävs, och uppskattningen finns under 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'