MultiTEL
Разработчици

Задачи за преобразуване на реч в текст и превод

Удостоверявайте заявките, проверявайте статуса на задачите, повтаряйте изпращания с неясен резултат, уреждайте плащането за резултати, изчакващи плащане, проверявайте потреблението и обработвайте грешки и ограничения.

На тази страница
  1. Удостоверяване
  2. Проверявайте периодично за завършване
  3. Повтаряйте безопасно заявки с неясен резултат
  4. Освободете резултат след добавяне на средства
  5. Проверете потреблението
  6. Ограничения
  7. Обработвайте грешките при заявки

В примерите по-долу заменете SERVICE с speech_to_text или translate, а JOB_ID — с върнатия UUID. Всички операции изискват идентификационни данни за вашия акаунт, както е описано в раздел Удостоверяване, и са ограничени до акаунта, който притежава задачата. Задача може да се прочете от всеки от двата API сървъра, но всеки използва собствена външна структура на отговора, затова използвайте последователно един и същ сървър.

СървърУспехГрешка
api.multi.tel{"status":"success","data":{...}}{"status":"error","code":"...","message":"...","requestId":"..."}
api.multitel.net{"status":{"code":200},"response":{...}}{"status":{"code":409},"response":{"code":"idempotency_conflict"}}

На api.multitel.net грешките при удостоверяване (401) се връщат преди прилагането на тази външна структура и могат да имат различно тяло. Затова проверявайте HTTP статуса, преди да разчетете отговора.

Удостоверяване

Всяка заявка трябва да съдържа идентификационни данни за вашия акаунт. Задачите, ключовете за идемпотентност, ограниченията, потреблението и таксите принадлежат на акаунта, който притежава идентификационните данни. Те са общи за всички идентификационни данни на този акаунт и на двата сървъра, независимо с кои данни е изпратена заявката.

  • HTTP Basic (Authorization: Basic или curl --user). Приемат се идентификационни данни на API акаунт от тип парола, подакаунт или данните за вход във вашия акаунт. Препоръчваме отделен API акаунт. Потребителското име не може да съдържа двоеточие и нито потребителското име, нито паролата могат да бъдат празни.
  • Bearer токен (Authorization: Bearer YOUR_TOKEN). Приема се за API акаунт от тип токен. API акаунтите с токен трябва да имат ограничение по IP, а заявките трябва да идват от разрешен адрес. И двата API сървъра приемат зададените за акаунта IPv4 адреси и CIDR диапазони. Токенът не може да се изпрати като Basic парола. Проверете дали токенът ви работи на използвания сървър.
API_TOKEN="your-api-token"

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $API_TOKEN" \
  https://api.multi.tel/v3/speech_to_text

Ако API акаунтът има ограничение по IP адрес, изпращайте заявките от разрешен адрес. Липсващи или невалидни идентификационни данни връщат 401. На api.multitel.net валидни идентификационни данни, с които не могат да се използват тези услуги, например данни на акаунт с токен, изпратени като Basic, връщат 403 unsupported_transcription_principal или unsupported_translation_principal. Многократните неуспешни опити за удостоверяване от един адрес на api.multitel.net могат да доведат до блокиране на адреса, затова коригирайте идентификационните данни, преди да опитате отново.

Проверявайте периодично за завършване

Изпратете заявка GET /v3/SERVICE/JOB_ID. Препоръчваме проверките да са не по-чести от веднъж на 3 секунди. Външната структура на отговора описва заявката; проверете полето status на вложената задача, за да определите дали обработката е приключила.

СтатусЗначение
queuedПриета и изчакваща. Задачите на един акаунт се обработват една по една, като се редуват със задачите на други акаунти.
runningОбработва се. Полето progress може да бъде null; стойност null сама по себе си не означава, че задачата е блокирала.
completedРезултатът е наличен. Запазете го и сравнете важните подробности с източника.
failedПроверете failureCode. Неуспешните задачи не се таксуват. Коригирайте причината и изпратете с нов ключ; повторно изпращане със същия ключ връща същата неуспешна задача.
awaiting_paymentОбработката приключи, но предплатеният баланс не беше достатъчен за таксата. Резултатът се запазва и се задържа до уреждането на плащането за задачата.
API_USER="your-api-username"
API_PASSWORD="your-api-password"
SERVICE="speech_to_text"
HOST="https://api.multi.tel"
JOB_ID=$(node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).data.id')

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/$JOB_ID"

На api.multitel.net задайте HOST на https://api.multitel.net и прочетете .response.id вместо .data.id.

Повтаряйте безопасно заявки с неясен резултат

Ако времето за изчакване при изпращане изтече или заявката върне 429 или статус 5xx, изпратете отново същите входни данни със същия ключ за идемпотентност. Отговорът от всеки от двата сървъра може да се загуби или да бъде заменен с грешка, след като задачата е приета; повторно изпращане със същия ключ връща задачата, ако съществува. Повторно използване на ключ с различни входни данни връща 409 idempotency_conflict. Някои грешки се повтарят при всеки опит, например 503, когато платена услуга е изключена, или 500 за аудиофайл, който не може да се прочете, затова спрете след няколко опита.

Смяната на ключа има различни последствия за всяка услуга.

  • При преобразуване на реч в текст нов ключ създава нова задача с отделна такса, ако обработката завърши успешно. Първоначалният ключ продължава да връща първоначалната задача дори след обновяване на обработката.
  • При превод нов ключ с идентично съдържание връща съответстваща задача в опашката, в обработка, завършена или изчакваща плащане, без нова такса. Създава нова задача, ако предишната е неуспешна или версията на обработката е променена. Повторен опит за превод с първоначалния ключ връща 409 след промяна на версията на обработката, затова запазете първоначалния идентификатор на задачата и я прочетете директно.

