Cerebras

Connect AISIX AI Gateway to Cerebras so applications can call Cerebras-hosted models through the gateway's OpenAI-compatible API. AISIX keeps the Cerebras credential on the gateway side. It authorizes model access with caller API keys and allowlists, and applies the same rate-limit and usage-accounting controls as other model aliases.

Cerebras serves open-weight models on its own inference hardware and exposes an OpenAI-compatible API, so it uses the openai adapter with a Cerebras api_base.

Prerequisites

The following examples configure the upstream through the AISIX Cloud Admin API. Before configuring the upstream, prepare the following:

• A running AISIX managed control plane with an environment and an attached gateway. Follow the AISIX On-Premises Quickstart to set up the stack, create an admin token with write scope, and capture the environment ID.
• A Cerebras API key from the Cerebras Cloud console.

Export the connection details used by every request below:

# Replace with your values
export AISIX_CP="http://localhost:8080/api"
export AISIX_TOKEN="aisix_pat_YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

Configure the Cerebras Upstream

Create a provider key, model alias, and caller API key for the Cerebras-backed chat-completions route.

Create a Provider Key

Create the provider key that stores the Cerebras credential and API root:

# Replace with your value
export CEREBRAS_API_KEY="YOUR_PROVIDER_API_KEY"

PROVIDER_KEY_ID=$(curl -sS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "cerebras-prod",
    "provider": "cerebras",
    "api_key": "'"${CEREBRAS_API_KEY}"'",
    "api_base": "https://api.cerebras.ai/v1",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -r '.provider_key.id')

echo "$PROVIDER_KEY_ID"

❶ provider is cerebras. The Cloud Admin API derives the adapter from the catalog provider; the adapter field is only accepted on BYO provider keys.

❷ api_key stores the Cerebras API key. Cerebras authenticates with HTTP bearer authentication, which is what the openai adapter already sends. The value follows the credential-handling behavior in Provider Credentials.

❸ api_base is https://api.cerebras.ai/v1, the same root that Cerebras documents as the baseURL for OpenAI client libraries. It already includes the /v1 path, so AISIX appends the endpoint path, such as /chat/completions, directly to it. For the cerebras catalog provider the field is optional — the Cloud Admin API fills in this same value when you omit it — but the examples set it explicitly so the root each key targets stays visible in the configuration.

The command captures the returned provider key ID in PROVIDER_KEY_ID.

Create a Model

Cerebras model IDs are bare identifiers with no vendor prefix, even when the weights come from another vendor. The OpenAI open-weight model is gpt-oss-120b on Cerebras, and the Google model is gemma-4-31b. Check the Cerebras model catalog for the current list before you create an alias; the catalog is short and rotates as models are added and retired. Current IDs include gpt-oss-120b, gemma-4-31b, and zai-glm-4.7.

Create the model alias callers will send in requests:

MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "cerebras-gptoss-prod",
    "model_name": "gpt-oss-120b",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

echo "$MODEL_ID"

❶ display_name is the alias callers send in model.

❷ model_name is the Cerebras model ID, for example gpt-oss-120b or gemma-4-31b. Do not carry over a prefixed ID such as openai/gpt-oss-120b from another provider that hosts the same weights.

❸ provider_key_id attaches the alias to the Cerebras provider key.

Create a Caller API Key

Create the caller API key that can access the model alias. The plaintext key is server-generated and returned once in the create response, so capture it now:

AISIX_API_KEY=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "cerebras-caller",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }' | jq -r '.plaintext')

echo "$AISIX_API_KEY"

The allowed_models value must reference the model ID captured in the previous step. After the write, the configuration projects to attached gateways automatically.

Verify the Provider Connection

Send a chat-completions request through the AISIX proxy:

curl -sS -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cerebras-gptoss-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from Cerebras."
      }
    ]
  }'

The gateway returns an OpenAI-compatible response that echoes the caller-facing alias cerebras-gptoss-prod. If the request fails, check the provider key api_key, api_base, and the Cerebras model ID in model_name.

Send Token Limits

Cerebras follows current OpenAI parameter naming and documents max_completion_tokens for the generated-token cap in Chat Completions. The Cerebras entry in the AISIX provider catalog therefore configures no parameter renames, and AISIX forwards max_completion_tokens to Cerebras exactly as the caller sent it. Some other OpenAI-compatible upstreams still expect the older max_tokens name and carry a rename for it, so a request body that works against Cerebras is not automatically portable to every openai-adapter provider.

If an existing client sends the older max_tokens name and you need it delivered under the current name, add a rename on the provider key:

{
  "request": {
    "param_renames": {
      "max_tokens": "max_completion_tokens"
    }
  }
}

The rename applies to every model that references the provider key. See Provider-Specific Overrides.

Control Reasoning Effort

Cerebras accepts the standard OpenAI reasoning_effort parameter at the top level of the chat-completions body. AISIX does not strip unrecognized top-level parameters, so the value reaches the upstream unchanged:

{
  "model": "cerebras-gptoss-prod",
  "messages": [
    {
      "role": "user",
      "content": "Plan a three-step migration."
    }
  ],
  "reasoning_effort": "low"
}

Accepted values depend on the model:

Model	reasoning_effort values	Default
gpt-oss-120b	low, medium, high	medium
gemma-4-31b	none, low, medium, high	none
zai-glm-4.7	none to disable reasoning	Reasoning enabled

Confirm the values for the model you configured in the Cerebras reasoning documentation, because a value one model accepts can be rejected by another.

The Cerebras catalog entry sets no reasoning-field override, so AISIX preserves reasoning that the upstream already returns in the canonical reasoning_content field for streaming and non-streaming responses. If a Cerebras model streams reasoning at a different delta path, set response.reasoning_field on the provider key.

Route Latency-Sensitive Traffic

A Cerebras alias is a useful target in a routing model that ranks targets by observed latency. Create a routing model with strategy set to least_latency and list the Cerebras alias alongside a fallback target. AISIX ranks targets by a moving average of recent upstream latency, using time to first token for streaming requests, and probes targets that have no samples yet before ranking them. See Route by Cost, Latency, or Load.

Endpoint Support

Cerebras is an inference-only upstream, so only part of the proxy surface applies to a Cerebras-backed alias.

Route	Behavior with a Cerebras alias
/v1/chat/completions	Supported, including stream: true.
/v1/responses	Supported through the Responses bridge over the chat adapter path.
/v1/messages	Supported for Anthropic-shaped callers through translation. Token counting at /v1/messages/count_tokens requires an Anthropic-backed model.
/v1/embeddings	Not usable. Cerebras serves language models and does not publish embedding models, so route embeddings to a separate provider. See Embeddings.
/v1/images/generations	Rejected. The route accepts only models whose provider is openai.
/v1/rerank	Rejected. The route accepts only the openai, cohere, and jina provider values.
/v1/videos	Rejected. The route accepts only its own provider allowlist, which does not include cerebras.
/passthrough/cerebras/*	Supported for provider-native routes, with limited gateway normalization. See Provider Passthrough.

Next Steps

You have now connected AISIX to Cerebras and verified the model alias. Continue with these guides:

• Model Aliases: add routing, cost metadata, and rate limits for this alias.
• Routing and Failover: fail over between Cerebras and a second provider.
• Provider-Specific Overrides: adapt request and response shapes when an upstream API differs from its adapter.
• Provider Compatibility: review supported proxy endpoints and provider-specific boundaries.