MultiTEL
Ontwikkelaars

Spraak- en vertalingstake

Staaf versoeke, vra taakstatusse op, herprobeer onsekere indienings, vereffen take wat op betaling wag, gaan gebruik na en hanteer foute en perke.

Op hierdie bladsy
  1. Stawing
  2. Vra die status op totdat die taak klaar is
  3. Herprobeer onsekere versoeke veilig
  4. Stel ’n resultaat vry nadat jy geld bygevoeg het
  5. Gaan gebruik na
  6. Perke
  7. Hanteer versoekfoute

Vervang SERVICE hieronder met speech_to_text of translate, en JOB_ID met die teruggestuurde UUID. Alle bewerkings vereis jou rekening se aanmeldbesonderhede, soos beskryf onder Stawing, en is tot die rekening wat die taak besit, beperk. ’n Taak kan vanaf enige API-gasheer gelees word, maar elke gasheer gebruik sy eie antwoordomhulsel. Gebruik dus deurgaans dieselfde gasheer.

GasheerSuksesFout
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"}}

Op api.multitel.net word stawingsfoute (401) teruggestuur voordat hierdie omhulsel toegepas word, en hulle kan ’n ander antwoordliggaam hê. Gaan dus die HTTP-status na voordat jy die antwoord ontleed.

Stawing

Elke versoek moet jou rekening se aanmeldbesonderhede bevat. Take, idempotensiesleutels, perke, gebruik en heffings behoort aan die rekening wat die aanmeldbesonderhede besit. Hulle word deur al daardie rekening se aanmeldbesonderhede op albei gashere gedeel, ongeag watter aanmeldbesonderhede die versoek stuur.

  • HTTP Basic (Authorization: Basic of curl --user). Aanvaarde aanmeldbesonderhede is dié van ’n API-rekening van die wagwoordtipe, ’n subrekening of jou rekening se aanmelding. Ons beveel ’n toegewyde API-rekening aan. Die gebruikersnaam mag nie ’n dubbelpunt bevat nie, en die gebruikersnaam en wagwoord mag nie leeg wees nie.
  • Bearer-token (Authorization: Bearer YOUR_TOKEN). Word aanvaar vir ’n API-rekening van die tokentipe. Token-API-rekeninge moet ’n IP-beperking hê, en versoeke moet van ’n toegelate adres af kom. Albei API-gashere aanvaar die rekening se ingestelde IPv4-adresse en CIDR-reekse. ’n Token kan nie as ’n Basic-wagwoord gestuur word nie. Bevestig dat jou token werk op die gasheer wat jy gebruik.
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

As ’n API-rekening volgens IP-adres beperk is, stuur versoeke vanaf ’n toegelate adres. Ontbrekende of ongeldige aanmeldbesonderhede gee 401 terug. Op api.multitel.net gee geldige aanmeldbesonderhede wat nie hierdie dienste mag gebruik nie, soos ’n tokenrekening se besonderhede wat as Basic gestuur word, 403 terug met unsupported_transcription_principal of unsupported_translation_principal. Herhaalde mislukte stawing vanaf een adres op api.multitel.net kan daartoe lei dat daardie adres geblokkeer word. Stel dus die aanmeldbesonderhede reg voordat jy weer probeer.

Vra die status op totdat die taak klaar is

Stuur die versoek GET /v3/SERVICE/JOB_ID. Ons beveel aan dat jy die status nie meer as een keer elke 3 sekondes opvra nie. Die buitenste omhulsel beskryf die versoek; gaan die binneste taak se status na om te bepaal of verwerking klaar is.

StatusBetekenis
queuedAanvaar en wag. Een rekening se take word een op ’n slag verwerk, om die beurt met ander rekeninge.
runningWord verwerk. progress kan null wees; ’n null-waarde op sigself beteken nie dat die taak vasgeval het nie.
completedDie resultaat is beskikbaar. Bewaar dit en vergelyk belangrike besonderhede met die bron.
failedGaan failureCode na. Daar is geen heffing vir mislukte werk nie. Stel die oorsaak reg en dien dit met ’n nuwe sleutel in; as jy dieselfde sleutel weer stuur, word dieselfde mislukte taak teruggestuur.
awaiting_paymentVerwerking is klaar, maar die voorafbetaalde saldo kon nie die heffing dek nie. Die resultaat is gestoor en word teruggehou totdat die taak vereffen is.
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"

