API за претварање говора у текст

Овај API транскрибује завршене аудио-датотеке као задатке у реду за обраду. Пошаљите датотеку, сачувајте враћени ID задатка и преузимајте задатак док се обрада не заврши. Сваки захтев шаљите преко 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 са целим објектом задатка описаним у одељку Прочитајте транскрипт. Прочитајте ID задатка, који је 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 за неисправно форматиран ID задатка.

Одговори услуге претварања говора у текст са овог сервера користе омотач {"status":{"code":HTTP_STATUS},"response":{...}}. Имајте у виду да је status објекат, а не стринг. У случају успеха, response садржи исти објекат као data на примарном серверу, па је ID задатка response.id. При грешци, response.code садржи код грешке; порука и ID захтева нису укључени. Неуспешну аутентификацију (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'