Skip to main content
POST
Supported reasoning levels, defaults, and response formats vary by model. See Reasoning for model-specific tables, request examples, and conversation-history guidance. For image formats, limits, and model-specific support for images in user and tool messages, see Image Inputs. On enabled gemma-4-31b Dedicated deployments, set image_url.detail on each image to control its image token budget. Supported values are low, medium, high, auto (default), and original. Defaults and limits depend on the deployment. See Image token budgets for availability, mappings, and examples.

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.

model
string
required

The model or endpoint ID to use for generating a response. For Shared Inference, use a model ID from the model catalog. For Dedicated Inference, use the endpoint ID assigned to your organization.

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.

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.

n
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 with Shared Inference or for kimi-k2.7-code.

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

Selects a model-specific reasoning level. Effort levels don't reserve or guarantee an exact reasoning-token budget.

Supported values and defaults vary by model.

For qwen-3.8-27b, high selects the model's native xhigh mode. For gemma-4-31b, low, medium, and high enable reasoning equivalently.

The value none disables reasoning for qwen-3.8-27b and gemma-4-31b. For kimi-k2.7-code, all accepted values, including none, are ignored and reasoning stays enabled. The other listed models don't support none.

Reasoning tokens count toward max_completion_tokens and usage.completion_tokens. See Reasoning for model-specific examples.

Available options:
low,
medium,
high,
max,
none
reasoning_format
enum<string> | null

Selects how the API returns reasoning. Support varies by model.

Setting this field to none doesn't disable reasoning. Use reasoning_effort to disable reasoning on supported models.

  • qwen-3.8-27b returns reasoning separately, including when raw is selected. hidden isn't supported.
  • kimi-k2.7-code defaults to parsed and supports raw. hidden isn't supported. Do not combine raw with json_object or json_schema response formats.
  • kimi-k3 and kimi-k3.1-pro support parsed only. Do not send raw or hidden.
  • zai-glm-5.3-flash and gpt-oss-120b default to parsed and support raw and hidden.
  • gemma-4-31b doesn't support raw or hidden.

See Reasoning formats for the complete model comparison.

Available options:
parsed,
raw,
hidden,
none
clear_thinking
boolean | null
default:false

Controls whether historical assistant reasoning is removed from the conversation before prompting the model. Assistant final-answer content is retained.

Not supported for gemma-4-31b, kimi-k2.7-code, kimi-k3, or kimi-k3.1-pro. Do not send this field for those models.

See Multi-turn reasoning for an example that resends assistant reasoning.

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.

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. default uses the request's standard priority and quota. priority attempts the configured higher priority and can retry at the standard priority. auto starts with standard priority and quota, then can fall back to flex. flex uses the lowest configured priority and separate flex rate limits.

Service tiers are not available with Shared Inference on the Developer Tier.

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. Requires an endpoint with service-tier support enabled.
  • 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.

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

id
string

A unique identifier for the chat completion.

choices
object[]

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

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
enum<string> | null

The effective service tier used to process the request. An auto request can return auto or flex, and a priority request can return priority or auto. The field may be omitted or null when the request uses default processing.

Available options:
priority,
default,
auto,
flex
usage
object

Usage statistics for the completion request.

time_info
object

Performance timing information for the request.