Jobb för tal-till-text och översättning

Ersätt SERVICE nedan med speech_to_text eller translate och JOB_ID med det returnerade UUID:t. Alla åtgärder kräver inloggningsuppgifter för ditt konto enligt Autentisering och är begränsade till ägarkontot. Ett jobb kan läsas från båda API-värdarna, men de använder olika svarsstrukturer. Använd därför samma värd konsekvent.

På api.multitel.net returneras autentiseringsfel (401) innan denna svarsstruktur används och kan ha en annan svarskropp. Kontrollera HTTP-statusen innan du tolkar svaret.

Autentisering

Varje begäran måste innehålla inloggningsuppgifter för ditt konto. Jobb, idempotensnycklar, gränser, användning och avgifter tillhör kontot som äger uppgifterna. De delas av alla inloggningsuppgifter för samma konto på båda värdarna, oavsett vilka uppgifter som skickar en begäran.

• HTTP Basic (Authorization: Basic eller curl --user). Godkända uppgifter är ett API-konto av lösenordstyp, ett underkonto eller ditt kontos vanliga inloggning. Vi rekommenderar ett särskilt API-konto. Användarnamnet får inte innehålla kolon, och varken användarnamn eller lösenord får vara tomt.
• Bearer-token (Authorization: Bearer YOUR_TOKEN). Godtas för ett API-konto av tokentyp. Sådana konton måste ha en IP-begränsning och begäranden måste komma från en tillåten adress. Båda API-värdarna godtar kontots konfigurerade IPv4-adresser och CIDR-intervall. En token kan inte skickas som ett Basic-lösenord. Kontrollera att din token fungerar på värden du använder.

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

Om ett API-konto är begränsat till vissa IP-adresser ska begäranden skickas från en tillåten adress. Saknade eller ogiltiga uppgifter ger 401. På api.multitel.net ger giltiga uppgifter som inte kan använda dessa tjänster, till exempel ett tokenkontos uppgifter skickade med Basic, 403 unsupported_transcription_principal eller unsupported_translation_principal. Upprepade misslyckade autentiseringar från samma adress på api.multitel.net kan göra att adressen blockeras. Rätta uppgifterna innan du försöker igen.

Kontrollera när jobbet är klart

Skicka GET /v3/SERVICE/JOB_ID. Vi rekommenderar att du inte kontrollerar oftare än en gång var 3:e sekund. Den yttre svarsstrukturen beskriver begäran. Kontrollera jobbets status för att avgöra om bearbetningen är klar.

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 anger du HOST som https://api.multitel.net och läser .response.id i stället för .data.id.

Försök igen säkert när utfallet är oklart

Om en inskickning får timeout eller returnerar 429 eller en 5xx-status ska du skicka samma indata igen med samma idempotensnyckel. Ett svar från någon av värdarna kan gå förlorat eller ersättas av ett fel efter att arbetet har godtagits. Samma nyckel returnerar jobbet om det finns. En nyckel som återanvänds med andra indata ger 409 idempotency_conflict. Vissa fel upprepas vid varje försök, exempelvis 503 när en betaltjänst är avstängd eller 500 för en ljudfil som inte kan läsas. Sluta efter några försök.

En ändrad nyckel får olika följder för de olika tjänsterna.

• För tal-till-text skapar en ny nyckel ett nytt jobb med en separat avgift om bearbetningen lyckas. Den ursprungliga nyckeln fortsätter att returnera det ursprungliga jobbet även efter att bearbetningen har uppdaterats.
• För översättning returnerar en ny nyckel med identiskt innehåll ett matchande väntande, pågående, slutfört eller betalningsväntande jobb utan en ny avgift. Nytt arbete skapas om det tidigare jobbet misslyckades eller bearbetningsversionen har ändrats. Ett nytt översättningsförsök med den ursprungliga nyckeln ger 409 efter en versionsändring. Spara därför det ursprungliga jobb-ID:t och läs jobbet direkt.

Frigör ett resultat efter att ha fyllt på saldo

