Taken voor spraak-naar-tekst en vertaling

Vervang SERVICE hieronder door speech_to_text of translate en JOB_ID door de ontvangen UUID. Voor alle bewerkingen zijn de inloggegevens van je account vereist, zoals beschreven bij Authenticatie. Ze zijn beperkt tot het account dat eigenaar is. Je kunt een taak via beide API-hosts uitlezen, maar elke host gebruikt een eigen antwoordstructuur. Gebruik daarom steeds dezelfde host.

Op api.multitel.net worden authenticatiefouten (401) teruggestuurd voordat deze antwoordstructuur wordt toegepast. De inhoud kan daardoor afwijken. Controleer de HTTP-status voordat je het antwoord verwerkt.

Authenticatie

Elk verzoek moet de inloggegevens van je account bevatten. Taken, idempotentiesleutels, limieten, gebruik en kosten behoren toe aan het account dat eigenaar is van de inloggegevens. Ze worden op beide hosts gedeeld door alle inloggegevens van dat account, ongeacht welke het verzoek versturen.

• HTTP Basic (Authorization: Basic of curl --user). Een API-account van het type wachtwoord, een subaccount of de inloggegevens van je account worden geaccepteerd. We raden een apart API-account aan. De gebruikersnaam mag geen dubbele punt bevatten en zowel de gebruikersnaam als het wachtwoord mogen niet leeg zijn.
• Bearer-token (Authorization: Bearer YOUR_TOKEN). Geaccepteerd voor een API-account van het type token. Token-API-accounts moeten een IP-beperking hebben en verzoeken moeten van een toegestaan adres komen. Beide API-hosts accepteren de IPv4-adressen en CIDR-bereiken die voor het account zijn ingesteld. Je kunt een token niet als Basic-wachtwoord verzenden. Controleer of je token werkt op de host die je gebruikt.

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

Heeft een API-account een IP-beperking, verstuur verzoeken dan vanaf een toegestaan adres. Ontbrekende of ongeldige inloggegevens leveren 401 op. Op api.multitel.net leveren geldige inloggegevens die deze diensten niet kunnen gebruiken, zoals de gegevens van een tokenaccount die via Basic worden verstuurd, 403 unsupported_transcription_principal of unsupported_translation_principal op. Herhaalde mislukte authenticatie vanaf hetzelfde adres op api.multitel.net kan ertoe leiden dat dit adres wordt geblokkeerd. Corrigeer de inloggegevens voordat je het opnieuw probeert.

Controleren of de verwerking klaar is

Verstuur GET /v3/SERVICE/JOB_ID. We raden aan om niet vaker dan eens per 3 seconden te controleren. De buitenste antwoordstructuur beschrijft het verzoek; controleer het veld status van de taak om vast te stellen of de verwerking klaar 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"

Stel op api.multitel.net de waarde van HOST in op https://api.multitel.net en lees .response.id in plaats van .data.id.

Onzekere verzoeken veilig opnieuw proberen

Als een indiening een time-out geeft of 429 of een 5xx-status retourneert, verstuur dan dezelfde invoer opnieuw met dezelfde idempotentiesleutel. Een antwoord van beide hosts kan verloren gaan of door een fout worden vervangen nadat de verwerking is geaccepteerd. Dezelfde sleutel opnieuw versturen geeft de taak terug als die bestaat. Een sleutel opnieuw gebruiken met andere invoer geeft 409 idempotency_conflict. Sommige fouten komen bij elke poging terug, zoals 503 zolang een betaalde dienst is uitgeschakeld of 500 voor een onleesbaar audiobestand. Stop na enkele pogingen.

Een andere sleutel heeft per dienst een ander effect.

• Bij spraak-naar-tekst maakt een nieuwe sleutel een nieuwe taak aan, die apart wordt gefactureerd als de verwerking slaagt. De oorspronkelijke sleutel blijft de oorspronkelijke taak teruggeven, ook nadat de verwerking is bijgewerkt.
• Bij vertaling geeft een nieuwe sleutel met identieke inhoud zonder nieuwe kosten een overeenkomende wachtende, lopende, voltooide of op betaling wachtende taak terug. Er wordt nieuw werk aangemaakt als de eerdere taak is mislukt of de verwerkingsversie is gewijzigd. Een vertaalpoging met de oorspronkelijke sleutel geeft 409 na een wijziging van de verwerkingsversie. Bewaar daarom de oorspronkelijke taak-ID en lees de taak rechtstreeks uit.

Een resultaat vrijgeven na het opwaarderen

