Skip to main content
POST

Streaming responses

With stream: true, the response is a sequence of server-sent events instead of one JSON object. Each event is a data: line holding a chat.completion.chunk. Read the generated text from choices[0].delta.content on each chunk, not from message, and concatenate the pieces in order. The final chunk for each choice carries a finish_reason. With stream_options.include_usage, one more chunk with empty choices reports usage for the whole request. A completed stream ends with data: [DONE].

Errors during streaming

The HTTP status is sent before generation starts, so a failure after that cannot change it. Instead, an event whose data is an error object, in the same shape as an error response body, reports the failure. The request may be retried. A stream that ends without data: [DONE], with or without an error event, did not complete: treat the text received as partial. Lines that begin with :, such as : keepalive, are comments that keep an idle connection open; ignore them.

Authorizations

Authorization
string
header
required

A Reflection API key, sent in the Authorization header as Bearer <API key>. Create a key for your project from the Reflection platform.

Headers

Reflection-Missing-Reasoning-Strategy
enum<string>
default:default

How assistant messages without reasoning_content are handled. default applies the model's own rule: Beam-1.0-501B-A23B refuses them. auto accepts them and lets the API choose how to make up for the missing reasoning when needed, which can lower the quality of the response.

Available options:
default,
auto

Body

application/json

Parameters not listed here are not supported: a request that includes one is refused.

model
string
required

ID of the model to use. Use List models to see the models available to you.

Minimum string length: 1
messages
object[]
required

A list of messages comprising the conversation so far.

Minimum array length: 1
stream
boolean | null
default:false

Whether to stream the model response data to the client as it is generated using server-sent events. See the streaming guide for how to handle the streamed events.

stream_options
object | null

Options for streaming response. Only set this when you set stream: true.

temperature
number | null

The sampling temperature, from 0 to 2. Higher values such as 0.8 make the output more varied; lower values such as 0.2 make it more focused and consistent. Adjust this or top_p, not both. When omitted or null, the model's default_parameters.temperature from the models endpoints applies, if it lists one.

Required range: 0 <= x <= 2
top_p
number | null

The nucleus sampling threshold, from 0 to 1. The model samples only from the most likely tokens whose probabilities add up to top_p, so 0.1 limits it to the top 10% of probability mass. Adjust this or temperature, not both. When omitted or null, the model's default_parameters.top_p from the models endpoints applies, if it lists one.

Required range: 0 <= x <= 1
max_tokens
integer | null
deprecated

The maximum number of tokens that can be generated in the chat completion, including reasoning tokens. Deprecated in favor of max_completion_tokens. The two cannot be set together. If both are omitted or null, the model's default_parameters.max_tokens applies, unreduced for the prompt. Your plan's per-request output limit applies if lower. At most 8,192 when logprobs is true.

Required range: x >= 1
max_completion_tokens
integer | null

Maximum generated tokens, including visible output and reasoning tokens. The prompt plus this value should fit within context_length. Cannot be set together with max_tokens. If both are omitted or null, the model's default_parameters.max_tokens applies, unreduced for the prompt. Your plan's per-request output limit applies if lower. At most 8,192 when logprobs is true.

Required range: x >= 1
stop
No effect

Sequences at which to stop generating further tokens: a non-empty string, or an array of 1 to 4 non-empty strings. Accepted but has no effect: generation does not stop at these sequences.

Minimum string length: 1
seed
integer<int64> | null
No effect

A seed for sampling, meant to make repeated requests with the same seed and parameters return the same result. Accepted but has no effect: sampling is not seeded, so results can differ.

reasoning_effort
string | null

Constrains effort on reasoning: a level name of 1 to 64 characters, such as low, medium, high, xhigh, or max. A model that lists reasoning.supported_efforts accepts only those values. When omitted or null, the default that retrieving the model reports in reasoning.default_effort applies; if it reports none, the model chooses its own effort. See the reasoning guide.

Required string length: 1 - 64
tools
object[] | null

A list of tools the model may call, each a function tool with a name, an optional description and JSON Schema parameters. A call the model makes is returned in message.tool_calls with finish_reason: tool_calls.

