---
title: Cerebras
description: Learn how to use Cerebras with AI Gateway and the direct provider.
url: "https://ai-sdk.dev/providers/ai-sdk-providers/cerebras"
docs_index: /llms.txt
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

The [Cerebras](https://cerebras.ai) provider offers access to powerful language models through the Cerebras API, including their high-speed inference capabilities powered by Wafer-Scale Engines and CS-3 systems.
Start with [AI Gateway](/providers/ai-sdk-providers/ai-gateway) for models in its catalog (recommended), or use `@ai-sdk/cerebras` to connect directly to Cerebras.

```ts provider="cerebras" model="openai/gpt-oss-120b"
import { generateText } from 'ai';

const { text } = await generateText({
  model: "openai/gpt-oss-120b",
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
  providerOptions: {
    gateway: {
      order: ['cerebras'],
    },
  },
});

console.log(text);
```

## Using AI Gateway

The AI SDK uses AI Gateway by default for model strings. Gateway provides access to models across providers through a single API key, with usage and cost tracking. Install `ai`:

```bash
pnpm add ai
```

Set an [AI Gateway API key](https://vercel.com/docs/ai-gateway/getting-started) in your environment:

```bash
export AI_GATEWAY_API_KEY=your_api_key_here
```

Vercel deployments can also use [OIDC authentication](/providers/ai-sdk-providers/ai-gateway#oidc-authentication-vercel-deployments).
See the [AI Gateway provider documentation](/providers/ai-sdk-providers/ai-gateway) for configuration and the [model catalog](https://vercel.com/ai-gateway/models) for available models.

The example sets `providerOptions.gateway.order` to `['cerebras']`. This sends the request to Cerebras first, then falls back to other available providers of the same model if Cerebras is unavailable or the request fails. `order` sets a preference; it does not restrict fallback to Cerebras. See [provider ordering](https://vercel.com/docs/ai-gateway/models-and-providers/provider-filtering-and-ordering).

The dropdown lists models served by Cerebras through Gateway with a corresponding direct-provider example. Provider availability depends on the model and your team's [Provider Allowlist](https://vercel.com/docs/ai-gateway/models-and-providers/provider-filtering-and-ordering).

## Using `@ai-sdk/cerebras`

For direct access to Cerebras, install `ai` and `@ai-sdk/cerebras`:

```bash
pnpm add ai @ai-sdk/cerebras
```

Set your Cerebras API credential in the `CEREBRAS_API_KEY` environment variable:

```bash
export CEREBRAS_API_KEY=your_api_key_here
```

AI Gateway does not expose every API in `@ai-sdk/cerebras`. Use the direct provider for provider-specific APIs or custom connection settings.

The following sections document the direct `@ai-sdk/cerebras` provider,
including its model factories and settings. Gateway model and feature
availability can differ.

API keys can be obtained from the [Cerebras Platform](https://cloud.cerebras.ai).

## Provider Instance

You can import the default provider instance `cerebras` from `@ai-sdk/cerebras`:

```ts
import { cerebras } from '@ai-sdk/cerebras';
```

For custom configuration, you can import `createCerebras` and create a provider instance with your settings:

```ts
import { createCerebras } from '@ai-sdk/cerebras';

const cerebras = createCerebras({
  apiKey: process.env.CEREBRAS_API_KEY ?? '',
});
```

You can use the following optional settings to customize the Cerebras provider instance:

- **baseURL** *string*

  Use a different URL prefix for API calls.
  The default prefix is `https://api.cerebras.ai/v1`.

- **apiKey** *string | PromiseLike\<string> | (() => string | PromiseLike\<string>)*

  API key that is being sent using the `Authorization` header. It defaults to
  the `CEREBRAS_API_KEY` environment variable.

  A function is called before each request and may return a promise. Use it to
  supply refreshed credentials; a promise value resolves to the same key each time.

- **headers** *Record\<string,string>*

  Custom headers to include in the requests.

- **fetch** *(input: RequestInfo, init?: RequestInit) => Promise\<Response>*

  Custom [fetch](https://developer.mozilla.org/en-US/docs/Web/API/fetch) implementation.

## Language Models

You can create language models using a provider instance:

```ts
import { cerebras } from '@ai-sdk/cerebras';
import { generateText } from 'ai';

const { text } = await generateText({
  model: cerebras('gpt-oss-120b'),
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
});
```

Cerebras language models can be used in the `streamText` function
(see [AI SDK Core](/docs/ai-sdk-core)).

You can create Cerebras language models using a provider instance. The first argument is the model ID, e.g. `gpt-oss-120b`:

```ts
const model = cerebras('gpt-oss-120b');
```

You can also use the `.languageModel()` and `.chat()` methods:

```ts
const languageModel = cerebras.languageModel('gpt-oss-120b');
const chatModel = cerebras.chat('gpt-oss-120b');
```

### Reasoning Models

Cerebras offers reasoning models including `gpt-oss-120b` and `gemma-4-31b` that generate intermediate thinking tokens before their final response. The reasoning output is streamed through the standard AI SDK reasoning parts.

For `gpt-oss-120b`, you can control the reasoning depth using the `reasoningEffort` provider option:

```ts
import { cerebras } from '@ai-sdk/cerebras';
import { streamText } from 'ai';

const result = streamText({
  model: cerebras('gpt-oss-120b'),
  providerOptions: {
    cerebras: {
      reasoningEffort: 'medium',
    },
  },
  prompt: 'How many "r"s are in the word "strawberry"?',
});

for await (const part of result.stream) {
  if (part.type === 'reasoning') {
    console.log('Reasoning:', part.text);
  } else if (part.type === 'text-delta') {
    process.stdout.write(part.textDelta);
  }
}
```

See [AI SDK UI: Chatbot](/docs/ai-sdk-ui/chatbot#reasoning) for more details on how to integrate reasoning into your chatbot.

### Provider Options

The following optional provider options are available for Cerebras language models:

- **parallelToolCalls** *boolean*

  Whether to enable parallel function calling during tool use. Defaults to `true`.

- **logprobs** *boolean*

  Whether to return log probabilities for generated tokens. Defaults to `false`.

- **topLogprobs** *number*

  Number of most likely tokens to return at each token position. Accepts values from `0` through `20`. Requires `logprobs` to be `true`.

- **logitBias** *Record\<string, number>*

  Maps token IDs to bias values from `-100` through `100`.

- **serviceTier** *'auto' | 'default' | 'flex' | 'priority'*

  Controls request priority on a dedicated endpoint with service tiers enabled through Cerebras private preview. Service tiers are not available with Shared Inference on the Developer Tier. `default` uses standard priority, `flex` uses the lowest priority, `auto` starts at standard priority and falls back to `flex` when needed, and `priority` requests the highest configured priority.

  See the [Cerebras service tiers documentation](https://inference-docs.cerebras.ai/capabilities/service-tiers).

  When the API returns `service_tier`, the effective tier is surfaced on `result.providerMetadata.cerebras.serviceTier` (or the awaited stream metadata). For example, an `auto` request can return `flex`, and a `priority` request can return `auto`. The metadata field is omitted when the response field is missing or `null`; it is never inferred from the requested tier.

- **queueThreshold** *number*

  Maximum acceptable queue time, in integer milliseconds, for `flex`/`auto` requests on a supported endpoint. If the expected queue time exceeds the threshold, the request is rejected instead of queued. Sent as the `queue_threshold` header, taking precedence over a custom header with that name. Valid range: `50`–`20000` (inclusive).

- **reasoningEffort** *'none' | 'low' | 'medium' | 'high'*

  Controls the amount of reasoning performed by supported models. Supported values and defaults depend on the model.

- **reasoningFormat** *'none' | 'parsed' | 'text\_parsed' | 'raw' | 'hidden'*

  Controls how reasoning content appears in the response. Format support depends on the model.

- **prediction** *\{ type: 'content'; content: string | Array\<\{ type: 'text'; text: string }> }*

  Supplies predicted output that can accelerate requests where most of the response is already known.

- **promptCacheKey** *string*

  Routes related requests to the same prompt cache. The value can contain up to 1024 characters and requires account-level enablement.

- **user** *string*

  A unique identifier representing your end-user, which can help with monitoring and abuse detection.

- **strictJsonSchema** *boolean*

  Whether to use strict JSON schema validation. When `true`, the model uses constrained decoding to guarantee schema compliance. Defaults to `true`.

For example:

```ts
import {
  cerebras,
  type CerebrasLanguageModelChatOptions,
} from '@ai-sdk/cerebras';
import { generateText } from 'ai';

const result = await generateText({
  model: cerebras('gpt-oss-120b'),
  prompt: 'Explain why the sky is blue.',
  providerOptions: {
    cerebras: {
      reasoningEffort: 'low',
      reasoningFormat: 'parsed',
      promptCacheKey: 'conversation-123',
    } satisfies CerebrasLanguageModelChatOptions,
  },
});
```

## Model Capabilities

| Model          | Image Input | Object Generation | Tool Usage | Tool Streaming | Reasoning |
| -------------- | ----------- | ----------------- | ---------- | -------------- | --------- |
| `gpt-oss-120b` | ✗           | ✓                 | ✓          | ✓              | ✓         |
| `gemma-4-31b`  | ✓           | ✓                 | ✓          | ✓              | ✓         |

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)