Cerebras

Cerebras Inference hosts open-weight models on Cerebras inference systems. AISIX places those models behind one OpenAI-compatible API and centralizes upstream credentials, caller access, rate limits, and usage accounting.

Prerequisites

Before starting, prepare the following:

• One AISIX setup:
  • For AISIX Cloud, an environment with an attached gateway and a write-scoped admin token. For On-Premises, follow the AISIX Cloud Quickstart. To request Hybrid Cloud access, contact API7.
  • For the open-source AISIX gateway, prepare either a local AISIX installation or the Docker setup from the Open-Source AISIX Gateway Quickstart. Configure the gateway to load a declarative resources file.
• A Cerebras API key from the Cerebras Cloud console.
• curl and jq.

Configure with AISIX Cloud

Export the AISIX Cloud connection details:

# AISIX_CP is the Admin API base URL; include /api and omit a trailing slash
# The local On-Premises quickstart uses http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

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

Because the Cerebras API is OpenAI-compatible, AISIX connects through the openai adapter and uses the Cerebras API root as api_base.

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 AISIX 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 Keys.

❸ 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 AISIX 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.

Configure with the Open-Source AISIX Gateway

Export the upstream credential and choose the caller API key that applications will send to the gateway:

export CEREBRAS_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

For a new gateway, use this complete resources file. For an existing gateway, merge the entries into its current file, preserving its other resources:

resources.yaml

_format_version: "1"

provider_keys:
  - display_name: "cerebras-prod"
    provider: "cerebras"
    adapter: "openai"
    api_key: ${CEREBRAS_API_KEY}
    api_base: "https://api.cerebras.ai/v1"

models:
  - display_name: "cerebras-gptoss-prod"
    provider: "cerebras"
    model_name: "gpt-oss-120b"
    provider_key: "cerebras-prod"

api_keys:
  - display_name: "cerebras-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "cerebras-gptoss-prod"

If AISIX is installed locally, validate the file before loading it:

aisix validate --resources resources.yaml

After validation, start the gateway with the referenced environment variables in its process environment. Reload an existing gateway only if those variables are already available to the process; otherwise, restart it with the updated environment.

If you use Docker, adapt the validation and startup commands in the Open-Source AISIX Gateway Quickstart. Mount this resources.yaml file and pass every environment variable it references with -e in both commands. After the resources load, prepare the shared verification request below:

export AISIX_API_KEY="$CALLER_API_KEY"

Verify the Provider Connection

Export the AISIX gateway origin:

# AISIX_PROXY has no trailing slash or endpoint path
# The local quickstarts use http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"

Send a chat-completions request through the AISIX proxy:

curl -sS -X POST "$AISIX_PROXY/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. OpenAI-specific Responses fields without a chat equivalent are ignored.
/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/*	Available through a configured passthrough route claiming this prefix with the https://api.cerebras.ai/v1 root as its target_url; grant the route on the caller key's allowed_routes. Provider-native paths relay with limited gateway normalization.

Next Steps

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

• Model Aliases: configure routing, retry behavior, or cost metadata 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.