Job di trascrizione e traduzione

Sostituisci SERVICE qui sotto con speech_to_text oppure translate, e JOB_ID con l’UUID ricevuto. Tutte le operazioni richiedono le credenziali del tuo account, come descritto in Autenticazione, e sono limitate all’account proprietario. Un job può essere letto da entrambi gli host API, ma ciascuno usa una propria struttura di risposta: utilizza quindi sempre lo stesso host.

Su api.multitel.net, gli errori di autenticazione (401) vengono restituiti prima di applicare questa struttura e possono avere un corpo diverso. Controlla lo stato HTTP prima di interpretare la risposta.

Autenticazione

Ogni richiesta deve contenere le credenziali del tuo account. Job, chiavi di idempotenza, limiti, dati di utilizzo e addebiti appartengono all’account proprietario delle credenziali. Sono condivisi da tutte le credenziali di quell’account su entrambi gli host, indipendentemente da quelle utilizzate per inviare la richiesta.

• HTTP Basic (Authorization: Basic, oppure curl --user). Sono accettati un account API di tipo password, un sottoaccount o le credenziali di accesso del tuo account. Consigliamo un account API dedicato. Il nome utente non può contenere i due punti e né il nome utente né la password possono essere vuoti.
• Token Bearer (Authorization: Bearer YOUR_TOKEN). Accettato per un account API di tipo token. Questi account devono avere una restrizione IP e le richieste devono provenire da un indirizzo consentito. Entrambi gli host API accettano gli indirizzi IPv4 e gli intervalli CIDR configurati per l’account. Un token non può essere inviato come password Basic. Verifica che il token funzioni sull’host utilizzato.

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

Se un account API ha restrizioni per indirizzo IP, invia le richieste da un indirizzo consentito. Credenziali mancanti o non valide restituiscono 401. Su api.multitel.net, credenziali valide ma non utilizzabili per questi servizi, come quelle di un account di tipo token inviate tramite Basic, restituiscono 403 unsupported_transcription_principal oppure unsupported_translation_principal. Errori di autenticazione ripetuti dallo stesso indirizzo su api.multitel.net possono causare il blocco dell’indirizzo. Correggi le credenziali prima di riprovare.

Controllare il completamento

Invia una richiesta GET /v3/SERVICE/JOB_ID. Consigliamo di interrogare il servizio non più di una volta ogni 3 secondi. La struttura esterna descrive la richiesta; controlla il campo status del job per sapere se l’elaborazione è terminata.

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"

Su api.multitel.net, imposta HOST su https://api.multitel.net e leggi .response.id invece di .data.id.

Riprovare in sicurezza le richieste dall’esito incerto

Se un invio scade o restituisce 429 o uno stato 5xx, reinvia gli stessi dati con la stessa chiave di idempotenza. La risposta di uno dei due host può andare persa o essere sostituita da un errore dopo l’accettazione del lavoro; reinviare la stessa chiave restituisce il job, se esiste. Riutilizzare una chiave con dati diversi restituisce 409 idempotency_conflict. Alcuni errori si ripetono a ogni tentativo, come 503 mentre un servizio a pagamento è disattivato o 500 per un file audio illeggibile. Fermati dopo alcuni tentativi.

Cambiare chiave ha effetti diversi per ciascun servizio.

• Per la trascrizione audio, una nuova chiave crea un nuovo job, con un addebito separato se l’elaborazione riesce. La chiave originale continua a restituire il job originale, anche dopo un aggiornamento dell’elaborazione.
• Per la traduzione, una nuova chiave con contenuto identico restituisce senza nuovi addebiti un job corrispondente in attesa, in esecuzione, completato o in attesa di pagamento. Crea nuovo lavoro se il job precedente non è riuscito o la versione di elaborazione è cambiata. Un nuovo tentativo di traduzione con la chiave originale restituisce 409 dopo un cambio di versione di elaborazione: conserva quindi l’ID del job originale e leggilo direttamente.

Sbloccare un risultato dopo aver aggiunto fondi

