Tre esempi, con i numeri misurati

Ogni numero di questa pagina viene da una chiamata vera all'interfaccia pubblica, fatta il 22 settembre 2026, ripetuta tre volte. Niente è stimato. Il codice si copia e si esegue: se i vostri numeri sono diversi dai nostri, quella differenza è un'informazione, e ci interessa saperla.

Serve solo una chiave e il vostro base_url:

export SIATI_API_KEY="sk-siati-…"
export SIATI_BASE_URL="https://api.siati.ai/v1"

1. Estrarre i campi da una fattura#

Il caso di una fiduciaria: una fattura fornitore diventa una riga di prima nota. Con json_schema la risposta è un oggetto con quei campi e quei tipi, non «di solito».

curl $SIATI_BASE_URL/chat/completions \
  -H "Authorization: Bearer $SIATI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma-4-26b",
    "temperature": 0,
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "fattura",
        "schema": {
          "type": "object",
          "properties": {
            "numero_documento": {"type": "string"},
            "data_emissione":   {"type": "string"},
            "data_scadenza":    {"type": "string"},
            "fornitore":        {"type": "string"},
            "imponibile":       {"type": "number"},
            "aliquota_iva":     {"type": "number"},
            "importo_iva":      {"type": "number"},
            "totale":           {"type": "number"},
            "iban":             {"type": "string"}
          },
          "required": ["numero_documento","data_emissione","fornitore","imponibile","totale"]
        }
      }
    },
    "messages": [
      {"role":"system","content":"Estrai i campi dalla fattura. Importi come numeri, senza apostrofi."},
      {"role":"user","content":"FATTURA N. 2026-0417\nStudio Bernasconi SA, Via Nassa 12, 6900 Lugano\nData: 14 settembre 2026 — Scadenza: 14 ottobre 2026\nImponibile CHF 4'\''650.00\nIVA 8.1% CHF 376.65\nTOTALE CHF 5'\''026.65\nIBAN CH93 0076 2011 6238 5295 7"}
    ]
  }'

Cosa torna:

{
  "numero_documento": "2026-0417",
  "data_emissione": "14 settembre 2026",
  "data_scadenza": "14 ottobre 2026",
  "fornitore": "Studio Bernasconi SA",
  "imponibile": 4650.0,
  "aliquota_iva": 8.1,
  "importo_iva": 376.65,
  "totale": 5026.65,
  "iban": "CH93 0076 2011 6238 5295 7"
}

Misurato — tre giri, identici:

Campi verificati uno per uno contro il documento: numero, imponibile, importo IVA, totale e aliquota, tutti corretti in tutti e tre i giri.

Quello che non vi garantiamo, e va detto. Lo schema vincola la forma, non la verità: totale c'è sempre e sarà un numero, che sia il totale lo dice il vostro controllo. Sommate le righe e confrontate. E su una fattura svizzera con la sezione di pagamento, leggete prima il codice QR: IBAN, riferimento, importo e creditore escono in modo deterministico, senza modello. Usate il modello per quello che il codice non contiene.

2. Interrogare i vostri documenti, con la fonte#

# 1. l'archivio
curl $SIATI_BASE_URL/rag/kb -H "Authorization: Bearer $SIATI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Contratti clienti","embedding_model":"bge-m3"}'

# 2. il documento
curl $SIATI_BASE_URL/rag/kb/$KB_ID/documents \
  -H "Authorization: Bearer $SIATI_API_KEY" \
  -F "file=@contratto-mandato.pdf"

# 3. la domanda
curl $SIATI_BASE_URL/rag/kb/$KB_ID/chat \
  -H "Authorization: Bearer $SIATI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"Con quanto preavviso si può disdire, e in che forma?","model":"gemma-4-26b","top_k":4}'

Cosa torna — su un contratto di mandato di cinque articoli:

Ciascuna parte può disdire il contratto con un preavviso di sei mesi per la fine di un anno civile [contratto-mandato.md: parte 0]. La disdetta deve essere comunicata per iscritto mediante raccomandata [contratto-mandato.md: parte 0].

La citazione non è un ornamento: è il punto. Una risposta senza fonte, su un contratto, non è utilizzabile da chi deve rispondere al cliente.

Misurato — tre domande diverse sullo stesso contratto:

Le tre domande — preavviso di disdetta, termine per l'adeguamento dell'onorario, importo annuo e rateizzazione — hanno avuto tutte la risposta giusta con l'articolo citato.

⚠️ Al 22 settembre 2026 il caricamento dei documenti non è in servizio. L'archivio a oggetti che riceve i file ha un guasto dal 12 settembre. I numeri qui sopra misurano la catena vera — lettura, divisione, vettori, ricerca, riordino, risposta — con il documento messo a disposizione per un'altra via. Il passo 2 tornerà a funzionare con la riparazione, e questa nota sparirà da qui con la data. Se il vostro caso è l'estrazione di campi (esempio 1) non vi riguarda.

3. Trascrivere una riunione#

curl $SIATI_BASE_URL/audio/transcriptions \
  -H "Authorization: Bearer $SIATI_API_KEY" \
  -F file=@verbale.wav \
  -F model=whisper-1 \
  -F response_format=verbose_json \
  -F "timestamp_granularities[]=word"

Misurato su 22,2 secondi di verbale in italiano:

Una cosa utile che non ci aspettavamo di dover documentare: i numeri pronunciati a voce escono in cifre.

«…un utile di 47.000 franchi. Secondo punto, la fattura numero 2026-0417 dello studio Bernasconi, da 5.026 franchi e 65, va registrata entro il 14 ottobre.»

Dettato come «quarantasettemila», «cinquemilaventisei franchi e sessantacinque», «quattordici ottobre». Su un verbale è esattamente quello che serve, e vuol dire che il testo si può passare direttamente all'esempio 1 per estrarne i campi.

I tempi per parola servono a chi deve evidenziare il punto esatto dell'audio, tagliare una registrazione o mostrare dove il riconoscimento è stato incerto — la probabilità è per parola:

{"start": 21.44, "end": 22.02, "word": " ottobre.", "probability": 0.9997}

Come sono stati ottenuti questi numeri#

Tre chiamate per esempio, dall'esterno, attraverso il bilanciatore, con una chiave normale e il livello medium. La latenza è il tempo totale della richiesta HTTP, non il tempo del solo modello: comprende rete, autenticazione, contabilizzazione e risposta. Il costo è calcolato con la formula di fatturazione vera, non con quella pubblicata nella pagina dei prezzi — le due non coincidono, e stiamo sistemando la pagina.

I numeri cambiano con la lunghezza del vostro documento, con il livello della chiave e con il carico. Rifate le misure sul vostro caso: è il motivo per cui qui c'è il codice e non solo la tabella.