Erstat SERVICE nedenfor med speech_to_text eller translate og JOB_ID med det returnerede UUID. Alle handlinger kræver loginoplysninger til din konto som beskrevet under Godkendelse og er afgrænset til ejerkontoen. Et job kan læses fra begge API-værter, men de bruger forskellige svarstrukturer. Brug derfor den samme vært konsekvent.
| Vært | Vellykket svar | Fejl |
|---|---|---|
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 godkendelsesfejl (401), før denne svarstruktur anvendes, og svarets indhold kan være anderledes. Kontrollér HTTP-status, før du fortolker svaret.
Godkendelse
Hver anmodning skal indeholde loginoplysninger til din konto. Job, idempotensnøgler, grænser, forbrug og gebyrer tilhører den konto, som ejer oplysningerne. De deles af alle loginoplysninger til den pågældende konto på begge værter, uanset hvilke der sender anmodningen.
- HTTP Basic (
Authorization: Basicellercurl --user). Der accepteres en API-konto af typen adgangskode, en underkonto eller din kontos almindelige login. Vi anbefaler en særskilt API-konto. Brugernavnet må ikke indeholde et kolon, og hverken brugernavn eller adgangskode må være tomt. - Bearer-token (
Authorization: Bearer YOUR_TOKEN). Accepteres for en API-konto af typen token. Tokenkonti skal have en IP-begrænsning, og anmodninger skal komme fra en tilladt adresse. Begge API-værter accepterer de IPv4-adresser og CIDR-intervaller, der er konfigureret for kontoen. Et token kan ikke sendes som en Basic-adgangskode. Kontrollér, at dit token virker på den vært, du bruger.
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 begrænset efter IP-adresse, skal anmodninger sendes fra en tilladt adresse. Manglende eller ugyldige oplysninger giver 401. På api.multitel.net giver gyldige oplysninger, som ikke kan bruge disse tjenester, eksempelvis en tokenkontos oplysninger sendt med Basic, 403 unsupported_transcription_principal eller unsupported_translation_principal. Gentagne mislykkede godkendelser fra samme adresse på api.multitel.net kan medføre, at adressen blokeres. Ret oplysningerne, før du prøver igen.
Kontrollér, hvornår jobbet er færdigt
Send GET /v3/SERVICE/JOB_ID. Vi anbefaler højst at kontrollere én gang hvert 3. sekund. Den ydre svarstruktur beskriver anmodningen. Kontrollér jobbets status for at afgøre, om behandlingen er færdig.
| Status | Betydning |
|---|---|
queued | Accepteret og venter. Job for én konto behandles ét ad gangen, skiftevis med andre konti. |
running | Behandles. progress kan være null; en null-værdi betyder ikke i sig selv, at jobbet er gået i stå. |
completed | Resultatet er tilgængeligt. Gem det, og sammenlign vigtige oplysninger med kilden. |
failed | Kontrollér failureCode. Mislykket arbejde faktureres ikke. Ret årsagen, og indsend med en ny nøgle. Hvis du sender den samme nøgle igen, returneres det samme mislykkede job. |
awaiting_payment | Behandlingen er færdig, men den forudbetalte saldo kunne ikke dække gebyret. Resultatet er gemt og tilbageholdes, indtil jobbet 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 sætter du HOST til https://api.multitel.net og læser .response.id i stedet for .data.id.
Gentag anmodninger med usikkert udfald sikkert
Hvis en indsendelse får timeout eller returnerer 429 eller en 5xx-status, skal du sende de samme input igen med den samme idempotensnøgle. Et svar fra begge værter kan gå tabt eller erstattes af en fejl, efter at arbejdet er accepteret. Den samme nøgle returnerer jobbet, hvis det findes. Genbrug af en nøgle med andre input giver 409 idempotency_conflict. Visse fejl gentages ved hvert forsøg, eksempelvis 503, mens en betalingstjeneste er deaktiveret, eller 500 for en lydfil, der ikke kan læses. Stop efter nogle få forsøg.
En ændret nøgle har forskellige virkninger for de enkelte tjenester.
- Ved tale-til-tekst opretter en ny nøgle et nyt job med et særskilt gebyr, hvis behandlingen lykkes. Den oprindelige nøgle fortsætter med at returnere det oprindelige job, også efter en opdatering af behandlingen.
- Ved oversættelse returnerer en ny nøgle med identisk indhold et tilsvarende ventende, igangværende, afsluttet eller betalingsafventende job uden et nyt gebyr. Der oprettes nyt arbejde, hvis det tidligere job mislykkedes, eller behandlingsversionen er ændret. Et nyt oversættelsesforsøg med den oprindelige nøgle giver 409 efter en versionsændring. Gem derfor det oprindelige job-ID, og læs jobbet direkte.
Frigiv et resultat efter at have indbetalt penge
For et job med status awaiting_payment skal du indbetale, så saldoen mindst svarer til jobbets costUsd afrundet op til det næste multiplum af $0.00001. Send derefter POST /v3/SERVICE/JOB_ID/settle. Debiteringer sker i hele trin på $0.00001 og omfatter eventuelle restbeløb fra tidligere job i den samme tjeneste. Det debiterede beløb kan derfor overstige costUsd med mindre end $0.00001. På api.multi.tel sender du JSON {} eller en tom krop. Alle egenskaber i kroppen afvises med 400. api.multitel.net ignorerer kroppen. Betalingen frigiver det gemte resultat uden at køre transskription eller oversættelse igen. Svaret indeholder jobbet. Kontrollér, at dets status er completed. Hvis saldoen stadig er for lav, forbliver jobbet awaiting_payment, og svaret er stadig HTTP 200.
Ved tale-til-tekst returneres et allerede afsluttet job med duplicate: true ved betaling, mens et ventende, igangværende eller mislykket job giver 409 transcription_not_awaiting_payment. Ved oversættelse returneres job i alle andre statusser uændret. Betaling er kun tilgængelig, når betalt behandling er aktiveret, ellers gives 503. Job, der afventer betaling, tæller som reserverede omkostninger. For forudbetalte konti kan de derfor blokere nye betalte indsendelser med 402, indtil 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"Kontrollér forbruget
Brug GET /v3/SERVICE/usage. De valgfrie parametre from og to er UTC-datoer i formatet YYYY-MM-DD. Begge grænsedatoer er inkluderet. Hvis de udelades, bliver from som standard datoen 30 dage før i dag og to dags dato (UTC). to må ikke ligge før from. Datoerne må højst ligge 366 dage fra hinanden, altså op til 367 datoer inklusive grænserne. Ugyldige kalenderdatoer eller et omvendt eller længere interval giver 400, ligesom andre forespørgselsparametre 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 indeholder mode, currency (USD), from, to og days, en liste med de nyeste poster først.
- Poster for tale-til-tekst grupperes efter dato og kilde. De indeholder
date,source(apiellerhpbxfor Hosted PBX-optagelser),files,audioSeconds,billedSeconds,accruedUsdogdebitedUsd. - Oversættelsesposter grupperes efter dato, kilde og motor. De indeholder
date,source,engine,jobs,sourceCharacters,accruedUsdogdebitedUsd.
accruedUsd er den præcise pris med ni decimaler, og debitedUsd er det debiterede beløb med fem. Forbruget registreres på UTC-datoen, hvor gebyret for hvert job betales. Ventende, igangværende, mislykkede og betalingsafventende job vises derfor ikke.
Grænser
Hver konto kan have højst 50 udestående job for tale-til-tekst og oversættelse i alt: ventende, igangværende eller betalingsafventende, inklusive arbejde med Hosted PBX-optagelser. Når denne grænse eller tjenestens samlede kapacitet nås, returnerer indsendelser 429 transcription_queue_full eller translation_queue_full. api.multi.tel begrænser desuden hver klient-IP-adresse til 300 anmodninger pr. minut på tværs af alle anmodninger til den vært. Grænsen giver 429 med headere for hastighedsbegrænsning og en krop i ren tekst i stedet for JSON-fejlstrukturen.
Håndtér fejl i anmodninger
På den primære vært giver fejl en HTTP-fejlstatus og JSON med status: "error", code, message og requestId. Hvert svar indeholder desuden en header X-Request-ID. Du kan angive din egen værdi. Værdier over 128 tegn afkortes. Kompatibilitetsværten returnerer kun fejlkoden i response.code. Log anmodnings-ID’et, når det er tilgængeligt, og fejlkoden, men medtag ikke lyd, tekst eller loginoplysninger i loggene.
Almindelige statusser:
| Status | Betydning |
|---|---|
| 400 | Ugyldige input. |
| 401 | Manglende eller ugyldige loginoplysninger. |
| 402 | Utilstrækkelig forudbetalt saldo. |
| 403 | På kompatibilitetsværten: oplysninger, som ikke kan bruge disse tjenester. |
| 404 | Et ukendt job eller en ukendt rute. |
| 405 | En metode, der ikke understøttes, eller en ukendt sti i en tjeneste. |
| 409 | Modstridende input, en oversættelse til samme sprog eller betaling af et talejob, som ikke afventer betaling. |
| 413 | En for stor krop eller fil. |
| 422 | Lyd, der ikke understøttes, eller et sprogpar, som ikke er tilgængeligt til standardoversættelse. |
| 429 | Grænser for kø, validering eller anmodningsfrekvens. |
| 500 | En uventet serverfejl, inklusive en lydfil, der ikke kan læses. |
| 503 | En deaktiveret eller midlertidigt utilgængelig tjeneste eller loginoplysninger, som ikke kan kontrolleres lige nu. |
Følg den returnerede fejlkode i stedet for at antage, at alle valideringsfejl har samme status.
For 429 eller 503 skal du vente og prøve igen med stigende intervaller og den samme indsendelsesnøgle. Følg Retry-After, når den er angivet. Ved ugyldige input eller oplysninger skal årsagen rettes først. Indsend ikke gentagne gange nye nøgler, mens tidligere job stadig venter.