Задаци обраде говора и превода

Замените 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 када постоји. За неважећи улаз или приступне податке прво отклоните узрок. Немојте више пута слати нове кључеве док су ранији задаци још у реду чекања.