Освободете резултат след добавяне на средства

За задача със статус awaiting_payment добавете средства, така че балансът ви да е поне равен на стойността costUsd на задачата, закръглена нагоре до следващото кратно на $0.00001, след което изпратете POST /v3/SERVICE/JOB_ID/settle. Сумите се удържат на цели стъпки от $0.00001 и включват остатъка, пренесен от предишни задачи на същата услуга, така че удържаната сума може да надвиши costUsd с по-малко от $0.00001. На api.multi.tel изпратете JSON {} или празно тяло; всяко свойство в тялото се отхвърля с 400. api.multitel.net игнорира тялото. Уреждането на плащането освобождава запазения резултат, без да изпълнява отново транскрипция или превод. Отговорът съдържа задачата; проверете дали статусът ѝ е completed. Ако балансът все още е недостатъчен, задачата остава със статус awaiting_payment, а отговорът продължава да е HTTP 200.

При преобразуване на реч в текст уреждането на плащане за вече завършена задача я връща с duplicate: true, а за задача в опашката, в обработка или неуспешна връща 409 transcription_not_awaiting_payment. При превод уреждането на плащане за задача с какъвто и да е друг статус връща задачата без промяна. Уреждането на плащане е налично само когато платената обработка е включена (иначе 503). Задачите, изчакващи плащане, се отчитат като резервиран разход, затова при предплатени акаунти могат да блокират нови платени заявки с 402, докато плащането им не бъде уредено.

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -X POST -H "Content-Type: application/json" --data '{}' \
  "$HOST/v3/$SERVICE/$JOB_ID/settle"

Проверете потреблението

Използвайте GET /v3/SERVICE/usage. Незадължителните параметри from и to са дати по UTC във формат YYYY-MM-DD, като и двете гранични дати са включени. Ако бъдат пропуснати, from по подразбиране е датата 30 дни преди днес, а to е днешната дата (UTC). to не трябва да е преди from, а разликата между датите може да е най-много 366 дни (до 367 дати). Невалидни календарни дати или обърнат или по-дълъг диапазон връщат 400, както и други параметри на заявката на api.multi.tel.

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/usage?from=2026-10-01&to=2026-10-31"

Отговорът съдържа mode, currency (USD), from, to и days, списък с най-новите записи първи.

  • Записите за преобразуване на реч в текст са групирани по дата и източник. Те съдържат date, source (api или hpbx за записи от Hosted PBX), files, audioSeconds, billedSeconds, accruedUsd и debitedUsd.
  • Записите за превод са групирани по дата, източник и машина за превод. Те съдържат date, source, engine, jobs, sourceCharacters, accruedUsd и debitedUsd.

accruedUsd е точният разход с девет знака след десетичната запетая, а debitedUsd е удържаната сума с пет знака. Потреблението се записва на датата по UTC, на която е уредено плащането за всяка задача, затова задачи в опашката, в обработка, неуспешни и изчакващи плащане не се показват.

Ограничения

Всеки акаунт може да има общо най-много 50 незавършени задачи за преобразуване на реч в текст и превод: в опашката, в обработка или изчакващи плащане, включително обработка на записи от Hosted PBX. При достигане на това ограничение или на общия капацитет на услугата заявките за нови задачи връщат 429 transcription_queue_full или translation_queue_full. api.multi.tel също ограничава всеки клиентски IP адрес до 300 заявки в минута общо за всички заявки към този сървър. При достигане на това ограничение се връща 429 със заглавки за ограничаване на честотата и тяло от обикновен текст вместо външната JSON структура за грешки.

Обработвайте грешките при заявки

На основния сървър неуспешните заявки връщат HTTP статус за грешка и JSON с status: "error", code, message и requestId. Всеки отговор съдържа и заглавка X-Request-ID. Можете да подадете собствена стойност; стойности над 128 знака се съкращават. Сървърът за съвместимост връща само кода за грешка в response.code. Записвайте идентификатора на заявката, когато е наличен, и кода за грешка в дневниците, но не записвайте в тях аудио, текст или идентификационни данни.

Често срещани статуси:

СтатусЗначение
400Невалидни входни данни.
401Липсващи или невалидни идентификационни данни.
402Недостатъчен предплатен баланс.
403На сървъра за съвместимост — идентификационни данни, с които тези услуги не могат да се използват.
404Непозната задача или маршрут.
405Неподдържан метод или непознат път в рамките на услуга.
409Противоречиви входни данни, превод на същия език или уреждане на плащане за задача за преобразуване на реч в текст, която не изчаква плащане.
413Твърде голямо тяло или файл.
422Неподдържано аудио или недостъпна езикова двойка за стандартен превод.
429Ограничения на опашката, проверката на входните данни или честотата на заявките.
500Неочаквана сървърна грешка, включително аудиофайл, който не може да се прочете.
503Изключена или временно недостъпна услуга или идентификационни данни, които не могат да бъдат проверени в момента.

Следвайте върнатия код за грешка, вместо да приемате, че всяка неуспешна проверка на входните данни има един и същ статус.

При 429 или 503 изчакайте и опитайте отново с нарастващо изчакване и същия ключ за изпращане; спазвайте Retry-After, когато тази заглавка е налична. При невалидни входни или идентификационни данни първо отстранете причината. Не изпращайте многократно нови ключове, докато предишни задачи все още са в опашката.