Erstatt SERVICE nedenfor med speech_to_text eller translate og JOB_ID med UUID-en du fikk tilbake. Alle operasjoner krever påloggingsopplysninger for kontoen din, som beskrevet under Autentisering, og er avgrenset til eierkontoen. En jobb kan leses fra begge API-vertene, men de bruker ulike svarstrukturer. Bruk derfor samme vert konsekvent.
| Vert | Vellykket svar | Feil |
|---|---|---|
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"}} |
På api.multitel.net returneres autentiseringsfeil (401) før denne svarstrukturen brukes, og innholdet kan være annerledes. Kontroller HTTP-statusen før du tolker svaret.
Autentisering
Hver forespørsel må inneholde påloggingsopplysninger for kontoen din. Jobber, idempotensnøkler, grenser, bruk og kostnader tilhører kontoen som eier opplysningene. De deles mellom alle påloggingsopplysningene til denne kontoen på begge verter, uavhengig av hvilke som sender forespørselen.
- HTTP Basic (
Authorization: Basicellercurl --user). En API-konto av typen passord, en underkonto eller den vanlige påloggingen til kontoen din godtas. Vi anbefaler en egen API-konto. Brukernavnet kan ikke inneholde kolon, og verken brukernavn eller passord kan være tomt. - Bearer-token (
Authorization: Bearer YOUR_TOKEN). Godtas for en API-konto av typen token. Tokenkontoer må ha en IP-begrensning, og forespørsler må komme fra en tillatt adresse. Begge API-vertene godtar IPv4-adressene og CIDR-områdene som er konfigurert for kontoen. Et token kan ikke sendes som et Basic-passord. Kontroller at tokenet fungerer på verten du bruker.
API_TOKEN="your-api-token"
curl --fail-with-body --silent --show-error \
-H "Authorization: Bearer $API_TOKEN" \
https://api.multi.tel/v3/speech_to_textHvis en API-konto er begrenset etter IP-adresse, må forespørsler sendes fra en tillatt adresse. Manglende eller ugyldige opplysninger gir 401. På api.multitel.net gir gyldige opplysninger som ikke kan bruke disse tjenestene, for eksempel en tokenkontos opplysninger sendt med Basic, 403 unsupported_transcription_principal eller unsupported_translation_principal. Gjentatte mislykkede autentiseringer fra samme adresse på api.multitel.net kan føre til at adressen blokkeres. Rett opplysningene før du prøver igjen.
Kontroller når behandlingen er ferdig
Send GET /v3/SERVICE/JOB_ID. Vi anbefaler å kontrollere høyst én gang hvert 3. sekund. Den ytre svarstrukturen beskriver forespørselen. Kontroller jobbens status for å finne ut om behandlingen er ferdig.
| Status | Betydning |
|---|---|
queued | Godtatt og venter. Jobber for én konto behandles én om gangen, vekselvis med andre kontoer. |
running | Behandles. progress kan være null; en null-verdi alene betyr ikke at jobben har stoppet opp. |
completed | Resultatet er tilgjengelig. Ta vare på det og sammenlign viktige detaljer med kilden. |
failed | Kontroller failureCode. Mislykket arbeid belastes ikke. Rett årsaken og send inn med en ny nøkkel. Hvis du sender samme nøkkel på nytt, returneres den samme mislykkede jobben. |
awaiting_payment | Behandlingen er ferdig, men den forhåndsbetalte saldoen kunne ikke dekke kostnaden. Resultatet er lagret og holdes tilbake til jobben er betalt. |
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"På api.multitel.net setter du HOST til https://api.multitel.net og leser .response.id i stedet for .data.id.
Prøv forespørsler med usikkert utfall på nytt på en trygg måte
Hvis en innsending får tidsavbrudd eller returnerer 429 eller en 5xx-status, sender du samme inndata på nytt med samme idempotensnøkkel. Et svar fra begge verter kan gå tapt eller bli erstattet med en feil etter at arbeidet er godtatt. Samme nøkkel returnerer jobben hvis den finnes. En nøkkel som gjenbrukes med andre inndata, gir 409 idempotency_conflict. Noen feil gjentas ved hvert forsøk, som 503 når en betalingstjeneste er deaktivert eller 500 for en lydfil som ikke kan leses. Stopp etter noen forsøk.
En endret nøkkel har ulike virkninger for de to tjenestene.
- For tale-til-tekst oppretter en ny nøkkel en ny jobb med separat kostnad hvis behandlingen lykkes. Den opprinnelige nøkkelen fortsetter å returnere den opprinnelige jobben, også etter en oppdatering av behandlingen.
- For oversettelse returnerer en ny nøkkel med identisk innhold en tilsvarende ventende, pågående, fullført eller betalingsventende jobb uten ny kostnad. Nytt arbeid opprettes hvis den tidligere jobben mislyktes eller behandlingsversjonen er endret. Et nytt oversettelsesforsøk med den opprinnelige nøkkelen gir 409 etter en versjonsendring. Ta derfor vare på den opprinnelige jobb-ID-en og les jobben direkte.
Frigi et resultat etter å ha fylt på saldo
For en jobb med status awaiting_payment fyller du på kontoen slik at saldoen minst tilsvarer jobbens costUsd avrundet opp til neste multiplum av $0.00001. Send deretter POST /v3/SERVICE/JOB_ID/settle. Belastninger skjer i hele trinn på $0.00001 og inkluderer eventuelle restbeløp fra tidligere jobber i samme tjeneste. Det belastede beløpet kan derfor overstige costUsd med mindre enn $0.00001. På api.multi.tel sender du JSON {} eller en tom kropp. Alle egenskaper i kroppen avvises med 400. api.multitel.net ignorerer kroppen. Betalingen frigir det lagrede resultatet uten å kjøre transkripsjon eller oversettelse på nytt. Svaret inneholder jobben. Kontroller at statusen er completed. Hvis saldoen fortsatt er for lav, forblir jobben awaiting_payment og svaret er fortsatt HTTP 200.
For tale-til-tekst returneres en allerede fullført jobb med duplicate: true når den betales, mens en ventende, pågående eller mislykket jobb gir 409 transcription_not_awaiting_payment. For oversettelse returneres jobber i alle andre statuser uendret. Betaling er bare tilgjengelig når betalt behandling er aktivert, ellers gis 503. Jobber som venter på betaling, regnes som reservert kostnad. For forhåndsbetalte kontoer kan de derfor blokkere nye betalte innsendinger med 402 til de er betalt.
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"Kontroller bruken
Bruk GET /v3/SERVICE/usage. De valgfrie parameterne from og to er UTC-datoer i formatet YYYY-MM-DD. Begge grensedatoene er inkludert. Hvis de utelates, blir from som standard datoen 30 dager før i dag og to dagens dato (UTC). to kan ikke være tidligere enn from. Datoene kan ligge høyst 366 dager fra hverandre, altså opptil 367 datoer med grensene inkludert. Ugyldige kalenderdatoer eller et omvendt eller lengre intervall gir 400, det samme gjør andre spørringsparametere på 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"Svaret inneholder mode, currency (USD), from, to og days, en liste med de nyeste oppføringene først.
- Oppføringer for tale-til-tekst grupperes etter dato og kilde. De inneholder
date,source(apiellerhpbxfor Hosted PBX-opptak),files,audioSeconds,billedSeconds,accruedUsdogdebitedUsd. - Oversettelsesoppføringer grupperes etter dato, kilde og motor. De inneholder
date,source,engine,jobs,sourceCharacters,accruedUsdogdebitedUsd.
accruedUsd er den nøyaktige kostnaden med ni desimaler, og debitedUsd er det belastede beløpet med fem. Bruk registreres på UTC-datoen da kostnaden for hver jobb ble betalt. Ventende, pågående, mislykkede og betalingsventende jobber vises derfor ikke.
Grenser
Hver konto kan ha høyst 50 utestående jobber for tale-til-tekst og oversettelse til sammen: ventende, pågående eller betalingsventende, inkludert arbeid med Hosted PBX-opptak. Når grensen eller tjenestens samlede kapasitet nås, returnerer innsendinger 429 transcription_queue_full eller translation_queue_full. api.multi.tel begrenser også hver klients IP-adresse til 300 forespørsler per minutt på tvers av alle forespørsler til den verten. Grensen gir 429 med hoder for hastighetsbegrensning og en kropp i ren tekst i stedet for JSON-feilstrukturen.
Håndter forespørselsfeil
På den primære verten gir feil en HTTP-feilstatus og JSON med status: "error", code, message og requestId. Hvert svar inneholder også et hode X-Request-ID. Du kan angi din egen verdi. Verdier over 128 tegn blir avkortet. Kompatibilitetsverten returnerer bare feilkoden i response.code. Logg forespørsels-ID-en når den er tilgjengelig, og feilkoden, men ikke ta med lyd, tekst eller påloggingsopplysninger i loggene.
Vanlige statuser:
| Status | Betydning |
|---|---|
| 400 | Ugyldige inndata. |
| 401 | Manglende eller ugyldige påloggingsopplysninger. |
| 402 | Utilstrekkelig forhåndsbetalt saldo. |
| 403 | På kompatibilitetsverten: opplysninger som ikke kan bruke disse tjenestene. |
| 404 | En ukjent jobb eller rute. |
| 405 | En metode som ikke støttes, eller en ukjent sti i en tjeneste. |
| 409 | Motstridende inndata, en oversettelse til samme språk eller betaling av en talejobb som ikke venter på betaling. |
| 413 | En for stor kropp eller fil. |
| 422 | Lyd som ikke støttes, eller et språkpar som ikke er tilgjengelig for standardoversettelse. |
| 429 | Grenser for kø, validering eller forespørselsfrekvens. |
| 500 | En uventet serverfeil, inkludert en lydfil som ikke kan leses. |
| 503 | En deaktivert eller midlertidig utilgjengelig tjeneste, eller påloggingsopplysninger som ikke kan kontrolleres akkurat nå. |
Følg den returnerte feilkoden i stedet for å anta at alle valideringsfeil har samme status.
For 429 eller 503 skal du vente og prøve igjen med økende intervaller og samme innsendingsnøkkel. Følg Retry-After når det er angitt. Ved ugyldige inndata eller opplysninger må du rette årsaken først. Ikke send inn nye nøkler gjentatte ganger mens tidligere jobber fortsatt venter.