API за преобразуване на реч в текст

Този API транскрибира завършени аудиофайлове като задачи на опашка. Подайте файл, запазете върнатия идентификатор на задачата и извличайте задачата, докато обработката приключи. Изпращайте всяка заявка по HTTPS с данните за удостоверяване на профила си — чрез HTTP Basic, както е показано в примерите, или с API токен, както е описано в Удостоверяване. Пазете данните за удостоверяване на сървъра си.

Крайни точки

Двата API хоста, https://api.multi.tel и хостът за съвместимост https://api.multitel.net, споделят едни и същи задачи, ключове за идемпотентност, ограничения и таксуване в рамките на профила. Те се различават по кодирането на качените данни и обвивката на отговора, затова използвайте последователно един хост със съответстващ анализатор на отговорите.

На api.multi.tel всеки път е достъпен и с префикса /v1/speech-to-text вместо /v3/speech_to_text, например POST /v1/speech-to-text/estimate. На api.multitel.net използвайте пътищата /v3/speech_to_text.

Отговорът с информация за услугата съдържа mode (batch), realtime (false), paidEnabled (дали в момента се приемат нови платени задачи), pricePerMinuteUsd (0.005), billingUnit (audio_second), maxAudioSeconds (7200) и maxUploadBytes (26214400), заедно с кратко описание в description. Прочитането е безплатно и работи, когато подаването на платени задачи е изключено; връща 503 transcription_unavailable само когато услугата като цяло е недостъпна.

Подготовка на аудиофайл

Използвайте завършен аудиофайл с размер до 25 MiB (26,214,400 байта) и продължителност до 2 часа (7,200 секунди). При подаването файлът трябва да бъде разпознат като MP3, WAV, Ogg, FLAC, MOV или Matroska медия с аудиопоток, чиято продължителност в метаданните е по-голяма от нула и не надвишава 7,200 секунди. Разпознат файл, който не премине тези проверки, се отхвърля с 422 unsupported_audio. Файл, който не може да бъде прочетен в нито един от тези формати, в момента може вместо това да бъде отхвърлен със сървърна грешка (500); не подавайте такъв файл повторно без промени. Самото файлово разширение не доказва съвместимост.

Преминаването на тези проверки не гарантира, че аудиото може да бъде декодирано. Аудиото се обработва като един или два канала. Файл с повече от два аудиоканала, файл, чието декодирано аудио е по-дълго от 2 часа, или друг файл, чието декодиране се провали при обработката, завършва като задача със статус failed, обикновено с decode_failed, и не се таксува. Преди подаване преобразувайте многоканалното аудио в моно или стерео.

Незадължителната подсказка за език е код от две или три малки букви за говоримия език, например en. За да не задавате подсказка, пропуснете полето; api.multi.tel отхвърля празен низ. Подсказката насочва обработката, но не се проверява спрямо списък с поддържани езици, затова използвайте валиден код за говоримия език.

Подаване на задача за транскрипция

Изпратете JSON с Content-Type: application/json към POST https://api.multi.tel/v3/speech_to_text. Тялото на заявката може да е до 35 MiB, което побира файл с максималния размер след base64 кодиране; по-голямо тяло се отхвърля с 413.

Всяко друго JSON свойство, включително idempotency_key, се отхвърля с 400 invalid_transcription_request. Изпратете ключа като хедър.

Ключ за идемпотентност

Всяко подаване изисква хедър Idempotency-Key с дължина от 1 до 190 знака. Използвайте ASCII букви, цифри, -, _, . и :, без начални или крайни интервали: хостът за съвместимост премахва околните празни знаци и измерва ключа в байтове, затова други знаци може да се броят различно от двата хоста. Липсващ ключ или ключ от 191 или повече знака се отхвърля с 400.

Ключовете са обвързани с профила ви и услугата за преобразуване на реч в текст, за двата хоста и всички данни за удостоверяване на профила. Повторното изпращане на същия ключ със същия файл и език връща съществуващата задача с HTTP 200 и duplicate: true, независимо от статуса ѝ и дори ако обработката е актуализирана след създаването ѝ, без нова такса. Повторното използване на ключ с различен файл или език връща 409 idempotency_conflict. Нов ключ създава нова задача дори за идентичен файл, с отделна такса, ако обработката приключи успешно.

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'

