OpenAI Compatibility

The Cerebras API is compatible with OpenAI client libraries for many common workflows. Existing applications can use Cerebras by changing the API key, base URL, and model ID. Cerebras also provides dedicated Python and TypeScript SDKs.

Configure OpenAI to use the Cerebras API

Set the API key and base URL when you initialize the client. Python uses api_key and base_url; JavaScript uses apiKey and baseURL.

import os
import openai

client = openai.OpenAI(
    base_url="https://api.cerebras.ai/v1",
    api_key=os.environ.get("CEREBRAS_API_KEY")
)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.CEREBRAS_API_KEY,
  baseURL: "https://api.cerebras.ai/v1"
});

Use an exact Cerebras model ID in each request. The examples below use qwen-3.8-27b:

response = client.chat.completions.create(
    model="qwen-3.8-27b",
    messages=[{"role": "user", "content": "Explain this code."}],
)

Compatibility differences

Area	Cerebras behavior
`n`	Only `n: 1` is supported
`service_tier`	Not available on shared endpoints or Kimi K2.7 Code customer-trial endpoints
`prediction`	Limited by endpoint and model availability. It is not available for `qwen-3.8-27b` or `kimi-k2.7-code` on shared or trial endpoints.
Tool streaming	Use standard streaming with `stream: true`. Do not send `tool_stream`.
Image URLs	Use standard `image_url` content parts, but provide a base64 PNG or JPEG data URI. External HTTPS image URLs and `image_url.detail` are not supported.

Reasoning compatibility

Model	`reasoning_effort`	`reasoning_format`	`clear_thinking`
`qwen-3.8-27b`	`none`, `low`, `medium`, `high`; defaults to `high`	Reasoning is returned separately; `hidden` is not supported	Supported; defaults to `false`
`kimi-k2.7-code`	Accepted but ignored; reasoning is always enabled	Defaults to `parsed`; `raw` supported; `hidden` unsupported	Not supported

Kimi K2.7 Code is currently available only through customer trials, not on the public shared tier. See Reasoning and Image Inputs for complete model-specific behavior.

Image input with the OpenAI client

The standard OpenAI image_url content shape is supported. Supply the image as a base64 data URI:

import base64

with open("screenshot.png", "rb") as image_file:
    encoded = base64.b64encode(image_file.read()).decode("utf-8")

response = client.chat.completions.create(
    model="qwen-3.8-27b",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Describe this screenshot."},
            {
                "type": "image_url",
                "image_url": {"url": f"data:image/png;base64,{encoded}"},
            },
        ],
    }],
)

Developer-level instructions via system and developer roles

This section applies only to gpt-oss-120b.

For gpt-oss-120b, the API supports both the system and developer message roles. Both are mapped to a developer-level instruction layer in the prompt hierarchy, elevated above normal user instructions and injected into the model’s internal system prompt. This gives you significant control over the assistant’s tone, style, and behavior while preserving the model’s built-in safety guardrails. The developer role is functionally equivalent to system. The system role remains supported for backward compatibility.

Key differences from OpenAI

OpenAI’s API distinguishes between system and developer roles with different behavior. On Cerebras, both roles act at the developer level, meaning they may have stronger influence than system messages in OpenAI’s API. As a result, the same prompt may yield different behavior here compared to OpenAI. This is expected.

Unsupported parameter combinations

Support for combining tools and response_format is model-dependent. Do not combine them unless the selected model’s documentation explicitly supports and validates the combination. gpt-oss-120b rejects requests containing both fields. For portable behavior across Cerebras models, use one of the following approaches:

Tool calling only: Omit response_format and let the model invoke tools. For structured arguments, define a JSON schema in the tool’s parameters field.
Structured Outputs only: Omit tools and use response_format with a JSON schema. See Structured Outputs.
Two-step pipeline: Make one request with tools to gather data, then make another request with response_format to format the final result.

See Tool Use and Structured Outputs for details on each capability.

Pass non-standard parameters

reasoning_effort is a standard OpenAI parameter. reasoning_format and clear_thinking are Cerebras-specific parameters.

OpenAI client libraries: Pass Cerebras-specific parameters through extra_body.
Cerebras SDKs: Pass Cerebras-specific parameters as top-level arguments. The SDKs also accept extra_body for untyped extensions.

Use an OpenAI client

Pass Cerebras-specific parameters through extra_body when using an OpenAI client:

client = OpenAI(
    base_url="https://api.cerebras.ai/v1",
    api_key=os.environ.get("CEREBRAS_API_KEY")
)

response = client.chat.completions.create(
    model="qwen-3.8-27b",
    messages=[...],
    reasoning_effort="high",  # OpenAI parameter, no extra_body needed
    extra_body={
        "reasoning_format": "parsed",
        "clear_thinking": False
    }
)

const client = new OpenAI({
    baseURL: "https://api.cerebras.ai/v1",
    apiKey: process.env.CEREBRAS_API_KEY
});

const response = await client.chat.completions.create({
    model: "qwen-3.8-27b",
    messages: [...],
    reasoning_effort: "high",  // OpenAI parameter, no extra_body needed
    extra_body: {
        reasoning_format: "parsed",
        clear_thinking: false
    }
});

Use a Cerebras SDK

Pass Cerebras-specific parameters as top-level arguments when using a Cerebras SDK:

client = Cerebras(
    api_key=os.environ.get("CEREBRAS_API_KEY")
)

response = client.chat.completions.create(
    model="qwen-3.8-27b",
    messages=[...],
    reasoning_effort="high",    # OpenAI parameter
    reasoning_format="parsed",  # Cerebras-specific parameter
    clear_thinking=False         # Cerebras-specific parameter
)

const client = new Cerebras({
    apiKey: process.env.CEREBRAS_API_KEY
});

const response = await client.chat.completions.create({
    model: "qwen-3.8-27b",
    messages: [...],
    reasoning_effort: "high",    // OpenAI parameter
    reasoning_format: "parsed",  // Cerebras-specific parameter
    clear_thinking: false         // Cerebras-specific parameter
});

Get Started

Models

Capabilities

Dedicated Endpoints

Compatibility

Cloud Console

Resources

Support

Configure OpenAI to use the Cerebras API

Compatibility differences

Reasoning compatibility

Image input with the OpenAI client

Developer-level instructions via system and developer roles

Key differences from OpenAI

Unsupported parameter combinations

Pass non-standard parameters

​Configure OpenAI to use the Cerebras API

​Compatibility differences

​Reasoning compatibility

​Image input with the OpenAI client

​Developer-level instructions via system and developer roles

​Key differences from OpenAI

​Unsupported parameter combinations

​Pass non-standard parameters

Configure OpenAI to use the Cerebras API

Compatibility differences

Reasoning compatibility

Image input with the OpenAI client

Developer-level instructions via system and developer roles

Key differences from OpenAI

Unsupported parameter combinations

Pass non-standard parameters