IntelligenceBox

Chat

Manda un messaggio e ricevi la risposta dell’AI in streaming. È l’endpoint centrale dell’API di IntelligenceBox: ogni interazione con l’AI — una domanda semplice, una richiesta basata sui documenti o una conversazione con un assistente specializzato — passa da qui. La risposta arriva come stream Server-Sent Events, così la tua applicazione può mostrare i token in tempo reale mentre vengono generati.

Endpoint

Shell
POST /api/ai/chat

Parametri della richiesta

ParametroTipoObbligatorioDescrizione
idstringSìID univoco della chat. Riusalo per proseguire la conversazione
messagesarraySìArray di oggetti messaggio
boxAddressstringSìL’URL del tuo server
assistantIdstringNoID dell’assistente, da Assistenti
vectorarrayNoID delle cartelle, da Cartelle

Oggetto messaggio

JSON
{
  "role": "user",
  "content": "Your message here"
}

Ruoli: user, assistant, system

Chat semplice

Nessun assistente, nessuna cartella — solo una chiacchierata con l’AI.

Shell
curl -N -X POST BOX_URL/api/ai/chat \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "chat-001",
    "messages": [
      {"role": "user", "content": "What is machine learning?"}
    ],
    "boxAddress": "BOX_URL"
  }'

Chat con un assistente

Usa il carattere e le istruzioni di un assistente specifico.

Shell
curl -N -X POST BOX_URL/api/ai/chat \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "chat-002",
    "messages": [
      {"role": "user", "content": "Help me with my research"}
    ],
    "boxAddress": "BOX_URL",
    "assistantId": "YOUR_ASSISTANT_ID"
  }'

Chat con una cartella (RAG)

Cerca nei tuoi documenti e usali come contesto.

Shell
curl -N -X POST BOX_URL/api/ai/chat \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "chat-003",
    "messages": [
      {"role": "user", "content": "What do my documents say about pricing?"}
    ],
    "boxAddress": "BOX_URL",
    "vector": ["YOUR_FOLDER_ID"]
  }'

Più cartelle

JSON
"vector": ["folder-1", "folder-2", "folder-3"]

Chat con assistente + cartella

Combina le due cose: il carattere dell’assistente e la ricerca su più cartelle.

Shell
curl -N -X POST BOX_URL/api/ai/chat \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "chat-004",
    "messages": [
      {"role": "user", "content": "Summarize the key points from my documents"}
    ],
    "boxAddress": "BOX_URL",
    "assistantId": "YOUR_ASSISTANT_ID",
    "vector": ["FOLDER_ID_1", "FOLDER_ID_2"]
  }'

Risposta

La risposta è uno stream Server-Sent Events (SSE):

Shell
data: {"type":"text-delta","textDelta":"Hello"}
data: {"type":"text-delta","textDelta":"! I"}
data: {"type":"text-delta","textDelta":" can help"}
data: {"type":"finish","finishReason":"stop"}

Vedi Leggere la risposta per gestirlo nel codice.

Errori

CodiceSignificato
401API key mancante o non valida
404Assistente o cartella non trovati
500Errore del server
JSON
{
  "error": "Unauthorized - Invalid API key"
}

Consigli per usarlo bene

  • Riusa gli ID chat per le conversazioni: inviare lo stesso id con un array messages aggiornato prosegue la conversazione. Includi i messaggi precedenti perché l’AI mantenga il contesto da un turno all’altro.
  • Sii specifico nei prompt: prompt chiari e dettagliati danno risultati migliori. Invece di «Parlami delle vendite», prova con «Riassumi l’andamento delle vendite del Q4 dai report che ho caricato».
  • Usa il flag -N con curl: il flag -N disattiva il buffering dell’output ed è indispensabile per vedere i token man mano che arrivano invece di aspettare l’intera risposta.

Endpoint compatibile con OpenAI

Il box espone anche il formato OpenAI, così qualunque client o SDK compatibile con OpenAI può parlarci senza modifiche. Punta la base URL del client su BOX_URL/api/v1 e usa la tua API key come chiave OpenAI.

Python
from openai import OpenAI

client = OpenAI(
    base_url="BOX_URL/api/v1",
    api_key="YOUR_API_KEY",
)

stream = client.chat.completions.create(
    model="default",            # the box picks the model; see the note below
    messages=[{"role": "user", "content": "Summarise this quarter's risks."}],
    stream=True,
)

for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

Questo è il modello nudo, non il box completo

/api/v1/chat/completions è un passaggio diretto al modello locale: niente recupero dai documenti, niente assistenti, niente strumenti, niente citazioni, e nulla viene salvato nella cronologia delle conversazioni. Anche il campo model viene ignorato — il box serve sempre il modello locale che ha configurato, e GET /api/v1/models dice qual è. Per risposte basate sui documenti e con le citazioni, usa POST /api/ai/chat qui sopra.

Shell
curl BOX_URL/api/v1/models \
  -H "x-api-key: YOUR_API_KEY"

# {"object":"list","data":[{"id":"Qwen/Qwen3-…","object":"model","owned_by":"intelligencebox"}]}

Endpoint collegati

  • Leggere la risposta — impara a consumare e interpretare lo stream SSE nei vari linguaggi
  • Interrompere lo stream — annulla uno stream attivo se la risposta tarda troppo o non serve più
  • Assistenti — trova gli ID assistente da usare nel parametro assistantId
  • Cartelle — trova gli ID cartella da usare nel parametro vector per il RAG
Chat | IntelligenceBox