---
title: "Create chat completion"
method: POST
path: "/v1/chat/completions"
---

# Create chat completion

`POST /v1/chat/completions`

## Request

- Base URL: `https://api.cerebras.ai`
- URL: `https://api.cerebras.ai/v1/chat/completions`
- Auth: HTTP bearer

Generate conversational responses using a structured message format with roles (system, user, assistant, developer, tool). Best for chatbots, assistants, and multi-turn conversations.

## Headers

- `Content-Type` 'application/json' | 'application/vnd.msgpack'
- `Content-Encoding` 'gzip'
- `queue_threshold` string

## Request body

- ChatCompletionRequest
  - `messages` union[], 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. <br/>
    - union
      - SystemMessage: Developer-provided instructions the model should follow regardless of user messages.
        - `role` 'system', required: The role of the message author. Always `system`.
        - `content` union, required: The contents of the system message.
          - string: Text content string.
          - object[]: Array of text content parts.
            - `type` 'text', required
            - `text` string, required
        - `name` string: An optional name for the participant. Provides the model with information to differentiate between participants of the same role.
      - UserMessage: Messages sent by an end user, containing prompts or additional context.
        - `role` 'user', required: The role of the message author. Always `user`.
        - `content` union, required: The contents of the user message. Can include text and image inputs. Supported content types differ by model. <br/>
          - string: Text content string.
          - union[]: Array of content parts (text and/or image).
            - union
              - …
        - `name` string: An optional name for the participant. Provides the model with information to differentiate between participants of the same role.
      - AssistantMessage: Messages sent by the model in response to user messages.
        - `role` 'assistant', required: The role of the message author. Always `assistant`.
        - `content` union: The contents of the assistant message.
          - string: Text content string.
          - object[]: Array of content parts. For assistant messages, only type `text` is supported.
            - `type` 'text', required
            - `text` string, required
        - `name` string: An optional name for the participant.
        - `reasoning` string, nullable: The reasoning content from the model's response. Include this when passing back assistant messages that contained reasoning.
        - `tool_calls` object[]: Tool calls generated by the model, such as function calls.
          - `id` string, required: The ID of the tool call.
          - `type` 'function', required: The type of tool. Currently only `function` is supported.
          - `function` object, required
            - `name` string, required: The name of the function to call.
            - `arguments` string, required: The arguments to call the function with, as generated by the model in JSON format.
      - ToolMessage: Tool message containing the result of a tool call.
        - `role` 'tool', required: The role of the message author. Always `tool`.
        - `content` union, required: The contents of the tool message.
          - string: Text content string.
          - object[]: Array of text content parts.
            - `type` 'text', required
            - `text` string, required
        - `tool_call_id` string, required: The tool call that this message is responding to.
      - DeveloperMessage: Developer-provided instructions the model should follow regardless of user messages. For `gpt-oss-120b`, developer messages replace system messages, but `system` is still accepted. Only available for the `gpt-oss-120b` model.
        - `role` 'developer', required: The role of the message author. Always `developer`.
        - `content` union, required: The contents of the developer message.
          - string: Text content string.
          - object[]: Array of text content parts.
            - `type` 'text', required
            - `text` string, required
        - `name` string: An optional name for the participant.
  - `model` string, required: The ID of the model to use for generating a response.
  - `clear_thinking` boolean, nullable: Controls whether thinking content from previous conversation turns is included in the prompt context. - `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. When this parameter is not specified or set to `null`, the API defaults to `clear_thinking: true`. Only supported on the `zai-glm-4.7` model. For additional information, see [Preserved thinking](https://docs.z.ai/guides/capabilities/thinking-mode#preserved-thinking) in the Z.ai documentation.
  - `frequency_penalty` number, nullable: 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.
  - `logit_bias` object, nullable: 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: Whether to return log probabilities of the output tokens.
  - `max_completion_tokens` integer, nullable: 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.
  - `parallel_tool_calls` boolean, nullable: 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, nullable: Configuration for a [Predicted Output](/capabilities/predicted-outputs), 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.
    - `type` 'content', required: The type of predicted content. Always `content`.
    - `content` union, required: The content that should be matched when generating a model response.
      - string: The content used for a given Predicted Output. Typically the text of a file you are regenerating with only minor changes.
      - object[]: Array of text content parts.
        - `type` 'text', required
        - `text` string, required: The text content.
  - `presence_penalty` number, nullable: 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.
  - `prompt_cache_key` string, nullable: An opaque identifier that groups related requests so they reuse the same [prompt cache](/capabilities/prompt-caching). 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 like a conversation ID, user ID, or session ID. **Requires account-level enablement. [Contact us](https://www.cerebras.ai/contact) or reach out to your account representative to request access.**
  - `reasoning_effort` 'low' | 'medium' | 'high' | 'none', nullable: Controls the amount of reasoning the model performs. Supported values vary by model: - **gpt-oss-120b**: `low`, `medium` (default), `high` - **zai-glm-4.7**: `none` (disables reasoning) - **gemma-4-31b**: `none` (default), `low`, `medium`, `high` (all enable reasoning equivalently). `raw` and `hidden` reasoning formats are not supported.
  - `response_format` union: An object that controls the format of the model response. Setting `{ "type": "json_schema", ... }` enables Structured Outputs, which enforces schema compliance. See [Structured Outputs](/capabilities/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 — `stream` must be set to `false`.
    - ResponseFormatText: Text format (default). Generates plain text responses.
      - `type` 'text', required: The type of response format being defined. Always `text`.
    - ResponseFormatJsonSchema: JSON Schema format. Enforces schema compliance for structured output. Recommended over `json_object` for models that support it.
      - `type` 'json_schema', required: The type of response format being defined. Always `json_schema`.
      - `json_schema` object, required
        - `name` string, required: An optional name for your schema.
        - `description` string: A description of the response format's purpose, used by the model to determine how to generate its response.
        - `schema` object: A valid [JSON Schema](https://json-schema.org/) 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`).
        - `strict` boolean: When `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`.
    - ResponseFormatJsonObject: JSON object format (legacy). Ensures valid JSON output but does not enforce a specific schema. Using `json_schema` is recommended for models that support it. To use `json_object`, include a system or user message specifying the desired format. `json_object` is not compatible with streaming — `stream` must be set to `false`.
      - `type` 'json_object', required: The type of response format being defined. Always `json_object`.
  - `seed` integer, nullable: 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` 'priority' | 'default' | 'auto' | 'flex', nullable: Controls request prioritization. **Note**: This feature is in **Private Preview**. For access or more information, [contact us](https://www.cerebras.ai/contact) 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](/capabilities/service-tiers) for more information.
  - `stop` string, nullable: Up to 4 sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence.
  - `stream` boolean, nullable: If set to `true`, partial message deltas will be sent.
  - `temperature` number, nullable: Sampling temperature between 0 and 2.0. Higher values (e.g. 0.8) make output more random; lower values (e.g. 0.2) make it more focused and deterministic. We recommend altering this or `top_p`, not both.
  - `tool_choice` union: Controls which (if any) tool is called by the model. - `none` — no tool is called - `auto` — (default when tools are present) the model chooses whether to call a tool - `required` — forces a tool call A specific tool can be forced by passing an object specifying the function name.
    - 'none' | 'auto' | 'required'
    - object
      - `type` 'function', required
      - `function` object, required
        - `name` string, required: The name of the function to call.
  - `tools` object[], nullable: 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.
    - `type` 'function', required: The type of the tool. Currently only `function` is supported.
    - `function` object, required
      - `name` string, required: The name of the function to call. Supported characters: `a-z`, `A-Z`, `0-9`, `_`, `-`. Maximum length: 64.
      - `description` string: A description of what the function does, used by the model to choose when and how to call the function.
      - `parameters` object: The parameters the function accepts, described as a JSON Schema object. Omitting parameters defines a function with an empty parameter list.
  - `top_logprobs` integer, nullable: 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`.
  - `top_p` number, nullable: Nucleus sampling parameter. The model considers only the tokens comprising the top `top_p` probability mass (e.g. 0.1 means only the tokens comprising the top 10% probability mass are considered). We recommend altering this or `temperature`, not both.
  - `user` string, nullable: A unique identifier representing your end-user, which can help monitor and detect abuse.

