BEATRICE Docs
Sezioni

Chat completions

POST /v1/chat/completions segue il formato OpenAI. Qui sotto le cose da sapere specifiche di Beatrice; lo schema completo è nel riferimento.

Parametri

ParametroNote
model, messagesObbligatori. Immagini, audio e video solo dentro il messaggio come data: URL (base64), mai come link: un link riceve 400
max_tokens o max_completion_tokensOutput, ragionamento compreso. Predefinito 8.192 più il ragionamento del livello (2.048 con low, 8.192 con medium, 16.384 con high), massimo 49.152
stream, stream_options.include_usageStreaming SSE; con include_usage arriva un ultimo chunk con i token
temperature, top_p, seed, stopCome in OpenAI
presence_penalty, frequency_penaltyCome in OpenAI
tools, tool_choice, parallel_tool_callsChiamata di funzioni, anche più di una per volta
response_formatPer esempio JSON
logprobs, top_logprobsInoltrati al modello; top_logprobs da 0 a 20
reasoning_effortQuanto ragiona il modello: none, low (predefinito), medium, high. Vedi Modelli
reasoning_budget_tokensFacoltativo: al massimo tanti token di ragionamento, sotto il tetto del livello (mai sopra); 0 vuol dire senza ragionamento. Utile a un agente che divide un compito in molte richieste
nSolo 1

Gli altri campi vengono ignorati senza errore, così i client che mandano opzioni proprie continuano a funzionare. Un campo facoltativo uguale a null vale come non impostato.

La risposta

  • choices[0].message.content: la risposta.
  • choices[0].message.reasoning_content: il ragionamento del modello, se presente.
  • choices[0].finish_reason: stop, length (finito lo spazio di output, oppure risposta fermata perché si ripeteva: vedi sotto), tool_calls, oppure content_filter quando la richiesta tocca una linea rossa.
  • usage: prompt_tokens, completion_tokens (ragionamento compreso) e prompt_tokens_details.cached_tokens (input letto dalla cache).

Risposte che si ripetono. Se il modello comincia a ripetere lo stesso testo (nella risposta, nel ragionamento o negli argomenti di uno strumento), l’API ferma la generazione: la risposta finisce con finish_reason: "length" e in più stop_reason: "repetition", e usage è una stima. Succede di solito dopo 8–32 KB di testo ripetuto. Una risposta lunga ma varia, anche con molte righe simili come un CSV, non si ferma.

Chiamate scritte come testo. Se la richiesta offre tools e il modello scrive una chiamata come testo invece di farla (nel formato <tool_call>…</tool_call> o <function=nome>…</function>), l’API la trasforma in una chiamata vera in tool_calls, con finish_reason: "tool_calls", solo per gli strumenti offerti. Conta solo una chiamata a inizio riga che chiude la risposta: una chiamata citata in una frase, o seguita da altro testo, resta testo. Con tool_choice: "none" il recupero è spento, con una funzione imposta vale solo per quella, e con parallel_tool_calls: false arriva al massimo una chiamata. Il testo prima della chiamata resta nella risposta. In streaming il testo che potrebbe essere l’inizio di una chiamata arriva appena è chiaro che non lo è.

Streaming

Con "stream": true la risposta arriva come server-sent events, nel formato OpenAI, e termina con data: [DONE].

Senza streaming la risposta arriva tutta insieme, alla fine. Può durare fino a 10 minuti, che è anche il tempo di attesa predefinito degli SDK di OpenAI. Per ragionamenti più lunghi, per esempio con reasoning_effort alto e un max_tokens grande, usa lo streaming: non ha questo limite e mostra la risposta mentre arriva. Il ragionamento arriva in delta.reasoning_content, la risposta in delta.content.

stream = client.chat.completions.create(
    model="beatrice-flash",
    messages=[{"role": "user", "content": "Spiegami la ricorsione."}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="")
    elif chunk.usage:
        print("\n", chunk.usage)

Se il client chiude la connessione, la generazione si ferma subito anche sul nostro lato.

Code e tempi

Le richieste di tutti condividono la stessa capacità: quando è piena, la tua richiesta aspetta in coda prima di partire, fino a 3 minuti. Se la coda è piena o l’attesa supera il limite rispondiamo 503 server_overloaded con Retry-After. Gli SDK di OpenAI riprovano da soli. Ogni risposta porta un’intestazione x-request-id: indicala quando scrivi all’assistenza.

l'amor che move il sole e l'altre stelle