Нова задача връща HTTP 202 с полетата по-долу, а повторно подаване връща HTTP 200 с пълния обект на задачата, описан в Прочитане на транскрипцията. Прочетете идентификатора на задачата, който е UUID, от data.id. Отговорът за нова задача изглежда така (идентификаторът и стойностите са примерни):

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

Докато задачата е на опашка или се изпълнява, durationSeconds, billedSeconds и costUsd са оценки от метаданните на файла. Окончателната такса използва декодираната продължителност.

Подаването може да върне и 402 insufficient_balance, когато предплатеното салдо не покрива задачата заедно с останалите ви неприключени задачи, 429 transcription_queue_full, когато профилът ви или услугата има твърде много неприключени задачи, 429 audio_validation_busy, когато капацитетът за проверка на файлове е изчерпан, и 503 paid_transcription_not_enabled, докато платената транскрипция е изключена. Повторете заявките с отговори 429 и 503 по-късно със същия ключ.

Оценка без създаване на задача

Изпратете същото JSON тяло към POST https://api.multi.tel/v3/speech_to_text/estimate. Не е необходим ключ за идемпотентност. Оценката проверява и измерва файла, но не го транскрибира, не създава задача, не резервира средства, не проверява салдото ви и не таксува профила ви. Подсказка чрез language се приема, но не влияе на оценката.

Успешна оценка връща HTTP 200 с estimate: true, charged: false, mode, realtime, durationSeconds, billedSeconds, pricePerMinuteUsd и costUsd в data. Използва се продължителността в метаданните на файла, докато завършената задача се таксува според декодираната ѝ продължителност, която може да е различна. Оценките прилагат същите проверки на файловете като подаването на задачи. Достъпни са само когато платената транскрипция е включена (в противен случай 503 paid_transcription_not_enabled). Могат да върнат 429 audio_validation_busy, когато капацитетът за проверка на файлове е изчерпан; опитайте отново след кратко изчакване.

Прочитане на транскрипцията

Изпращайте периодично заявки към GET /v3/speech_to_text/JOB_ID, както е описано в ръководството за работния процес на задачите. Обектът на задачата съдържа следните полета:

Транскрипциите и техните времеви маркери, езикови означения и означения на каналите се генерират автоматично и точността им не е гарантирана. Приемайте всеки индикатор за качество като основание за преглед на резултата и сравнявайте важните имена, числа и ангажименти с оригиналното аудио. Дългите паузи и много тихите пасажи се пропускат и не създават сегменти. Резултатите не разпознават отделни говорители. Когато резултатът показва channelCount със стойност 2, всеки сегмент има channel със стойност A (първият, или левият, канал) или B (вторият, или десният, канал). Това разделя говорителите само когато всеки е записан на отделен канал. Двуканалното аудио се таксува веднъж според изминалата му продължителност, а не за всеки канал. Моно резултатите нямат означения на канали.

Използване на api.multitel.net

Крайната точка за съвместимост POST https://api.multitel.net/v3/speech_to_text приема multipart/form-data с файлова част audio и незадължително поле language, вместо JSON audioBase64. Празна стойност за language се приема за липса на подсказка. Изпратете същия хедър Idempotency-Key. Ако хедърът липсва, този хост приема и поле idempotency_key във формуляра. Полета с имена source, free, billing_source, realtime или stream се отхвърлят с 400 unsupported_transcription_option; останалите полета във формуляра се игнорират. Този хост връща и следните грешки:

• 400 idempotency_key_required за липсващ или прекалено дълъг ключ.
• 400 audio_upload_required за липсващо качване или такова, което не е получено изцяло.
• 400 invalid_language за невалиден език.
• 413 invalid_audio_size за празен или прекалено голям файл.
• 400 invalid_job за неправилно оформен идентификатор на задача.

Отговорите от услугата за преобразуване на реч в текст на този хост използват обвивката {"status":{"code":HTTP_STATUS},"response":{...}}. Обърнете внимание, че status е обект, а не низ. При успех response съдържа същия обект като data на основния хост, така че идентификаторът на задачата е response.id. При грешка response.code съдържа кода на грешката; не се включват съобщение или идентификатор на заявката. Неуспешното удостоверяване (401) се връща от общата проверка за вход на хоста и може да има различно тяло, затова проверявайте HTTP статуса преди анализа на отговора. Не разменяйте кодирането на качването или анализатора на отговорите между хостовете.

За оценка на този хост изпратете с POST същите multipart полета към /v3/speech_to_text/estimate. Не е необходим ключ за идемпотентност, а оценката е в 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'