Chat completions
POST /v1/chat/completions follows the OpenAI format. Below are the Beatrice specifics; the full schema is in the reference.
Parameters
| Parameter | Notes |
|---|---|
model, messages | Required. Images, audio and video only inside the message as data: URLs (base64), never as links: a link gets a 400 |
max_tokens or max_completion_tokens | Output, reasoning included. Default 8,192 plus the reasoning of the level (2,048 with low, 8,192 with medium, 16,384 with high), maximum 49,152 |
stream, stream_options.include_usage | SSE streaming; with include_usage a last chunk carries the tokens |
temperature, top_p, seed, stop | As in OpenAI |
presence_penalty, frequency_penalty | As in OpenAI |
tools, tool_choice, parallel_tool_calls | Function calling, more than one at a time too |
response_format | For example JSON |
logprobs, top_logprobs | Forwarded to the model; top_logprobs from 0 to 20 |
reasoning_effort | How long the model reasons: none, low (default), medium, high. See Models |
reasoning_budget_tokens | Optional: at most this many reasoning tokens, below the level’s cap (never above it); 0 means no reasoning. Useful to an agent that spreads one task over many requests |
n | Only 1 |
Other fields are ignored without an error, so clients that send their own options keep working. An optional field set to null counts as not set.
The response
choices[0].message.content: the answer.choices[0].message.reasoning_content: the model’s reasoning, when present.choices[0].finish_reason:stop,length(out of output room, or stopped because the answer was repeating itself: see below),tool_calls, orcontent_filterwhen the request touches a red line.usage:prompt_tokens,completion_tokens(reasoning included) andprompt_tokens_details.cached_tokens(input read from the cache).
Answers that repeat themselves. If the model starts repeating the same text (in the answer, in the reasoning or in a tool’s arguments), the API stops the generation: the answer ends with finish_reason: "length" plus stop_reason: "repetition", and usage is an estimate. It usually happens after 8–32 KB of repeated text. A long but varied answer, even one with many similar lines such as a CSV, is not stopped.
Calls written as text. If the request offers tools and the model writes a call as text instead of making it (as <tool_call>…</tool_call> or <function=name>…</function>), the API turns it into a real call in tool_calls, with finish_reason: "tool_calls", for the offered tools only. Only a call at the start of a line that ends the answer counts: a call quoted inside a sentence, or followed by more text, stays text. tool_choice: "none" turns this off, a forced function limits it to that function, and with parallel_tool_calls: false you get at most one call. The text before the call stays in the answer. When streaming, text that may be the start of a call arrives as soon as it is clear that it is not.
Streaming
With "stream": true the answer arrives as server-sent events, in the OpenAI format, ending with data: [DONE].
Without streaming the whole answer arrives at the end. It can take up to 10 minutes, which is also the default wait of the OpenAI SDKs. For longer reasoning, for example with a high reasoning_effort and a large max_tokens, use streaming: it has no such limit and shows the answer as it arrives.
Reasoning comes in delta.reasoning_content, the answer in delta.content.
stream = client.chat.completions.create(
model="beatrice-flash",
messages=[{"role": "user", "content": "Explain recursion."}],
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) If the client closes the connection, generation stops at once on our side too.
Queues and timing
Everyone’s requests share the same capacity: when it is full, your request waits in a queue before starting, for up to 3 minutes.
If the queue is full or the wait exceeds the limit we answer 503 server_overloaded with Retry-After. The OpenAI SDKs retry by themselves.
Every response carries an x-request-id header: include it when you contact support.