Skip to main content

Batch

In modalità Batch, l'utente carica un file audio intero ed effettua una richiesta HTTP POST alla nostra infrastruttura per richiederne il processamento.

Autenticazione​

Per poter effettuare richieste, è necessario risultare autenticati ed includere la propria chiave come header Litus-AI-Scripta-Key in ogni richiesta:

curl \
    'https://scripta.litus.ai/api/v1/batch/speech/sync-transcribe' \
    -X 'POST' \
    -H 'Litus-AI-Scripta-Key: <your-key>' \
    ...

Endpoint Disponibili​

Scripta supporta due possibili endpoint per l'utilizzo:

  • sync
  • async (consigliata)
info

Nei prossimi due esempi, invieremo il file audio tramite uno URL pubblico, che Scripta procederà poi a scaricare automaticamente. Più avanti, vedremo altre modalità di upload.

Sync​

L'utente manda una richiesta con un file audio e Scripta risponde con il corrispondente risultato.

warning

Questo endpoint è disponibile solo per file audio con durata massima di 300 secondi e dimensione inferiore a 10MB.

curl \
    'https://scripta.litus.ai/api/v1/batch/speech/sync-transcribe' \
    -X 'POST' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Litus-AI-Scripta-Key: <your-key>' \
    -d '{"url": "<public-url-from-which-the-audio-can-be-downloaded>"}'
tip

Per ottenere un risultato più leggibile, si consiglia di usare jq per formattare la risposta (curl ... | jq).

A questa chiamata, Scripta risponderà con:

{
  "status": "finished",
  "task_id": "<task-id>",
  "result": {
    "segments": [
      {
        "start": 0,
        "end": 1000,
        "speaker": "Speaker 0", // campo opzionale, a seconda del piano collegato alla chiave e della richiesta effettuata
        "text": "<transcription>"
      },
      // ...
    ]
  }
}

Async​

In questo caso, l'utente manda una richiesta con un file audio ma il suo processamento è asincrono: Scripta risponderà con un ID associato alla richiesta e l'utente dovrà usare questo ID per far polling - interrogare periodicamente il sistema - in attesa del suo completamento.

Facendo un esempio, ricevuta la richiesta:

curl \
    'https://scripta.litus.ai/api/v1/batch/speech/async-transcribe' \
    -X 'POST' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Litus-AI-Scripta-Key: <your-key>' \
    -d '{"url": "<public-url-from-which-the-audio-can-be-downloaded>"}'
warning

L'endpoint è cambiato da [...]/sync-stt a [...]/async-stt.

Scripta risponderà con:

{
  "status": "running",
  "task_id": "<task-id>",
  "message": "Task still running"
}

A questo punto, l'utente dovrà far polling in attesa del completamento del processamento del file audio inviato:

curl \
    'https://scripta.litus.ai/api/v1/status/<task-id>' \
    -X 'GET' \
    -H 'Accept: application/json' \
    -H 'Litus-AI-Scripta-Key: <your-key>'

A ogni richiesta, Scripta risponderà in uno dei due seguenti modi, a seconda dello stato del processamento:

  • se ancora in corso:
{"status": "running", "task_id": "<task-id>", "message": "Task is still running"}
  • se completato:
{
  "status": "finished",
  "task_id": "<task-id>",
  "result": {
    "segments": [
      {
        "start": 0,
        "end": 1000,
        "speaker": "Speaker 0", // campo opzionale, a seconda del piano collegato alla chiave e della richiesta effettuata
        "text": "<transcription>"
      },
      // ...
    ]
  }
}
danger

Per gestire possibili usi malevoli del sistema, Scripta applica strategie di rate limiting sull'endpoint di polling. Per evitare possibili blocchi, si sconsiglia di effettuare più di una richiesta al secondo per task.

Upload​

Per fornire l'audio a Scripta, l'utente ha a disposizione 3 opzioni per entrambi gli endpoint.

URL Pubblico​

L'utente fornisce nella richiesta un URL pubblico (per esempio, su Amazon S3) da cui Scripta andrà a scaricare il file audio.

curl \
    'https://scripta.litus.ai/api/v1/batch/speech/async-transcribe' \
    -X 'POST' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Litus-AI-Scripta-Key: <your-key>' \
    -d '{"url": "<public-url-from-which-the-audio-can-be-downloaded>"}'

Il Content-Type della richiesta deve essere application/json e lo URL desiderato deve essere fornito nel campo url nel payload JSON.

Bytes Audio nel Body​

L'utente fornisce il file audio inviando i relativi bytes direttamente nel body della richiesta HTTP.

curl \
    'https://scripta.litus.ai/api/v1/batch/speech/async-transcribe' \
    -X 'POST' \
    -H 'Litus-AI-Scripta-Key: <your-key>' \
    -H 'Content-Type: application/octet-stream' \
    --data-binary @path/to/your/file.mp3
info

Il content-type "application/octet-stream" deve essere necessariamente specificato.

Richiesta Multipart​

L'utente fornisce il file audio inviandolo tramite richiesta multipart/form-data.

curl \
    'https://scripta.litus.ai/api/v1/batch/speech/async-transcribe' \
    -X 'POST' \
    -H 'Litus-AI-Scripta-Key: <your-key>' \
    -H "Content-Type: multipart/form-data" \
    -F "file=@path/to/your/file.wav"