Cerebras Python SDK

In API responses, a field that is explicitly null or missing entirely will both appear as None in the SDK. To distinguish between these two cases, use the .model_fields_set attribute on the response object. If the field name is not present in model_fields_set, the key was missing from the JSON; otherwise, the key was present with a null value.

if response.my_field is None:
  if 'my_field' not in response.model_fields_set:
    print('Got json like {}, without a "my_field" key present at all.'.format(response.model_dump()))
  else:
    print('Got json like {"my_field": null}.')

The SDK uses the standard Python logging module. You can control the verbosity of logs by setting the CEREBRAS_LOG environment variable.

Set CEREBRAS_LOG to info for standard logging or debug for more verbose output.

$ export CEREBRAS_LOG=info

While the SDK automatically closes connections when the client is garbage collected, it is best practice to manage the lifecycle manually using a context manager or by calling .close() to ensure resources are released promptly.

from cerebras.cloud.sdk import Cerebras

with Cerebras() as client:
  # make requests here
  ...

# HTTP client is now closed

Install the cerebras_cloud_sdk package using pip. This library requires Python 3.9 or higher.

pip install cerebras_cloud_sdk

To use the SDK, obtain an API Key from cloud.cerebras.ai and set it as an environment variable named CEREBRAS_API_KEY. The SDK will automatically look for this variable if no api_key is provided to the constructor.

export CEREBRAS_API_KEY="your-api-key-here"

By default, the async client uses httpx. To use aiohttp for improved concurrency performance, install the extra dependency and pass DefaultAioHttpClient() to the http_client parameter.

pip install 'cerebras_cloud_sdk[aiohttp]'

import os
import asyncio
from cerebras.cloud.sdk import DefaultAioHttpClient
from cerebras.cloud.sdk import AsyncCerebras

async def main() -> None:
    async with AsyncCerebras(
        api_key=os.environ.get("CEREBRAS_API_KEY"),
        http_client=DefaultAioHttpClient(),
    ) as client:
        chat_completion = await client.chat.completions.create(
            messages=[
                {
                    "role": "user",
                    "content": "Why is fast inference important?",
                }
            ],
            model="gpt-oss-120b",
        )

asyncio.run(main())

You can monitor token consumption and performance via the usage and time_info fields in a ChatCompletionResponse or ChatChunkResponse.

Usage Details:

• prompt_tokens: Total tokens in the input.
• prompt_tokens_details.cached_tokens: Number of tokens retrieved from cache.
• completion_tokens: Total tokens in the output.
• completion_tokens_details.reasoning_tokens: Tokens used specifically for model reasoning.
• total_tokens: Sum of prompt and completion tokens.

Time Information (in seconds):

• prompt_time: Time spent processing the prompt.
• queue_time: Time spent in the request queue.
• completion_time: Time spent generating the completion.
• total_time: Total end-to-end request time.

The ModelListResponse is a union type that represents the response from a model listing operation. Depending on the provider or context, it can take one of three forms:

1. ModelMetadataList: The standard Cerebras model list format.
2. OpenRouterModelsResponse: A format compatible with OpenRouter, containing detailed pricing, datacenter info, and OpenRouter-specific metadata.
3. HuggingFaceModelsResponse: A format compatible with HuggingFace, used for provider comparison and selection, including pricing in USD per million tokens and capability flags.

When consuming the API, you should handle these different response shapes accordingly.

You can customize the underlying httpx client by passing a DefaultHttpxClient instance to the Cerebras constructor. This allows for proxy configuration and custom transports. You can also apply these configurations to a specific client instance using .with_options().

import httpx
from cerebras.cloud.sdk import Cerebras, DefaultHttpxClient

client = Cerebras(
    # Or use the `CEREBRAS_BASE_URL` env var
    base_url="http://my.test.server.example.com:8083",
    http_client=DefaultHttpxClient(
        proxy="http://my.test.proxy.example.com",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)

# Per-request customization
client.with_options(http_client=DefaultHttpxClient(...))