Chat Completions

Authorizations

Authorization

string

header

required

API key for authentication. Obtain your key from the Cerebras Cloud console and pass it as Authorization: Bearer YOUR_API_KEY.

Headers

Content-Type

enum<string>

default:application/json

The media type of the request body.

Available options:

application/json,

application/vnd.msgpack

Content-Encoding

enum<string>

The compression encoding applied to the request body. When set, the request body must be gzip-compressed. Can be combined with any supported Content-Type.

Available options:

gzip

queue_threshold

string

Controls the queue time threshold for requests using the flex or auto service tiers. Requests are preemptively rejected if the rolling average queue time exceeds this threshold. Valid range: 50–20000 (milliseconds). Private Preview.

Body

application/json

messages

Chat message · object[]

required

A list of messages comprising the conversation so far. Depending on the model you use, different message types (modalities) are supported, like text and images.

Hide child attributes

messages.role

enum<string>

required

The role of the message author.

Available options:

system,

user,

assistant,

tool,

developer

messages.content

The message content. This is required for system, user, developer, and tool messages. Assistant messages may omit content when they include tool calls.

messages.name

string

An optional name for the message author.

messages.reasoning

string | null

Reasoning from an assistant response supplied back in conversation history. Supported behavior varies by model.

messages.tool_calls

object[]

Tool calls generated in an assistant message.

Hide child attributes

messages.tool_calls.id

string

required

messages.tool_calls.type

enum<string>

required

Available options:

function

messages.tool_calls.function

object

required

Hide child attributes

messages.tool_calls.function.name

string

required

messages.tool_calls.function.arguments

string

required

JSON-encoded arguments for the function call.

messages.tool_call_id

string

The tool call this message responds to. Required when role is tool.

model

string

required

The ID of the model to use for generating a response.

frequency_penalty

number | null

default:0

A number between -2.0 and 2.0. Positive values reduce the likelihood of the model repeating tokens by applying a penalty proportional to how frequently each token has already appeared in the generated output.

Required range: -2 <= x <= 2

logit_bias

object | null

Modify the likelihood of specified tokens appearing in the completion. Accepts a JSON object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from -100 to 100. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token.

Hide child attributes

logit_bias.{key}

number

logprobs

boolean

default:false

Whether to return log probabilities of the output tokens.

max_completion_tokens

integer | null

The maximum number of tokens that can be generated in the completion, including reasoning tokens. The total length of input tokens and generated tokens is limited by the model's context length.

max_tokens

integer | null

An alias for max_completion_tokens. Do not send both parameters in the same request.

min_completion_tokens

integer | null

The minimum number of tokens to generate. If omitted or set to 0, the model decides when to stop. Setting this value to -1 requests generation up to the maximum sequence length.

min_tokens

integer | null

An alias for min_completion_tokens. Do not send both parameters in the same request.

enum<integer> | null

default:1

The number of completion choices to generate. Cerebras currently supports only 1.

Available options:

1

parallel_tool_calls

boolean | null

default:true

Whether to enable parallel function calling during tool use. When enabled (default), the model can request multiple tool calls simultaneously in a single response. When disabled, only one tool call is made at a time.

prediction

object | null

Configuration for a Predicted Output, which can greatly speed up response times when large parts of the model response are known in advance. Most common when regenerating a file with mostly minor changes. Available by request on dedicated endpoints. Predicted Outputs are not available for qwen-3.8-27b or kimi-k2.7-code on shared or trial endpoints.

Hide child attributes

prediction.type

enum<string>

required

The type of predicted content. Always content.

Available options:

content

prediction.content

required

The content that should be matched when generating a model response.

presence_penalty

number | null

default:0

A number between -2.0 and 2.0. Positive values reduce the likelihood of the model repeating tokens that have already appeared in the output, encouraging the model to introduce new topics.

Required range: -2 <= x <= 2

prompt_cache_key

string | null

An opaque identifier that groups related requests so they reuse the same prompt cache. Requests sharing the same prompt_cache_key are routed together, which increases cache hits and reduces time to first token.

