Puheentunnistus- ja käännöstyöt

Korvaa alla oleva SERVICE arvolla speech_to_text tai translate ja JOB_ID palautetulla UUID-tunnuksella. Kaikki toiminnot edellyttävät tilisi tunnistetietoja kohdassa Todennus kuvatulla tavalla, ja ne rajataan työn omistavaan tiliin. Työn voi lukea kummaltakin API-palvelimelta, mutta palvelimet käyttävät omia vastauksen ulkorakenteitaan, joten käytä johdonmukaisesti samaa palvelinta.

Palvelimella api.multitel.net todennusvirheet (401) palautetaan ennen tämän ulkorakenteen muodostamista. Niiden vastausrunko voi olla erilainen, joten tarkista HTTP-tilakoodi ennen jäsentämistä.

Todennus

Jokaisen pyynnön on sisällettävä tilisi tunnistetiedot. Työt, idempotenssiavaimet, rajoitukset, käyttö ja veloitukset kuuluvat tunnistetiedot omistavalle tilille. Ne ovat yhteisiä tilin kaikille tunnistetiedoille molemmilla palvelimilla riippumatta siitä, millä tunnistetiedoilla pyyntö lähetetään.

• HTTP Basic (Authorization: Basic tai curl --user). Hyväksyttyjä tunnistetietoja ovat salasanatyyppisen API-tilin, alatilin tai oman käyttäjätilisi kirjautumistiedot. Suosittelemme erillistä API-tiliä. Käyttäjänimi ei saa sisältää kaksoispistettä, eikä käyttäjänimi tai salasana saa olla tyhjä.
• Bearer-token (Authorization: Bearer YOUR_TOKEN). Hyväksytään token-tyyppiselle API-tilille. Token-tyyppisillä API-tileillä on oltava IP-rajoitus, ja pyyntöjen on tultava sallitusta osoitteesta. Molemmat API-palvelimet hyväksyvät tilille määritetyt IPv4-osoitteet ja CIDR-alueet. Tunnusta ei voi lähettää Basic-salasanana. Varmista, että tunnuksesi toimii käyttämälläsi palvelimella.

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

Jos API-tilillä on IP-osoiterajoitus, lähetä pyynnöt sallitusta osoitteesta. Puuttuvat tai virheelliset tunnistetiedot palauttavat tilakoodin 401. Palvelimella api.multitel.net kelvolliset tunnistetiedot, joilla ei voi käyttää näitä palveluja, kuten Basic-muodossa lähetetyt token-tilin tunnistetiedot, palauttavat tilakoodin 403 ja virhekoodin unsupported_transcription_principal tai unsupported_translation_principal. Toistuvat epäonnistuneet todennusyritykset samasta osoitteesta palvelimella api.multitel.net voivat johtaa osoitteen estämiseen, joten korjaa tunnistetiedot ennen uutta yritystä.

Kysy työn valmistumistilaa

Lähetä pyyntö GET /v3/SERVICE/JOB_ID. Suosittelemme kysymään tilaa enintään kerran 3 sekunnissa. Vastauksen ulkorakenne kuvaa pyyntöä; tarkista sen sisällä olevan työn status-kentästä, onko käsittely valmistunut.

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"

Palvelimella api.multitel.net aseta HOST arvoon https://api.multitel.net ja lue .response.id kentän .data.id sijaan.

Yritä epävarmaksi jääneitä pyyntöjä turvallisesti uudelleen

Jos työn lähetys aikakatkaistaan tai palauttaa tilakoodin 429 tai 5xx, lähetä samat syötetiedot uudelleen samalla idempotenssiavaimella. Kummankin palvelimen vastaus voi kadota tai korvautua virheellä sen jälkeen, kun työ on hyväksytty. Lähettäminen samalla avaimella palauttaa työn, jos se on olemassa. Avaimen käyttäminen uudelleen eri syötetiedoilla palauttaa tilakoodin 409 ja virhekoodin idempotency_conflict. Osa virheistä toistuu joka yrityksellä, esimerkiksi 503 maksullisen palvelun ollessa poissa käytöstä tai 500, kun äänitiedostoa ei voida lukea. Lopeta siksi muutaman yrityksen jälkeen.

Avaimen vaihtamisen vaikutukset eroavat palveluittain.

• Puheentunnistuksessa uusi avain luo uuden työn, josta veloitetaan erikseen, jos käsittely onnistuu. Alkuperäinen avain palauttaa edelleen alkuperäisen työn, vaikka käsittelyä päivitettäisiin.
• Kääntämisessä uusi avain ja täsmälleen sama sisältö palauttavat vastaavan jonossa olevan, käsiteltävän, valmistuneen tai maksua odottavan työn ilman uutta veloitusta. Uusi työ luodaan, jos aiempi työ epäonnistui tai käsittelyversio on muuttunut. Käännöksen uudelleenyritys alkuperäisellä avaimella palauttaa tilakoodin 409 käsittelyversion muututtua, joten säilytä alkuperäinen työtunnus ja lue työ suoraan.

Vapauta tulos saldon lisäämisen jälkeen