Vul voor een taak met status awaiting_payment je saldo aan tot ten minste de waarde costUsd van de taak, naar boven afgerond op het volgende veelvoud van $0.00001, en verstuur vervolgens POST /v3/SERVICE/JOB_ID/settle. Afschrijvingen gebeuren in hele stappen van $0.00001 en omvatten een eventueel overgedragen restbedrag van eerdere taken van dezelfde dienst. Het afgeschreven bedrag kan daardoor costUsd met minder dan $0.00001 overschrijden. Verstuur op api.multi.tel JSON {} of een lege inhoud; elke eigenschap in de inhoud wordt met 400 geweigerd. api.multitel.net negeert de inhoud. Afrekenen geeft het opgeslagen resultaat vrij zonder de transcriptie of vertaling opnieuw uit te voeren. Het antwoord bevat de taak; controleer of de status completed is. Is het saldo nog steeds onvoldoende, dan blijft de taak in status awaiting_payment en blijft het antwoord HTTP 200.

Bij spraak-naar-tekst geeft het afrekenen van een al voltooide taak deze terug met duplicate: true. Het afrekenen van een wachtende, lopende of mislukte taak geeft 409 transcription_not_awaiting_payment. Bij vertaling geeft afrekenen een taak met elke andere status ongewijzigd terug. Afrekenen is alleen beschikbaar zolang betaalde verwerking is ingeschakeld, anders volgt 503. Taken die op betaling wachten tellen mee als gereserveerde kosten. Bij prepaidaccounts kunnen ze daardoor nieuwe betaalde indieningen met 402 blokkeren totdat ze zijn afgerekend.

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"

Gebruik controleren

Gebruik GET /v3/SERVICE/usage. De optionele parameters from en to zijn UTC-datums in de indeling YYYY-MM-DD. Beide grensdatums zijn inbegrepen. Als ze ontbreken, is from standaard de datum van 30 dagen geleden en to de datum van vandaag (UTC). to mag niet vóór from liggen. De datums mogen maximaal 366 dagen uit elkaar liggen, dus maximaal 367 datums inclusief de grenzen. Ongeldige kalenderdatums en omgekeerde of langere periodes geven 400, net als andere queryparameters 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"

Het antwoord bevat mode, currency (USD), from, to en days, een lijst met de nieuwste gegevens eerst.

• Gegevens voor spraak-naar-tekst worden gegroepeerd op datum en bron. Ze bevatten date, source (api of hpbx voor Hosted PBX-opnamen), files, audioSeconds, billedSeconds, accruedUsd en debitedUsd.
• Vertaalgegevens worden gegroepeerd op datum, bron en engine. Ze bevatten date, source, engine, jobs, sourceCharacters, accruedUsd en debitedUsd.

accruedUsd is het exacte bedrag met negen decimalen, en debitedUsd is het afgeschreven bedrag met vijf decimalen. Gebruik wordt geregistreerd op de UTC-datum waarop de kosten van elke taak zijn afgerekend. Wachtende, lopende, mislukte en op betaling wachtende taken verschijnen daarom niet.

Limieten

Elk account kan in totaal maximaal 50 openstaande taken voor spraak-naar-tekst en vertaling hebben: wachtend, lopend of op betaling wachtend, inclusief verwerking van Hosted PBX-opnamen. Bij het bereiken van deze limiet of de totale capaciteit van de dienst geven indieningen 429 transcription_queue_full of translation_queue_full. api.multi.tel beperkt daarnaast elk client-IP-adres tot 300 verzoeken per minuut voor alle verzoeken aan die host samen. Deze limiet geeft 429 met headers voor de verzoeklimiet en platte tekst als inhoud, in plaats van de JSON-foutstructuur.

Verzoekfouten afhandelen

Op de primaire host geven fouten een HTTP-foutstatus en JSON met status: "error", code, message en requestId. Elk antwoord bevat ook een header X-Request-ID. Je kunt je eigen waarde opgeven; waarden langer dan 128 tekens worden afgekapt. De compatibiliteitshost geeft alleen de foutcode terug in response.code. Leg de verzoek-ID vast als die beschikbaar is, samen met de foutcode, maar neem geen audio, tekst of inloggegevens op in logboeken.

Veelvoorkomende statussen:

Volg de geretourneerde foutcode in plaats van aan te nemen dat elke validatiefout dezelfde status heeft.

Wacht bij 429 of 503 en probeer opnieuw met oplopende wachttijden en dezelfde indieningssleutel. Respecteer Retry-After als die aanwezig is. Verhelp bij ongeldige invoer of inloggegevens eerst de oorzaak. Dien niet herhaaldelijk nieuwe sleutels in terwijl eerdere taken nog in de wachtrij staan.