Op api.multitel.net, stel HOST op https://api.multitel.net en lees .response.id in plaas van .data.id.

Herprobeer onsekere versoeke veilig

As ’n indiening se wagtyd verstryk of dit 429 of ’n 5xx-status teruggee, stuur dieselfde invoer weer met dieselfde idempotensiesleutel. ’n Antwoord vanaf enige gasheer kan verlore gaan of deur ’n fout vervang word nadat die werk aanvaar is; as jy dieselfde sleutel weer stuur, word die taak teruggestuur indien dit bestaan. ’n Sleutel wat met ander invoer hergebruik word, gee 409 terug met idempotency_conflict. Sommige foute herhaal met elke poging, soos 503 terwyl ’n betaalde diens afgeskakel is, of 500 vir ’n oudiolêer wat nie gelees kan word nie. Hou dus ná ’n paar pogings op.

Om ’n sleutel te verander, het verskillende gevolge vir elke diens.

  • Vir spraak-na-teks skep ’n nuwe sleutel ’n nuwe taak met ’n afsonderlike heffing indien verwerking suksesvol voltooi word. Die oorspronklike sleutel hou aan om die oorspronklike taak terug te stuur, selfs nadat die verwerking opgedateer is.
  • Vir vertaling gee ’n nuwe sleutel met identiese inhoud ’n ooreenstemmende taak terug wat in die tou staan, verwerk word, voltooi is of op betaling wag, sonder ’n nuwe heffing. Dit skep nuwe werk as die vorige taak misluk het of die verwerkingsweergawe verander het. ’n Herhaalde vertaalversoek met die oorspronklike sleutel gee 409 terug nadat die verwerkingsweergawe verander het. Bewaar dus die oorspronklike taak-ID en lees die taak direk.

Stel ’n resultaat vry nadat jy geld bygevoeg het

Vir ’n taak met status awaiting_payment, voeg geld by sodat jou saldo minstens die taak se costUsd is, opwaarts afgerond tot die volgende veelvoud van $0.00001. Stuur dan POST /v3/SERVICE/JOB_ID/settle. Bedrae word in volle stappe van $0.00001 gedebiteer en sluit enige resbedrag in wat van vorige take vir dieselfde diens oorgedra is. Die gedebiteerde bedrag kan dus costUsd met minder as $0.00001 oorskry. Op api.multi.tel, stuur JSON {} of ’n leë versoekliggaam; enige eienskap in die liggaam word met 400 verwerp. api.multitel.net ignoreer die liggaam. Vereffening stel die gestoorde resultaat vry sonder om transkripsie of vertaling weer uit te voer. Die antwoord bevat die taak; gaan na dat sy status completed is. As die saldo steeds onvoldoende is, bly die taak se status awaiting_payment en is die antwoord steeds HTTP 200.

Vir spraak-na-teks gee die vereffening van ’n reeds voltooide taak dit terug met duplicate: true, en die vereffening van ’n taak wat in die tou staan, verwerk word of misluk het, gee 409 terug met transcription_not_awaiting_payment. Vir vertaling gee die vereffening van ’n taak in enige ander status die taak onveranderd terug. Vereffening is slegs beskikbaar terwyl betaalde verwerking aangeskakel is (anders 503). Take wat op betaling wag, tel as gereserveerde koste. Vir voorafbetaalde rekeninge kan hulle dus nuwe betaalde indienings met 402 blokkeer totdat hulle vereffen is.

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"

Gaan gebruik na

