Beszédből szöveg API

Ez az API befejezett hangfájlokat ír át sorba állított feladatokként. Küldjön be egy fájlt, őrizze meg a visszakapott feladatazonosítót, és kérdezze le a feladatot a feldolgozás befejezéséig. Minden kérést HTTPS-en, a fiókjához tartozó hitelesítő adatokkal küldjön: a példákban látható HTTP Basic-hitelesítéssel vagy API-tokennel, a következő szakasz szerint: Hitelesítés. Tartsa a hitelesítő adatokat a szerverén.

Végpontok

A két API-hoszt, https://api.multi.tel és a kompatibilitási hoszt, https://api.multitel.net, ugyanazokat a fiókhoz tartozó feladatokat, idempotenciakulcsokat, korlátokat és számlázást használja. A feltöltési kódolásuk és a válaszok borítékformátuma eltér, ezért következetesen ugyanazt a hosztot használja a hozzá illő válaszfeldolgozóval.

A(z) api.multi.tel hoszton minden elérési út a következő előtaggal is használható: /v1/speech-to-text a következő helyett: /v3/speech_to_text, például: POST /v1/speech-to-text/estimate. A(z) api.multitel.net hoszton ezeket az elérési utakat használja: /v3/speech_to_text.

A szolgáltatásadatokat tartalmazó válasz a következőket adja meg: mode (batch), realtime (false), paidEnabled (jelenleg fogad-e új fizetős beküldéseket), pricePerMinuteUsd (0.005), billingUnit (audio_second), maxAudioSeconds (7200) és maxUploadBytes (26214400), továbbá egy rövid leírást a következő mezőben: description. A lekérdezés ingyenes, és akkor is működik, ha a fizetős beküldések le vannak tiltva; 503 transcription_unavailable választ csak akkor ad, ha a teljes szolgáltatás nem érhető el.

Hangfájl előkészítése

Legfeljebb 25 MiB (26,214,400 bájt) méretű és legfeljebb 2 óra (7,200 másodperc) hosszú, befejezett hangfájlt használjon. Beküldéskor a fájlnak hangfolyamot tartalmazó MP3, WAV, Ogg, FLAC, MOV vagy Matroska médiafájlként felismerhetőnek kell lennie, és a metaadataiban szereplő időtartamnak nullánál nagyobbnak, de legfeljebb 7,200 másodpercnek kell lennie. A felismert, de ezeken az ellenőrzéseken nem megfelelő fájlt 422 unsupported_audio hibával utasítja el a szolgáltatás. Ha a fájl egyik ilyen formátumként sem olvasható, jelenleg szerverhiba (500) is lehet a válasz; az ilyen fájlt ne küldje be változtatás nélkül újra. A fájlkiterjesztés önmagában nem igazolja a kompatibilitást.

Ezen ellenőrzések teljesítése nem garantálja, hogy a hang dekódolható. A feldolgozás egy vagy két hangcsatornával történik. A kettőnél több hangcsatornát tartalmazó fájl, a dekódolás után 2 óránál hosszabb hang, illetve bármely más, feldolgozás közben nem dekódolható fájl feladatának végállapota failed lesz, jellemzően a következő hibával: decode_failed, és nem számítunk fel érte díjat. A többcsatornás hangot beküldés előtt alakítsa monóvá vagy sztereóvá.

A nem kötelező nyelvi jelzés a beszélt nyelv kisbetűs, két- vagy hárombetűs kódja, például en. Ha nem kíván nyelvi jelzést megadni, hagyja ki a mezőt; a(z) api.multi.tel elutasítja az üres karakterláncot. A jelzés segíti a feldolgozást, de nem ellenőrizzük a támogatott nyelvek listájával szemben, ezért a beszélt nyelv érvényes kódját használja.

Átírási feladat beküldése

Küldjön JSON-t a(z) Content-Type: application/json fejléc használatával ide: POST https://api.multi.tel/v3/speech_to_text. A kérés törzse legfeljebb 35 MiB lehet, így a maximális méretű fájl base64-kódolás után is elfér benne; a nagyobb törzset 413 válasszal utasítja el a szolgáltatás.

Minden más JSON-tulajdonságot, beleértve a(z) idempotency_key tulajdonságot is, 400 invalid_transcription_request hibával utasít el a szolgáltatás. A kulcsot fejlécként küldje.

Idempotenciakulcs

Minden beküldéshez szükséges egy Idempotency-Key fejléc 1 és 190 karakter közötti értékkel. ASCII-betűket, számjegyeket, valamint -, _, . és : karaktereket használjon, kezdő és záró szóköz nélkül: a kompatibilitási hoszt eltávolítja a környező térközkaraktereket, és bájtokban méri a kulcsot, ezért a többi karaktert a két hoszt eltérően számolhatja. A hiányzó vagy legalább 191 karakteres kulcsot 400 válasszal utasítja el a szolgáltatás.

A kulcsok az Ön fiókjához és a beszédből szöveg szolgáltatáshoz tartoznak, mindkét hoszton és a fiók összes hitelesítő adatára kiterjedően. Ugyanannak a kulcsnak ugyanazzal a fájllal és nyelvvel történő újraküldése a meglévő feladatot adja vissza HTTP 200 válasszal és duplicate: true jelzéssel, újabb díj nélkül, bármilyen állapotú a feladat, és akkor is, ha a feldolgozás a feladat létrehozása óta frissült. A kulcs más fájllal vagy nyelvvel való újrafelhasználása 409 idempotency_conflict hibát ad. Új kulcs esetén azonos fájlból is új feladat jön létre, amelyért sikeres feldolgozás esetén külön díjat számítunk 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'