Per un job nello stato awaiting_payment, aggiungi fondi affinché il saldo sia almeno pari al valore costUsd del job, arrotondato per eccesso al multiplo successivo di $0.00001, quindi invia POST /v3/SERVICE/JOB_ID/settle. Gli addebiti avvengono in incrementi interi di $0.00001 e includono l’eventuale resto riportato dai job precedenti dello stesso servizio. L’importo addebitato può quindi superare costUsd di meno di $0.00001. Su api.multi.tel, invia il JSON {} oppure un corpo vuoto; qualsiasi proprietà nel corpo viene rifiutata con 400. api.multitel.net ignora il corpo. Il saldo del job sblocca il risultato salvato senza eseguire nuovamente la trascrizione o la traduzione. La risposta contiene il job: verifica che il suo stato sia completed. Se il saldo è ancora insufficiente, il job rimane nello stato awaiting_payment e la risposta resta HTTP 200.

Per la trascrizione audio, saldare un job già completato lo restituisce con duplicate: true, mentre saldare un job in attesa, in esecuzione o non riuscito restituisce 409 transcription_not_awaiting_payment. Per la traduzione, saldare un job in qualsiasi altro stato lo restituisce senza modifiche. Il saldo dei job è disponibile solo quando l’elaborazione a pagamento è abilitata (altrimenti 503). I job in attesa di pagamento rientrano nel costo riservato: per gli account prepagati possono quindi bloccare i nuovi invii a pagamento con 402 finché non vengono saldati.

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"

Controllare l’utilizzo

Usa GET /v3/SERVICE/usage. I parametri facoltativi from e to sono date UTC nel formato YYYY-MM-DD, ed entrambe le date limite sono incluse. Se omessi, from assume come valore predefinito la data di 30 giorni fa e to la data di oggi (UTC). to non deve precedere from, e le date possono distare al massimo 366 giorni (fino a 367 date incluse). Date di calendario non valide o un intervallo invertito o più lungo restituiscono 400, così come altri parametri di query su 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"

La risposta contiene mode, currency (USD), from, to e days, un elenco ordinato dalle voci più recenti.

• Le voci di trascrizione audio sono raggruppate per data e fonte. Contengono date, source (api, oppure hpbx per le registrazioni Hosted PBX), files, audioSeconds, billedSeconds, accruedUsd e debitedUsd.
• Le voci di traduzione sono raggruppate per data, fonte e motore. Contengono date, source, engine, jobs, sourceCharacters, accruedUsd e debitedUsd.

accruedUsd è il costo esatto con nove cifre decimali, mentre debitedUsd è l’importo addebitato, con cinque. L’utilizzo viene registrato alla data UTC in cui viene saldato l’addebito di ogni job: i job in attesa, in esecuzione, non riusciti o in attesa di pagamento non compaiono.

Limiti

Ogni account può avere al massimo 50 job di trascrizione audio e traduzione non conclusi complessivamente: in attesa, in esecuzione o in attesa di pagamento, inclusi quelli relativi alle registrazioni Hosted PBX. Quando viene raggiunto questo limite o la capacità complessiva del servizio, gli invii restituiscono 429 transcription_queue_full oppure translation_queue_full. api.multi.tel limita inoltre ogni indirizzo IP client a 300 richieste al minuto, considerando tutte le richieste verso quell’host. Questa limitazione restituisce 429 con intestazioni di limitazione della frequenza e un corpo di testo semplice, invece della struttura JSON di errore.

Gestire gli errori delle richieste

Sull’host principale, gli errori restituiscono uno stato HTTP di errore e JSON con status: "error", code, message e requestId. Ogni risposta include anche un’intestazione X-Request-ID. Puoi fornire un tuo valore; i valori superiori a 128 caratteri vengono troncati. L’host di compatibilità restituisce soltanto il codice di errore in response.code. Registra l’ID della richiesta, se disponibile, e il codice di errore, senza includere audio, testo o credenziali nei log.

Stati comuni:

Segui il codice di errore restituito, senza presumere che tutti gli errori di validazione abbiano lo stesso stato.

Per 429 o 503, attendi e riprova con intervalli crescenti e la stessa chiave di invio; rispetta Retry-After quando presente. Per input o credenziali non validi, correggi prima la causa. Non inviare ripetutamente nuove chiavi mentre i job precedenti sono ancora in attesa.