Maximum array length: 128
tool_choice

Controls which (if any) tool is called by the model: none, auto, required, or an object naming one function the model must call. Allowed only when tools is supplied.

Available options:
none,
auto,
required
parallel_tool_calls
boolean | null

Whether to enable parallel function calling during tool use. Allowed only when tools is supplied.

n
enum<integer> | null
Only 1

How many chat completion choices to generate for each input message. Only 1 is supported.

Available options:
1
logprobs
boolean | null
default:false

Whether to return, in choices[].logprobs, the log probability of each output token in content. When true, the output budget, reasoning tokens included, is at most 8,192 tokens, and a larger limit is rejected. A model that does not list max_top_logprobs on the models endpoints accepts only false or null.

top_logprobs
integer | null

The maximum number of most likely tokens, from 0 to 20, to return at each token position, each with its log probability. When omitted or null, none are returned. A model accepts at most the max_top_logprobs it lists. A non-null value is allowed only when logprobs is true.

Required range: 0 <= x <= 20
frequency_penalty
number | null

How much to penalize a token for each time it has already appeared, from -2 to 2. Positive values reduce verbatim repetition; negative values encourage it. When omitted or null, the model's default_parameters.frequency_penalty from the models endpoints applies, if it lists one.

Required range: -2 <= x <= 2
presence_penalty
number | null

How much to penalize a token that has already appeared at least once, from -2 to 2. Positive values steer the model toward new words and topics; negative values keep it on them. When omitted or null, the model's default_parameters.presence_penalty from the models endpoints applies, if it lists one.

Required range: -2 <= x <= 2
logit_bias
object | null
Only an empty object

Modifies the likelihood of specified tokens appearing in the completion. Not supported: only an empty object is accepted.

response_format
object

An object specifying the format that the model must output, selected by its type: plain text, a valid JSON object (json_object), or JSON matching the schema in json_schema (json_schema).

service_tier
enum<string> | null
Only auto or default

Specifies the processing type used for serving the request. Only auto and default are supported. Both select standard processing.

Available options:
auto,
default
store
enum<boolean> | null
Only false

Whether to store the output of this chat completion request so it can be retrieved later. Only false is supported.

Available options:
false
modalities
enum<string>[] | null
Only ["text"]

Output types that you would like the model to generate. Only ["text"] is supported.

Required array length: 1 element
Available options:
text
verbosity
enum<string> | null
Only medium

Constrains the verbosity of the model's response. Only medium is supported.

Available options:
medium
metadata
object | null
No effect

Up to 16 key-value pairs to attach to the request, each value a string of at most 512 characters. Accepted but has no effect: the pairs are not stored or returned.

safety_identifier
string | null

A stable identifier for the end user of your application, of at most 128 characters. Requests are attributed to it when detecting and handling misuse. The model never sees it. Send a hash of a username or email address rather than the value itself.

Maximum string length: 128
prompt_cache_key
string | null
No effect

A key shared by requests with a common prompt prefix, to improve cache hit rates. Accepted but has no effect: requests are not routed or cached by it. It is recorded with the request for internal usage analytics.

prompt_cache_options
object | null
No effect

Options for prompt caching. Accepted but has no effect: caching does not change with them.

prompt_cache_retention
enum<string> | null
deprecated
No effect

The retention policy for the prompt cache. Deprecated in favor of prompt_cache_options. Accepted but has no effect: cache retention does not change.

Available options:
in_memory,
24h
user
string | null
deprecated
No effect

A stable identifier for your end user. Deprecated in favor of safety_identifier and prompt_cache_key. Accepted but has no effect: responses do not depend on it. It is recorded with the request for internal usage analytics.

Response

A chat completion, or a stream of chat completion chunks when stream is true.

Represents a chat completion response returned by the model, based on the provided input.

id
string
required

A unique identifier for the chat completion.

object
enum<string>
required

The object type, which is always chat.completion.

Available options:
chat.completion
created
integer<int64>
required

The Unix timestamp (in seconds) of when the chat completion was created.

model
string
required

The model used for the chat completion.

choices
object[]
required

A list of chat completion choices.

usage
object
required

Usage statistics for the completion request.