Задания распознавания речи и перевода

В примерах ниже замените 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-аккаунта типа «токен». Для таких 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, если этот заголовок присутствует. При неверных входных или учётных данных сначала исправьте причину. Не отправляйте постоянно новые ключи, пока предыдущие задания ещё в очереди.