> ## Documentation Index
> Fetch the complete documentation index at: https://inference-docs.cerebras.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Compatibility

> Use OpenAI client libraries with Cerebras Inference.

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`.

<CodeGroup>
  ```python Python theme={null}
  import os
  import openai

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

  ```javascript Node.js theme={null}
  import OpenAI from "openai";

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

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 use the Shared Inference model ID [`qwen-3.8-27b`](/models/qwen-3.8-27b):

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

## Connect a third-party tool or app

Many agents, chat apps, and developer tools that aren't listed in [Integrations](/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](/console/api-keys) page. |
| Model | An exact model ID from the [Model Catalog](/models/overview), 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 or Kimi K2.7 Code customer trials |
| `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` customer trials. |
| 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 with Shared Inference.

See [Reasoning](/capabilities/reasoning) and [Image Inputs](/capabilities/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:

```python theme={null}
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

<Note>This section applies only to `gpt-oss-120b`.</Note>

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](/capabilities/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](/capabilities/tool-use) and [Structured Outputs](/capabilities/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.

<Accordion title="Use an OpenAI client">
  Pass Cerebras-specific parameters through `extra_body` when using an OpenAI client:

  <CodeGroup>
    ```python Python theme={null}
    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
        }
    )
    ```

    ```javascript Node.js theme={null}
    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
        }
    });
    ```
  </CodeGroup>
</Accordion>

<Accordion title="Use a Cerebras SDK">
  Pass Cerebras-specific parameters as top-level arguments when using a Cerebras SDK:

  <CodeGroup>
    ```python Python theme={null}
    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
    )
    ```

    ```javascript Node.js theme={null}
    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
    });
    ```
  </CodeGroup>
</Accordion>