Gebruik GET /v3/SERVICE/usage. Die opsionele from- en to-parameters is UTC-datums in YYYY-MM-DD-formaat, en albei grensdatums word ingesluit. Indien dit weggelaat word, is from by verstek 30 dae voor vandag en to by verstek vandag (UTC). to mag nie vroeër wees as from nie, en die datums mag hoogstens 366 dae uitmekaar wees (tot 367 datums). Ongeldige kalenderdatums of ’n omgekeerde of langer tydperk gee 400 terug, en so ook ander navraagparameters op 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"

Die antwoord bevat mode, currency (USD), from, to en days, ’n lys met die nuutste eerste.

  • Spraak-na-teks-inskrywings word volgens datum en bron gegroepeer. Hulle bevat date, source (api of hpbx vir Hosted PBX-opnames), files, audioSeconds, billedSeconds, accruedUsd en debitedUsd.
  • Vertalingsinskrywings word volgens datum, bron en enjin gegroepeer. Hulle bevat date, source, engine, jobs, sourceCharacters, accruedUsd en debitedUsd.

accruedUsd is die presiese koste met nege desimale plekke, en debitedUsd is die gedebiteerde bedrag met vyf. Gebruik word aangeteken op die UTC-datum waarop elke taak se heffing vereffen is. Take wat in die tou staan, verwerk word, misluk het of op betaling wag, verskyn dus nie.

Perke

Elke rekening kan hoogstens 50 uitstaande spraak-na-teks- en vertalingstake saam hê: in die tou, besig met verwerking of wagtend op betaling, insluitend werk aan Hosted PBX-opnames. Wanneer daardie perk of die diens se algehele kapasiteit bereik word, gee indienings 429 terug met transcription_queue_full of translation_queue_full. api.multi.tel beperk ook elke kliënt-IP-adres tot 300 versoeke per minuut oor alle versoeke aan daardie gasheer. Hierdie perk gee 429 terug met opskrifte oor die versoektempoperk en ’n gewone teksliggaam eerder as die JSON-foutomhulsel.

Hanteer versoekfoute

Op die primêre gasheer gee mislukkings ’n HTTP-foutstatus en JSON terug met status: "error", code, message en requestId. Elke antwoord bevat ook ’n X-Request-ID-opskrif. Jy kan jou eie waarde verskaf; waardes langer as 128 karakters word afgekap. Die versoenbaarheidsgasheer gee slegs die foutkode terug in response.code. Teken die versoek-ID aan waar dit beskikbaar is, asook die foutkode, en hou oudio, teks en aanmeldbesonderhede uit loglêers.

Algemene statusse:

StatusBetekenis
400Ongeldige invoer.
401Ontbrekende of ongeldige aanmeldbesonderhede.
402Onvoldoende voorafbetaalde saldo.
403Op die versoenbaarheidsgasheer: aanmeldbesonderhede wat nie hierdie dienste mag gebruik nie.
404’n Onbekende taak of roete.
405’n Metode wat nie ondersteun word nie, of ’n onbekende pad binne ’n diens.
409Botsende invoer, ’n vertaling na dieselfde taal, of die vereffening van ’n spraaktaak wat nie op betaling wag nie.
413’n Te groot liggaam of lêer.
422Oudio wat nie ondersteun word nie, of ’n standaardtaalpaar wat nie beskikbaar is nie.
429Perke vir die tou, validering of versoektempo.
500’n Onverwagte bedienerfout, insluitend ’n oudiolêer wat nie gelees kan word nie.
503’n Diens wat afgeskakel of tydelik onbeskikbaar is, of aanmeldbesonderhede wat nie tans nagegaan kan word nie.

Volg die teruggestuurde foutkode eerder as om aan te neem dat elke valideringsfout dieselfde status het.

Vir 429 of 503, wag en probeer weer met toenemende wagtye en dieselfde indieningsleutel; volg Retry-After wanneer dit teenwoordig is. Vir ongeldige invoer of aanmeldbesonderhede, stel eers die oorsaak reg. Moenie herhaaldelik nuwe sleutels indien terwyl vroeëre take nog in die tou is nie.