Az új feladat HTTP 202 választ ad az alább látható mezőkkel, az ismételt kérés pedig HTTP 200 választ a teljes feladatobjektummal, amelyet a következő szakasz ismertet: Az átirat lekérdezése. A feladat UUID formátumú azonosítóját a(z) data.id mezőből olvassa ki. Az új feladat válasza a következőképpen néz ki (az azonosító és az értékek példák):

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

Amíg a feladat sorban áll vagy fut, a(z) durationSeconds, billedSeconds és costUsd mezők a fájl metaadataiból származó becslések. A végleges díj a dekódolt időtartamon alapul.

A beküldés 402 insufficient_balance hibát is adhat, ha a feltöltött egyenleg nem fedezi a feladatot a többi függőben lévő feladattal együtt, 429 transcription_queue_full hibát, ha a fiókban vagy a szolgáltatásban túl sok függőben lévő feladat van, 429 audio_validation_busy hibát, ha a fájlellenőrzés kapacitása betelt, valamint 503 paid_transcription_not_enabled hibát, amíg a fizetős átírás le van tiltva. 429 és 503 válasz esetén később, ugyanazzal a kulccsal próbálkozzon újra.

Becslés feladat létrehozása nélkül

Ugyanazt a JSON-törzset küldje ide: POST https://api.multi.tel/v3/speech_to_text/estimate. Idempotenciakulcs nem szükséges. A becslés ellenőrzi és megméri a fájlt, de nem írja át, nem hoz létre feladatot, nem foglal le összeget, nem ellenőrzi az egyenleget, és nem terheli meg a fiókját. A(z) language nyelvi jelzést elfogadja, de az nem befolyásolja a becslést.

A sikeres becslés HTTP 200 választ ad a következő mezőkkel: estimate: true, charged: false, mode, realtime, durationSeconds, billedSeconds, pricePerMinuteUsd és costUsd, a következő objektumban: data. A fájl metaadataiban megadott időtartamot használja, míg a befejezett feladat díját a dekódolt időtartam alapján számítjuk ki, amely eltérhet ettől. A becslésnél ugyanazokat a fájlellenőrzéseket végezzük el, mint a beküldésnél. Becslés csak akkor érhető el, ha a fizetős átírás engedélyezve van (egyébként 503 paid_transcription_not_enabled a válasz). 429 audio_validation_busy hibát adhat, ha a fájlellenőrzés kapacitása betelt; rövid várakozás után próbálkozzon újra.

Az átirat lekérdezése

Ismételten kérdezze le a(z) GET /v3/speech_to_text/JOB_ID végpontot a következő útmutató szerint: feladatok munkafolyamatának útmutatója. A feladatobjektum az alábbi mezőket tartalmazza:

Az átiratok, időbélyegeik, nyelvi és csatornajelöléseik automatikusan készülnek, pontosságuk nem garantált. Bármely minőségi jelzés esetén ellenőrizze az eredményt, és vesse össze a fontos neveket, számokat és vállalásokat az eredeti hanggal. A hosszú csendeket és a nagyon halk részeket a rendszer kihagyja, ezekhez nem készül szegmens. Az eredmény nem azonosítja az egyes beszélőket. Ha az eredményben a(z) channelCount értéke 2, minden szegmenshez tartozik egy channel mező, amelynek értéke A (az első, vagyis bal csatorna) vagy B (a második, vagyis jobb csatorna). Ez csak akkor választja külön a beszélőket, ha mindegyiküket külön csatornán rögzítették. A kétcsatornás hangot egyszer, az eltelt időtartam alapján számlázzuk, nem csatornánként. A monó eredményeknek nincsenek csatornajelölései.

Az api.multitel.net használata

A kompatibilitási végpont, POST https://api.multitel.net/v3/speech_to_text, multipart/form-data kódolást fogad el egy audio fájlrésszel és egy nem kötelező language mezővel, JSON audioBase64 helyett. Az üres language értéket nyelvi jelzés hiányaként kezeli. Ugyanazt a(z) Idempotency-Key fejlécet küldje. Ha a fejléc hiányzik, ez a hoszt egy idempotency_key űrlapmezőt is elfogad. A(z) source, free, billing_source, realtime vagy stream nevű mezőket 400 unsupported_transcription_option hibával utasítja el; a többi űrlapmezőt figyelmen kívül hagyja. Ez a hoszt a következő hibákat is visszaadja:

• 400 idempotency_key_required hiányzó vagy túl hosszú kulcs esetén.
• 400 audio_upload_required hiányzó vagy nem teljesen beérkezett feltöltés esetén.
• 400 invalid_language érvénytelen nyelv esetén.
• 413 invalid_audio_size üres vagy túl nagy fájl esetén.
• 400 invalid_job hibás formátumú feladatazonosító esetén.

Az ezen a hoszton futó beszédből szöveg szolgáltatás válaszai a következő borítékot használják: {"status":{"code":HTTP_STATUS},"response":{...}}. Vegye figyelembe, hogy a(z) status objektum, nem karakterlánc. Siker esetén a(z) response ugyanazt az objektumot tartalmazza, mint az elsődleges hoszton a(z) data, így a feladat azonosítója a(z) response.id. Hiba esetén a(z) response.code tartalmazza a hibakódot; üzenetet vagy kérésazonosítót nem tartalmaz a válasz. A hitelesítési hibákat (401) a hoszt általános bejelentkezési ellenőrzése adja vissza, és eltérő törzsük lehet, ezért a feldolgozás előtt ellenőrizze a HTTP-állapotkódot. Ne cserélje fel a feltöltési kódolást vagy a válaszfeldolgozót a két hoszt között.

Az ezen a hoszton történő becsléshez POST-kéréssel küldje ugyanazokat a multipart mezőket ide: /v3/speech_to_text/estimate. Idempotenciakulcs nem szükséges, a becslés pedig a(z) response objektumban található.

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'