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

Parametro	Note
`model`, `messages`	Obbligatori
`max_tokens` o `max_completion_tokens`	Output, ragionamento compreso. Predefinito 8.192, massimo 32.768
`stream`, `stream_options.include_usage`	Streaming SSE; con `include_usage` arriva un ultimo chunk con i token
`temperature`, `top_p`, `seed`, `stop`	Come in OpenAI
`presence_penalty`, `frequency_penalty`	Come in OpenAI
`tools`, `tool_choice`, `parallel_tool_calls`	Chiamata di funzioni, anche più di una per volta
`response_format`	Per esempio JSON
`logprobs`, `top_logprobs`, `reasoning_effort`	Inoltrati al modello
`n`	Solo `1`

Gli altri campi vengono ignorati senza errore, così i client che mandano opzioni proprie continuano a funzionare.

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), 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).

Streaming

Con "stream": true la risposta arriva come server-sent events, nel formato OpenAI, e termina con data: [DONE]. 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 per qualche secondo prima di partire. 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.