## Response `200`

Successful response

- ChatCompletionResponse
  - `id` string: A unique identifier for the chat completion.
  - `choices` object[]: A list of chat completion choices. Can be more than one if `n` is greater than 1.
    - `finish_reason` 'stop' | 'length' | 'content_filter' | 'tool_calls': The reason the model stopped generating tokens.
    - `index` integer: The index of the choice in the list of choices.
    - `logprobs` object, nullable: Log probability information for the output tokens.
    - `reasoning_logprobs` object, nullable: Log probability information for the reasoning tokens, if provided by the model.
    - `message` object: A chat completion message generated by the model.
      - `content` string, nullable: The contents of the message.
      - `role` string: The role of the author of this message.
      - `reasoning` string: The model's reasoning content when using reasoning models.
      - `tool_calls` object[], nullable: Tool calls the model requested in its response.
        - `id` string: The ID of the tool call.
        - `type` 'function': The type of tool call.
        - `function` object: The function call details.
          - `name` string: The name of the function called.
          - `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` 'chat.completion': The object type. Always `chat.completion`.
  - `system_fingerprint` string: A fingerprint for the model or backend used to generate the response.
  - `service_tier` string, nullable: The service tier used for the request, or `null` if not specified.
  - `service_tier_used` 'priority' | 'default' | 'flex', nullable: The service tier used for processing the request. Only present when `service_tier` is set to `auto` in the request.
  - `usage` object: Usage statistics for the completion request.
    - `prompt_tokens` integer: Number of tokens in the prompt.
    - `completion_tokens` integer: Number of tokens in the generated completion.
    - `total_tokens` integer: Total number of tokens used (prompt + completion).
    - `image_tokens` integer: Number of tokens used to represent image inputs. Present for requests to vision-capable models.
    - `prompt_tokens_details` object: Detailed breakdown of prompt token usage.
      - `cached_tokens` integer: Number of prompt tokens served from the cache, reused from a previous request.
    - `completion_tokens_details` object: Breakdown of completion tokens when using Predicted Outputs.
      - `accepted_prediction_tokens` integer: Tokens in the prediction that appeared in the completion.
      - `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.
      - `reasoning_tokens` integer: Tokens spent on model reasoning, if applicable.
  - `time_info` object: Performance timing information for the request.
    - `queue_time` number: Time spent in queue waiting for processing (seconds).
    - `prompt_time` number: Time spent processing prompt/input tokens (seconds).
    - `completion_time` number: Time spent generating completion/output tokens (seconds).
    - `total_time` number: Total time for the entire request from submission to completion (seconds).
    - `created` number: Unix timestamp of when the time_info was recorded.

---

[API](https://skmtc.dev/cerebras/apis/cerebras-inference-api.md) - [All operations](https://skmtc.dev/cerebras/apis/cerebras-inference-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cerebras/apis/cerebras-inference-api/revisions/c8b3fb650198?raw)