För ett jobb med status awaiting_payment fyller du på kontot så att saldot minst motsvarar jobbets costUsd avrundat uppåt till nästa multipel av $0.00001. Skicka sedan POST /v3/SERVICE/JOB_ID/settle. Debiteringar sker i hela steg om $0.00001 och omfattar eventuella restbelopp från tidigare jobb i samma tjänst. Det debiterade beloppet kan därför överstiga costUsd med mindre än $0.00001. På api.multi.tel skickar du JSON {} eller en tom kropp. Alla egenskaper i kroppen avvisas med 400. api.multitel.net ignorerar kroppen. Betalningen frigör det sparade resultatet utan att köra transkribering eller översättning igen. Svaret innehåller jobbet. Kontrollera att dess status är completed. Om saldot fortfarande är för lågt förblir jobbet awaiting_payment och svaret är fortfarande HTTP 200.

För tal-till-text returneras ett redan slutfört jobb med duplicate: true när det betalas, medan ett väntande, pågående eller misslyckat jobb ger 409 transcription_not_awaiting_payment. För översättning returneras jobb i alla andra statusar oförändrade. Betalning är bara tillgänglig när betald bearbetning är aktiverad, annars ges 503. Jobb som väntar på betalning räknas som reserverad kostnad. För förbetalda konton kan de därför blockera nya betalda inskickningar med 402 tills de har betalats.

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"

Kontrollera användningen

Använd GET /v3/SERVICE/usage. De valfria parametrarna from och to är UTC-datum i formatet YYYY-MM-DD. Båda gränsdatumen ingår. Om de utelämnas blir from som standard datumet 30 dagar före i dag och to dagens datum (UTC). to får inte vara tidigare än from. Datumen får ligga högst 366 dagar från varandra, vilket ger upp till 367 datum inklusive gränserna. Ogiltiga kalenderdatum eller ett omvänt eller längre intervall ger 400, liksom andra frågeparametrar 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 innehåller mode, currency (USD), from, to och days, en lista med de senaste posterna först.

• Poster för tal-till-text grupperas efter datum och källa. De innehåller date, source (api eller hpbx för Hosted PBX-inspelningar), files, audioSeconds, billedSeconds, accruedUsd och debitedUsd.
• Översättningsposter grupperas efter datum, källa och motor. De innehåller date, source, engine, jobs, sourceCharacters, accruedUsd och debitedUsd.

accruedUsd är den exakta kostnaden med nio decimaler, och debitedUsd är det debiterade beloppet med fem. Användning registreras på UTC-datumet då varje jobbs avgift betalas. Väntande, pågående, misslyckade och betalningsväntande jobb visas därför inte.

Gränser

Varje konto kan ha högst 50 utestående jobb för tal-till-text och översättning sammanlagt: väntande, pågående eller betalningsväntande, inklusive arbete med Hosted PBX-inspelningar. När den gränsen eller tjänstens totala kapacitet nås returnerar inskickningar 429 transcription_queue_full eller translation_queue_full. api.multi.tel begränsar också varje klients IP-adress till 300 begäranden per minut för alla begäranden till den värden tillsammans. Gränsen ger 429 med huvuden för anropsbegränsning och en svarskropp i ren text i stället för JSON-felstrukturen.

Hantera fel i begäranden

På den primära värden ger fel en HTTP-felstatus och JSON med status: "error", code, message och requestId. Varje svar innehåller även ett huvud X-Request-ID. Du kan ange ett eget värde. Värden över 128 tecken kapas. Kompatibilitetsvärden returnerar bara felkoden i response.code. Logga begärans ID när det finns och felkoden, men ta inte med ljud, text eller inloggningsuppgifter i loggar.

Vanliga statusar:

Följ den returnerade felkoden i stället för att anta att alla valideringsfel har samma status.

För 429 eller 503 ska du vänta och försöka igen med ökande intervall och samma inskickningsnyckel. Följ Retry-After när det finns. Vid ogiltiga indata eller uppgifter ska orsaken rättas först. Skicka inte upprepade nya nycklar medan tidigare jobb fortfarande väntar.