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 inference target. 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"
});

The OpenAI-compatible model field selects the inference target:

With Shared Inference, use an exact Cerebras model ID.
With Dedicated Inference, use your stable endpoint ID. The endpoint routes the request to its active deployment.

The examples below call qwen-3.8-27b through Shared Inference. This model is also available through Dedicated Inference, using your assigned endpoint ID:

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

Use OpenAI SDK v3 for Python

Use the same Cerebras configuration with OpenAI SDK v3 for Python. openai 3.5.0 passed Cerebras compatibility tests for model listing, Chat Completions, Completions, and streaming. OpenAI SDK v3 for Python requires Python 3.10 or later and uses HTTPX2 instead of HTTPX. If you use the default HTTP client, you don’t need to change your Cerebras API calls. Review OpenAI’s HTTPX2 migration guide for:

Custom HTTP clients
HTTPX-specific request mocks or instrumentation
Corporate TLS-inspecting proxies
Custom certificate bundles

Connect a third-party tool or app

Many agents, chat apps, and developer tools that aren’t listed in Integrations let you add a custom OpenAI-compatible provider. To use Cerebras with one of these tools, open its model provider settings and enter these values:

Setting	Value
Provider type	OpenAI-compatible (sometimes labeled “OpenAI”, “Custom”, or “Custom endpoint”)
Base URL	`https://api.cerebras.ai/v1`
API key	Your Cerebras API key. Create one on the API Keys page.
Model	An exact model ID from the Model Catalog, such as `gpt-oss-120b` or `qwen-3.8-27b`

Enter the base URL exactly as shown. Most tools append /chat/completions automatically. If your tool asks for the full endpoint URL instead, use https://api.cerebras.ai/v1/chat/completions. The exact field names depend on the tool. Check the tool’s own documentation for where to set a custom OpenAI-compatible provider.

Compatibility differences

Area	Cerebras behavior
`n`	Only `n: 1` is supported
`service_tier`	Not available with Shared Inference on the Developer Tier.
`prediction`	Limited by endpoint and model availability. It is not available for `qwen-3.8-27b` with Shared Inference or for `kimi-k2.7-code`.
Tool streaming	Use standard streaming with `stream: true`. Do not send `tool_stream`.
Image URLs	Use standard `image_url` content parts with a base64 PNG or JPEG data URI. External HTTPS image URLs are not supported. `kimi-k3` accepts but ignores `image_url.detail`; behavior for other models depends on the endpoint configuration.
Images in tool results	Supported by enabled endpoints for compatible models, including `gemma-4-31b`, `kimi-k2.7-code`, and `kimi-k3`. Keep the full assistant response immediately before its tool results and use each returned tool-call ID exactly.

Reasoning compatibility

This guide covers both Shared Inference and Dedicated Inference. kimi-k2.7-code, kimi-k3, and zai-glm-5.3-flash are available through Dedicated Inference. Use the endpoint ID assigned to your organization as the request’s model value.

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-k3`	`low`, `high`, `max`; defaults to `max`; `medium` and `none` unsupported	`parsed` only; `raw` and `hidden` unsupported	Not supported
`zai-glm-5.3-flash`	`low`, `high`, `max`; defaults to `max`; `medium` and `none` unsupported	Defaults to `parsed`; `raw` and `hidden` supported	Supported; defaults to `false`

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 Inference

Compatibility

Cloud Console

Resources

Support

Configure OpenAI to use the Cerebras API

Use OpenAI SDK v3 for Python

Connect a third-party tool or app

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

​Use OpenAI SDK v3 for Python

​Connect a third-party tool or app

​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

Use OpenAI SDK v3 for Python

Connect a third-party tool or app

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