Завдання обробки мовлення та перекладу

Замініть SERVICE нижче на speech_to_text або translate, а JOB_ID — на отриманий UUID. Усі операції потребують облікових даних вашого облікового запису, як описано в розділі Автентифікація, і виконуються в межах облікового запису-власника. Завдання можна прочитати з будь-якого з двох хостів API, але кожен має власну оболонку відповіді, тому послідовно використовуйте один хост.

На api.multitel.net помилки автентифікації (401) повертаються до застосування цієї оболонки й можуть мати інше тіло, тому перед розбором відповіді перевіряйте HTTP-статус.

Автентифікація

Кожен запит має містити облікові дані вашого облікового запису. Завдання, ключі ідемпотентності, ліміти, використання та нарахування належать обліковому запису, якому належать ці облікові дані. Вони спільні для всіх його облікових даних на обох хостах незалежно від того, якими саме обліковими даними надіслано запит.

• HTTP Basic (Authorization: Basic або curl --user). Приймаються дані облікового запису API парольного типу, субоблікового запису або дані входу до вашого облікового запису. Рекомендуємо окремий обліковий запис API. Ім’я користувача не може містити двокрапку; ані ім’я користувача, ані пароль не можуть бути порожніми.
• Токен Bearer (Authorization: Bearer YOUR_TOKEN). Підтримується для облікового запису 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 вкладеного завдання.

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, тому збережіть початковий ID завдання й читайте завдання безпосередньо.

Отримання результату після поповнення балансу

Для завдання зі статусом 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. Записуйте в журнали ID запиту, якщо він доступний, і код помилки, але не записуйте аудіо, текст та облікові дані.

Поширені статуси:

Керуйтеся отриманим кодом помилки, а не припущенням, що всі помилки перевірки даних мають однаковий статус.

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