Introduction
Completions
Metrics
from cerebras.cloud.sdk import Cerebras
import os
client = Cerebras(api_key=os.environ.get("CEREBRAS_API_KEY"),)
chat_completion = client.chat.completions.create(
model="gpt-oss-120b",
messages=[
{"role": "user", "content": "Hello!",}
],
)
print(chat_completion)
{
"id": "chatcmpl-30b3c3d8-ca41-48e7-9ef0-27e322604a13",
"choices": [
{
"finish_reason": "stop",
"index": 0,
"message": {
"role": "assistant",
"content": "Hello! 👋 How can I help you today?",
"reasoning": "The user just says \"Hello!\" with no further context.\n\nWe need to respond politely, maybe ask how can assist.\n\nWe can also be friendly.\n\nNo constraints. We'll respond as chat.",
"tool_calls": null
},
"logprobs": null,
"reasoning_logprobs": null
}
],
"created": 1769729480,
"model": "gpt-oss-120b",
"object": "chat.completion",
"system_fingerprint": "fp_e7ab83753cbd28777b40",
"time_info": {
"completion_time": 0.04040406,
"prompt_time": 0.00383762,
"queue_time": 0.004628115,
"total_time": 0.05013155937194824,
"created": 1769729480.0787008
},
"usage": {
"completion_tokens": 59,
"completion_tokens_details": {
"accepted_prediction_tokens": 0,
"rejected_prediction_tokens": 0,
"reasoning_tokens": 0
},
"prompt_tokens": 69,
"prompt_tokens_details": {
"cached_tokens": 0
},
"total_tokens": 128
},
"service_tier": null
}
Chat Completions
POST
/
v1
/
chat
/
completions
from cerebras.cloud.sdk import Cerebras
import os
client = Cerebras(api_key=os.environ.get("CEREBRAS_API_KEY"),)
chat_completion = client.chat.completions.create(
model="gpt-oss-120b",
messages=[
{"role": "user", "content": "Hello!",}
],
)
print(chat_completion)
{
"id": "chatcmpl-30b3c3d8-ca41-48e7-9ef0-27e322604a13",
"choices": [
{
"finish_reason": "stop",
"index": 0,
"message": {
"role": "assistant",
"content": "Hello! 👋 How can I help you today?",
"reasoning": "The user just says \"Hello!\" with no further context.\n\nWe need to respond politely, maybe ask how can assist.\n\nWe can also be friendly.\n\nNo constraints. We'll respond as chat.",
"tool_calls": null
},
"logprobs": null,
"reasoning_logprobs": null
}
],
"created": 1769729480,
"model": "gpt-oss-120b",
"object": "chat.completion",
"system_fingerprint": "fp_e7ab83753cbd28777b40",
"time_info": {
"completion_time": 0.04040406,
"prompt_time": 0.00383762,
"queue_time": 0.004628115,
"total_time": 0.05013155937194824,
"created": 1769729480.0787008
},
"usage": {
"completion_tokens": 59,
"completion_tokens_details": {
"accepted_prediction_tokens": 0,
"rejected_prediction_tokens": 0,
"reasoning_tokens": 0
},
"prompt_tokens": 69,
"prompt_tokens_details": {
"cached_tokens": 0
},
"total_tokens": 128
},
"service_tier": null
}
Generate conversational responses using a structured message format with roles (system, user, assistant, developer, tool). Best for chatbots, assistants, and multi-turn conversations.
Parameter support can differ depending on the model used to generate the response, particularly for newer reasoning models. For details about parameters in reasoning models, refer to the Reasoning Guide.
Request
Headers
Controls the queue time threshold for requests using the Valid range:
flex or auto service tiers. Requests are preemptively rejected if the rolling average queue time exceeds this threshold.This feature is in Private Preview. For access or more information, contact us or reach out to your account representative.
50 - 20000 (milliseconds)Default: System default if not specifiedSee Service Tiers for more information.Body
A list of messages comprising the conversation so far.
Assistant message
Messages sent by the model in response to user messages.
Developer message
Developer-provided instructions that the model should follow, regardless of messages sent by the user. For gpt-oss-120b,
System message
Developer-provided instructions that the model should follow, regardless of messages sent by the user.
Tool message
Tool message containing the result of a tool call.
User message
Messages sent by an end user, containing prompts or additional context information.
Show possible types
Show possible types
Assistant message object
Messages sent by the model in response to user messages.Show properties
Show properties
The contents of the assistant message.
Show possible types
Show possible types
The role of the messages author, in this case
assistant.An optional name for the participant. Provides the model information to differentiate between participants of the same role.
The reasoning content from the model’s response. Include this when passing back assistant messages that contained reasoning.
The tool calls generated by the model, such as function calls.
Show properties
Show properties
The ID of the tool call.
The type of the tool. Currently, only
function is supported.Developer message object
Developer-provided instructions that the model should follow, regardless of messages sent by the user. For gpt-oss-120b, developer messages replace the previous system messages, but system is still accepted.The
developer role is currently only available for the gpt-oss-120b model.Show properties
Show properties
The contents of the developer message.
Show possible types
Show possible types
The role of the messages author, in this case
developer.An optional name for the participant. Provides the model information to differentiate between participants of the same role.
System message object
Developer-provided instructions that the model should follow, regardless of messages sent by the user.Show properties
Show properties
The contents of the system message.
Show possible types
Show possible types
The role of the messages author, in this case
system.An optional name for the participant. Provides the model information to differentiate between participants of the same role.
Tool message object
Tool message containing the result of a tool call.Show properties
Show properties
The contents of the tool message.
Show possible types
Show possible types
The role of the messages author, in this case
tool.Tool call that this message is responding to.
User message object
Messages sent by an end user, containing prompts or additional context information.Show properties
Show properties
The contents of the user message.
Text content
The text contents of the message.
Array of content parts
An array of content parts with a defined type. Supported options differ based on the model being used to generate the response. Can contain text inputs.
Show possible types
Show possible types
Text content string
The text contents of the message.Array of content parts array
An array of content parts with a defined type. Supported options differ based on the model being used to generate the response. Can contain text inputs.Show possible types
Show possible types
The role of the messages author, in this case
user.An optional name for the participant. Provides the model information to differentiate between participants of the same role.
Available options:
llama3.1-8bqwen-3-235b-a22b-instruct-2507(preview)gpt-oss-120bzai-glm-4.7(preview)
Controls whether thinking content from previous conversation turns is included in the prompt context.Note: Thinking content from the current (latest unfinished) turn is always included regardless of this setting.
false- Thinking from all previous turns is preserved in the conversation history. Recommended for agentic workflows where reasoning from past tool-calling turns may be relevant for future tool calls.true(default) - Thinking from earlier turns is excluded. Recommended for general chat conversations where reasoning from past turns is less relevant for performance.
null, the API defaults to clear_thinking: true.This parameter is supported only on the zai-glm-4.7 model. For additional information, see Preserved thinking in the Z.ai documentation.
Whether to return log probabilities of the output tokens or not.Default:
falseThe 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.
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, the model will only request one tool call at a time.Default:
trueConfiguration for a Predicted Output, which can greatly speed up response times when large parts of the model response are known in advance. This is most common when you are regenerating a file with mostly minor changes to the content.
Visit our page on Predicted Outputs for more information and examples.
Show possible types
Show possible types
Static Content
Static predicted output content, such as the content of a text or code file that is being regenerated.Show properties
Show properties
The content that should be matched when generating a model response. If continuous token sequences from the generated tokens match this content, the entire model response can be returned faster.
Text content
The content used for a given Predicted Output. Typically the text of a file you are regenerating with only minor changes.
Array of content parts
An array of content parts with a defined type. Supported options may differ based on the model that is used to generate the response. May contain text inputs.
Show possible types
Show possible types
Text content string
The content used for a given Predicted Output. Typically the text of a file you are regenerating with only minor changes. Array of content parts array
An array of content parts with a defined type. Supported options may differ based on the model that is used to generate the response. May contain text inputs.Show possible types
Show possible types
The type of the predicted content you wish to provide. This type is currently always
content.Controls the amount of reasoning the model performs. Supported values vary by model:gpt-oss-120b
"low"– Minimal reasoning, faster responses"medium"– Moderate reasoning (default)"high"– Extensive reasoning, more thorough analysis
"none"– Disables reasoning entirely
This parameter is only available for gpt-oss-120b and zai-glm-4.7 models.
An object that controls the format of the model response.Setting to
Text
Default response format. Generates plain text responses.
JSON schema
Generates structured JSON output that conforms to the specified schema. Use this format when you need the model to return structured JSON.
JSON object
A legacy method for generating JSON responses. Using
{ "type": "json_schema", "json_schema": { "name": "schema_name", "strict": true, "schema": {...} } } enforces schema compliance by ensuring that the model output conforms to your specified JSON schema. See Structured Outputs for more information.Setting { "type": "json_object" } enables the legacy JSON mode, ensuring that the model output is valid JSON. However, using json_schema is recommended for models that support it.Show properties
Show properties
Text object
Default response format. Generates plain text responses.Show properties
Show properties
The type of response format being defined. Always
text.JSON schema object
Generates structured JSON output that conforms to the specified schema. Use this format when you need the model to return structured JSON.Show properties
Show properties
Structured Outputs configuration options.
Show properties
Show properties
An optional name for your schema.
A description of the response format’s purpose, used by the model to determine how to generate its response in that format.
A valid JSON Schema object that defines the structure, types, and requirements for the response. Supports standard JSON Schema features including types (string, number, boolean, integer, object, array, enum, anyOf, null), nested structures, required fields, and additionalProperties (must be set to false).
When set to
true, enforces strict adherence to the schema. The model will only return fields defined in the schema and with the correct types. When false, behaves similar to JSON mode but uses the schema as a guide. Defaults to false.The type of response format being defined. Always
json_schema.JSON object object
A legacy method for generating JSON responses. Using json_schema is recommended for models that support it. To use json_object remember to also include a system or user message to specify the desired format.Show properties
Show properties
The type of response format being defined. Always
json_object.When using JSON object, you must explicitly instruct the model to generate JSON through a system or user message.
json_object is not compatible with streaming - stream must be set to false.If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same
seed and parameters should return the same result. Determinism is not guaranteed.Controls request prioritization.Available options:
This feature is in Private Preview. For access or more information, contact us or reach out to your account representative.
priority- Highest priority processing (Only available for dedicated endpoints, not shared endpoints.)default- Standard priority processingauto- Automatically uses the highest available service tierflex- Lowest priority processing
defaultSee Service Tiers for more information.Up to 4 sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence.
If set, partial message deltas will be sent.
What sampling temperature to use, between 0 and 1.5. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both.
Controls which (if any) tool is called by the model.
none means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools. Specifying a particular tool via {"type": "function", "function": {"name": "my_function"}} forces the model to call that tool.none is the default when no tools are present. auto is the default if tools are present.A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for.Specifying tools consumes prompt tokens in the context. If too many are given, the model may perform poorly or you may hit context length limitations
Show properties
Show properties
A description of what the function does, used by the model to choose when and how to call the function.
The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.
The parameters the functions accepts, described as a JSON Schema object. Omitting parameters defines a function with an empty parameter list.
The type of the tool. Currently, only
function is supported.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.
logprobs must be set to true if this parameter is used.An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So, 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both.
A unique identifier representing your end-user, which can help to monitor and detect abuse.
Response
A unique identifier for the chat completion.
A list of chat completion choices. Can be more than one if
n is greater than 1.Show choice properties
Show choice properties
The reason the model stopped generating tokens. Possible values:
stop, length, content_filter, tool_calls.The index of the choice in the list of choices.
Log probability information for the output tokens.
Log probability information for the reasoning tokens, if provided by the model.
A chat completion message generated by the model.
Show message properties
Show message properties
The contents of the message.
The role of the author of this message.
The model’s reasoning content when using reasoning models.
A list of tool calls the model requested in its response.
Show possible types
Show possible types
The Unix timestamp (in seconds) of when the chat completion was created.
The model used for the chat completion.
The object type, which is always
chat.completion.A fingerprint for the model or backend used to generate the response.
The service tier used for the request, or
null if not specified.The service tier used for processing the request. Only present when
service_tier is set to auto in the request.Possible values: priority, default, flexUsage statistics for the completion request.
Show usage properties
Show usage properties
Number of tokens in the prompt.
Number of tokens in the generated completion.
Total number of tokens used in the request (prompt + completion).
Detailed breakdown of prompt token usage.
Show properties
Show properties
Number of prompt tokens that were served from the cache and reused from a previous request. See Prompt Caching for more information.
Breakdown of completion tokens when using Predicted Outputs.
Show properties
Show properties
When using Predicted Outputs, the number of tokens in the prediction that appeared in the completion.
When using Predicted Outputs, the number of tokens in the prediction that did not appear in the completion. Like reasoning tokens, these tokens are still counted in the total completion tokens for the purposes of billing, output, and context window limits.
Tokens spent on model reasoning, if applicable.
Performance timing information for the request.
Show time_info properties
Show time_info properties
Time spent in queue waiting for processing (in seconds).
Time spent processing the prompt/input tokens (in seconds).
Time spent generating the completion/output tokens (in seconds).
Total time for the entire request from submission to completion (in seconds).
Unix timestamp (in seconds) of when the time_info was recorded.
from cerebras.cloud.sdk import Cerebras
import os
client = Cerebras(api_key=os.environ.get("CEREBRAS_API_KEY"),)
chat_completion = client.chat.completions.create(
model="gpt-oss-120b",
messages=[
{"role": "user", "content": "Hello!",}
],
)
print(chat_completion)
{
"id": "chatcmpl-30b3c3d8-ca41-48e7-9ef0-27e322604a13",
"choices": [
{
"finish_reason": "stop",
"index": 0,
"message": {
"role": "assistant",
"content": "Hello! 👋 How can I help you today?",
"reasoning": "The user just says \"Hello!\" with no further context.\n\nWe need to respond politely, maybe ask how can assist.\n\nWe can also be friendly.\n\nNo constraints. We'll respond as chat.",
"tool_calls": null
},
"logprobs": null,
"reasoning_logprobs": null
}
],
"created": 1769729480,
"model": "gpt-oss-120b",
"object": "chat.completion",
"system_fingerprint": "fp_e7ab83753cbd28777b40",
"time_info": {
"completion_time": 0.04040406,
"prompt_time": 0.00383762,
"queue_time": 0.004628115,
"total_time": 0.05013155937194824,
"created": 1769729480.0787008
},
"usage": {
"completion_tokens": 59,
"completion_tokens_details": {
"accepted_prediction_tokens": 0,
"rejected_prediction_tokens": 0,
"reasoning_tokens": 0
},
"prompt_tokens": 69,
"prompt_tokens_details": {
"cached_tokens": 0
},
"total_tokens": 128
},
"service_tier": null
}
Was this page helpful?
⌘I
Assistant
Responses are generated using AI and may contain mistakes.