Set it to a stable identifier such as a conversation, session, or workflow ID. Prompt caching works automatically when this field is omitted. This field is an optional routing hint and is available for all models.

Maximum string length: 1024

reasoning_effort

enum<string> | null

Controls the amount of reasoning the model performs. Supported values vary by model:

gpt-oss-120b: low, medium (default), high
gemma-4-31b: none (default), low, medium, high (all enable reasoning equivalently). raw and hidden reasoning formats are not supported.
qwen-3.8-27b: none, low, medium, high (default). high maps to Qwen's native xhigh mode. none disables reasoning. Effort values select reasoning modes, not exact token budgets.
kimi-k2.7-code: Accepted for compatibility but ignored. Reasoning is always enabled, including when this field is set to none.

Available options:

low,

medium,

high,

none

reasoning_format

enum<string> | null

Controls how reasoning is returned. Support varies by model. See Reasoning for the complete matrix.

qwen-3.8-27b returns reasoning separately in message.reasoning and delta.reasoning; hidden is not supported.
kimi-k2.7-code defaults to parsed, supports raw, and does not support hidden. raw cannot be combined with json_object or json_schema response formats.

Available options:

parsed,

raw,

hidden,

none

clear_thinking

boolean | null

default:false

Controls whether historical assistant reasoning supplied in the conversation is removed before prompting the model.

Supported by qwen-3.8-27b. When false or omitted, historical reasoning is preserved. When true, it is removed.

Not implemented for kimi-k2.7-code. Do not send.

response_format

Text · object

An object that controls the format of the model response.

Setting { "type": "json_schema", ... } enables Structured Outputs, which enforces schema compliance. See Structured Outputs for details.

Setting { "type": "json_object" } enables legacy JSON mode, which ensures the model returns valid JSON but does not enforce a specific schema. To use json_object, include a system or user message specifying the desired format. json_object is not compatible with streaming, so stream must be set to false.

Text
JSON Schema
JSON Object

Hide child attributes

response_format.type

enum<string>

required

The type of response format being defined. Always text.

Available options:

text

seed

integer | null

If specified, the system will make a best effort to sample deterministically so repeated requests with the same seed and parameters return the same result. Determinism is not guaranteed.

service_tier

enum<string> | null

default:default

Controls request prioritization. Service tiers are not available on shared endpoints, including qwen-3.8-27b, or on kimi-k2.7-code customer-trial endpoints.

Note: This feature is in Private Preview. For access or more information, contact us or reach out to your account representative.

Available options:

priority - Highest priority processing (Only available for dedicated endpoints, not shared endpoints.)
default - Standard priority processing
auto - Automatically uses the highest available service tier
flex - Lowest priority processing

See Service Tiers for more information.

Available options:

priority,

default,

auto,

flex

stop

Up to four sequences that cause the API to stop generating further tokens. The returned text does not contain the stop sequence.

stream

boolean | null

Streams partial message deltas when set to true.

temperature

number | null

Sampling temperature between 0 and 2. Higher values, such as 0.8, make output more random; lower values, such as 0.2, make it more focused and deterministic. We recommend changing either this value or top_p, but not both.

Required range: 0 <= x <= 2

tool_choice

Controls which (if any) tool is called by the model.

none: No tool is called.
auto: The model chooses whether to call a tool. This is the default when tools are present.
required: Forces a tool call.

A specific tool can be forced by passing an object specifying the function name.

Available options:

none,

auto,

required

tools

object[] | null

A list of tools the model may call. Use this to provide a list of functions the model may generate JSON inputs for.

Currently, only functions are supported. Specifying tools consumes prompt tokens; too many may degrade performance or hit context length limits.

Hide child attributes

tools.type

enum<string>

required

The type of the tool. Currently only function is supported.

Available options:

function

tools.function

object

required

Hide child attributes

tools.function.name

string

required

The name of the function to call. Supported characters: a-z, A-Z, 0-9, _, -. Maximum length: 64.

tools.function.description

string

A description of what the function does, used by the model to choose when and how to call the function.

tools.function.parameters

object

The parameters the function accepts, described as a JSON Schema object. Omitting parameters defines a function with an empty parameter list.