Jos työn tila on awaiting_payment, lisää saldoa niin, että sitä on vähintään työn costUsd ylöspäin seuraavaan $0.00001:n monikertaan pyöristettynä. Lähetä sitten POST /v3/SERVICE/JOB_ID/settle. Veloitukset tehdään kokonaisina $0.00001:n erinä, ja niihin sisältyy saman palvelun aiemmista töistä siirtynyt jäännös. Siksi veloitettu summa voi ylittää costUsd-arvon alle $0.00001:lla. Palvelimella api.multi.tel lähetä JSON-runko {} tai tyhjä runko; mikä tahansa rungon ominaisuus hylätään tilakoodilla 400. Palvelin api.multitel.net sivuuttaa rungon. Maksun suorittaminen vapauttaa tallennetun tuloksen tekemättä puheentunnistusta tai käännöstä uudelleen. Vastaus sisältää työn; tarkista, että sen tila on completed. Jos saldo ei vieläkään riitä, työn tila pysyy arvossa awaiting_payment ja vastauksen HTTP-tilakoodi on edelleen 200.

Puheentunnistuksessa jo valmistuneen työn maksun suorittaminen palauttaa työn merkinnällä duplicate: true, ja jonossa olevan, käsiteltävän tai epäonnistuneen työn maksun suorittaminen palauttaa tilakoodin 409 ja virhekoodin transcription_not_awaiting_payment. Kääntämisessä missä tahansa muussa tilassa olevan työn maksun suorittaminen palauttaa työn muuttumattomana. Maksun suorittaminen on mahdollista vain maksullisen käsittelyn ollessa käytössä (muuten 503). Maksua odottavat työt lasketaan varatuiksi kustannuksiksi, joten ennakkomaksutileillä ne voivat estää uusien maksullisten töiden lähettämisen tilakoodilla 402, kunnes niiden maksut suoritetaan.

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"

Tarkista käyttö

Käytä pyyntöä GET /v3/SERVICE/usage. Valinnaiset from ja to ovat UTC-päivämääriä muodossa YYYY-MM-DD, ja molemmat rajapäivät sisältyvät jaksoon. Jos parametrit jätetään pois, from on oletuksena 30 päivää ennen tätä päivää ja to on oletuksena tämä päivä (UTC). to ei saa olla aiempi kuin from, ja päivämäärien väli saa olla enintään 366 päivää (enintään 367 päivämäärää). Virheellinen kalenteripäivä, käänteinen jakso tai liian pitkä jakso palauttaa tilakoodin 400, samoin muut kyselyparametrit palvelimella 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"

Vastaus sisältää kentät mode, currency (USD), from, to ja days, joka on uusimmasta vanhimpaan järjestetty luettelo.

• Puheentunnistuksen merkinnät ryhmitellään päivämäärän ja lähteen mukaan. Ne sisältävät kentät date, source (api tai hpbx Hosted PBX -tallenteille), files, audioSeconds, billedSeconds, accruedUsd ja debitedUsd.
• Käännösten merkinnät ryhmitellään päivämäärän, lähteen ja käännösmoottorin mukaan. Ne sisältävät kentät date, source, engine, jobs, sourceCharacters, accruedUsd ja debitedUsd.

accruedUsd on tarkka kustannus yhdeksän desimaalin tarkkuudella, ja debitedUsd on veloitettu summa viiden desimaalin tarkkuudella. Käyttö kirjataan sille UTC-päivälle, jona työn maksu suoritettiin, joten jonossa olevat, käsiteltävät, epäonnistuneet ja maksua odottavat työt eivät näy tiedoissa.

Rajoitukset

Kullakin tilillä voi olla yhteensä enintään 50 keskeneräistä puheentunnistus- ja käännöstyötä: jonossa, käsittelyssä tai maksua odottamassa, mukaan lukien Hosted PBX -tallenteiden käsittely. Kun tämä raja tai palvelun kokonaiskapasiteetti täyttyy, työn lähettäminen palauttaa tilakoodin 429 ja virhekoodin transcription_queue_full tai translation_queue_full. Palvelin api.multi.tel rajoittaa myös kunkin asiakkaan IP-osoitteen pyyntömäärän 300 pyyntöön minuutissa. Raja koskee kaikkia kyseiselle palvelimelle tehtyjä pyyntöjä. Sen ylittyessä palautetaan tilakoodi 429, pyyntönopeuden rajoitusotsakkeet ja pelkkää tekstiä sisältävä runko JSON-virherakenteen sijaan.

Käsittele pyyntövirheet

Ensisijaisella palvelimella virheet palauttavat HTTP-virhetilakoodin ja JSON-vastauksen, joka sisältää status: "error", code, message ja requestId. Jokaisessa vastauksessa on myös X-Request-ID-otsake. Voit antaa oman arvon; yli 128 merkkiä pitkät arvot katkaistaan. Yhteensopivuuspalvelin palauttaa vain virhekoodin kentässä response.code. Kirjaa pyyntötunnus, jos se on saatavilla, sekä virhekoodi, mutta älä kirjaa ääntä, tekstiä tai tunnistetietoja lokeihin.

Yleiset tilakoodit:

Toimi palautetun virhekoodin mukaan äläkä oleta, että kaikki validointivirheet palauttavat saman tilakoodin.

Tilakoodeilla 429 tai 503 odota ja yritä uudelleen pidentäen odotusaikaa ja käyttäen samaa lähetysavainta. Noudata Retry-After-otsaketta, jos se on mukana. Korjaa virheelliset syötetiedot tai tunnistetiedot ensin. Älä lähetä jatkuvasti uusia avaimia, kun aiemmat työt ovat vielä jonossa.