tools.function.strict

boolean

default:false

When true, constrained decoding guarantees that tool arguments conform to the supported subset of the JSON Schema in parameters. See Tool Calling and Structured Outputs for requirements and model-specific limitations.

top_logprobs

integer | null

An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability. If using this parameter, logprobs must also be set to true.

Required range: 0 <= x <= 20

top_p

number | null

Nucleus sampling parameter between 0 and 1. The model considers only tokens comprising the top top_p probability mass. For example, 0.1 means only tokens comprising the top 10% probability mass are considered. We recommend changing either this value or temperature, but not both.

Required range: 0 <= x <= 1

user

string | null

A unique identifier representing your end-user, which can help monitor and detect abuse.

Response

200 - application/json

Successful response

string

A unique identifier for the chat completion.

choices

object[]

A list containing the chat completion choice. Cerebras currently supports n: 1 only.

Hide child attributes

choices.finish_reason

enum<string>

The reason the model stopped generating tokens.

Available options:

stop,

length,

content_filter,

tool_calls

choices.index

integer

The index of the choice in the list of choices.

choices.logprobs

object | null

Log probability information for the output tokens.

choices.reasoning_logprobs

object | null

Log probability information for the reasoning tokens, if provided by the model.

choices.message

object

A chat completion message generated by the model.

Hide child attributes

choices.message.content

string | null

The contents of the message.

choices.message.role

string

The role of the author of this message.

choices.message.reasoning

string

The model's reasoning content when using reasoning models.

choices.message.tool_calls

object[] | null

Tool calls the model requested in its response.

Hide child attributes

choices.message.tool_calls.id

string

The ID of the tool call.

choices.message.tool_calls.type

enum<string>

The type of tool call.

Available options:

function

choices.message.tool_calls.function

object

The function call details.

Hide child attributes

choices.message.tool_calls.function.name

string

The name of the function called.

choices.message.tool_calls.function.arguments

string

The JSON-encoded arguments supplied by the model.

created

integer

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

model

string

The model used for the chat completion.

object

enum<string>

The object type. Always chat.completion.

Available options:

chat.completion

system_fingerprint

string

A fingerprint for the model or backend used to generate the response.

service_tier

string | null

The service tier used for the request, or null if not specified.

service_tier_used

enum<string> | null

The service tier used for processing the request. Only present when service_tier is set to auto in the request.

Available options:

priority,

default,

flex

usage

object

Usage statistics for the completion request.

Hide child attributes

usage.prompt_tokens

integer

Number of tokens in the prompt.

usage.completion_tokens

integer

Number of tokens in the generated completion.

usage.total_tokens

integer

Total number of tokens used (prompt + completion).

usage.image_tokens

integer

Number of tokens used to represent image inputs. Present for requests to vision-capable models.

usage.prompt_tokens_details

object

Detailed breakdown of prompt token usage.

Hide child attributes

usage.prompt_tokens_details.cached_tokens

integer

Number of prompt tokens served from the cache, reused from a previous request.

usage.completion_tokens_details

object

Breakdown of completion tokens when using Predicted Outputs.

Hide child attributes

usage.completion_tokens_details.accepted_prediction_tokens

integer

Tokens in the prediction that appeared in the completion.

usage.completion_tokens_details.rejected_prediction_tokens

integer

Tokens in the prediction that did not appear in the completion. Counted in total completion tokens for billing, output, and context window limits.

usage.completion_tokens_details.reasoning_tokens

integer

Tokens spent on model reasoning, if applicable.

time_info

object

Performance timing information for the request.

Hide child attributes

time_info.queue_time

number

Time spent in queue waiting for processing (seconds).

time_info.prompt_time

number

Time spent processing prompt/input tokens (seconds).

time_info.completion_time

number

Time spent generating completion/output tokens (seconds).

time_info.total_time

number

Total time for the entire request from submission to completion (seconds).

time_info.created

number

Unix timestamp of when the time_info was recorded.

Introduction

Chat

Completions

Models

Batch

Files

Metrics

Management

Authorizations

Headers

Body

Response