Skip to main content
API7.ai Logo

Zhipu AI (GLM)

Connect AISIX AI Gateway to Zhipu AI so applications can call GLM models through the gateway's OpenAI-compatible API. AISIX keeps the Zhipu AI 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.

Zhipu AI exposes an OpenAI-compatible API, so it uses the openai adapter with a Zhipu AI api_base. It is also one of the few providers the gateway's modeled video-generation route can drive, so a single provider key serves both GLM chat traffic and CogVideoX video tasks.

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 Zhipu AI API key from the Zhipu AI open platform.

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 Zhipu AI Upstream​

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

Create a Provider Key​

Create the provider key that stores the Zhipu AI credential and API root:

# Replace with your value
export ZHIPU_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": "zhipuai-prod",
    "provider": "zhipuai",
    "api_key": "'"${ZHIPU_API_KEY}"'",
    "api_base": "https://open.bigmodel.cn/api/paas/v4",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -r '.provider_key.id')

echo "$PROVIDER_KEY_ID"

❶ provider is zhipuai, the catalog provider ID for the Zhipu AI open platform. 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 Zhipu AI API key and is sent as a bearer token on upstream calls. It follows the credential-handling behavior in Provider Credentials.

❸ api_base carries an unusual path shape: the version segment is v4 and lives under /api/paas, not the /v1 root that most OpenAI-compatible vendors publish. AISIX appends the endpoint path to api_base verbatim, so this value produces https://open.bigmodel.cn/api/paas/v4/chat/completions. The field is optional for this provider — when it is omitted, the Cloud Admin API fills in the same canonical value. Set it explicitly when you point the key at a different Zhipu AI deployment.

The command captures the returned provider key ID in PROVIDER_KEY_ID.

note

Zhipu AI operates two platforms with separate catalog provider IDs. Use zhipuai for the mainland China platform at open.bigmodel.cn, and zai for the international Z.ai platform, whose API root is https://api.z.ai/api/paas/v4. The two IDs are not interchangeable: only zhipuai (and the short spelling zhipu) is dispatched by the modeled video routes, so a zai provider key serves chat traffic but returns a not-implemented error on /v1/videos.

Unlike some other OpenAI-compatible catalog entries, the zhipuai entry needs no request or response overrides. AISIX sends the OpenAI request shape unchanged and does not rename any parameter, because Zhipu AI accepts the standard field names and already returns reasoning text on the canonical field. See Control Thinking Mode.

Create a Model​

Zhipu AI model IDs follow a glm-<version> pattern. A bare version such as glm-5.2 is the flagship text model for that generation; a -flash, -flashx, or -air suffix marks a lighter, cheaper lane; and a trailing v, as in glm-5v-turbo, marks a vision model. Check the Zhipu AI model overview for the current catalog before creating a model alias.

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": "glm-flagship-prod",
    "model_name": "glm-5.2",
    "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 Zhipu AI model ID, for example glm-5.2, glm-5, or glm-4.7.

❸ provider_key_id attaches the alias to the Zhipu AI 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 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": "zhipuai-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, so the key can only access the alias you created. 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": "glm-flagship-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from GLM."
      }
    ]
  }'

The gateway returns an OpenAI-compatible response that echoes the caller-facing alias glm-flagship-prod. Because the model reasons by default, the assistant message also carries a reasoning_content field alongside content. If the request fails, check the provider key api_key, api_base, and the Zhipu AI model ID in model_name.

Control Thinking Mode​

GLM reasoning models think by default. To turn thinking off for a single request, add the provider's thinking object to the chat-completions body:

{
  "thinking": {
    "type": "disabled"
  }
}

AISIX forwards fields it does not itself interpret to the upstream unchanged, so the control reaches Zhipu AI as written. Accepted values are enabled and disabled; see the GLM-5 model documentation for the per-model behavior.

Zhipu AI returns the thinking text on reasoning_content — message.reasoning_content for a buffered response and delta.reasoning_content for a streamed one. That is the canonical field AISIX preserves, so this provider needs no response.reasoning_field override on the provider key.

Generate Videos with CogVideoX​

The same provider key drives the gateway's modeled video routes. Create a second alias that points at a Zhipu AI video model, for example CogVideoX-3:

VIDEO_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": "glm-video-prod",
    "model_name": "cogvideox-3",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

echo "$VIDEO_MODEL_ID"

Add the new model ID to a caller API key's allowed_models, then submit a task:

curl -sS -X POST "http://127.0.0.1:3000/v1/videos" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-video-prod",
    "prompt": "A paper boat drifts down a rain-soaked street at dusk.",
    "seconds": 5,
    "size": "1920x1080"
  }'

Four provider-specific behaviors are worth knowing before you script around this route:

  • The chat api_base is reused as-is. AISIX recognizes the /api/paas/v4 suffix, derives the vendor root from it, and composes the provider's native task paths underneath. A provider key already configured for GLM chat traffic works on the video routes without change.
  • Parameters map directly. seconds is forwarded as the provider's integer duration, and size passes through verbatim, because Zhipu AI documents the same WIDTHxHEIGHT spelling the unified request uses. AISIX validates the shape before contacting the provider.
  • There is no queued state. Zhipu AI reports a task as processing from the moment it is accepted, so the unified status goes straight to in_progress and never reports queued. Poll GET /v1/videos/{id} until it reports completed.
  • Finished videos are delivered by redirect. GET /v1/videos/{id}/content returns 302 with a Location header pointing at the provider's signed download URL. The bytes travel from Zhipu AI storage to the client and do not pass through the gateway, so use curl -L when downloading.

For the full submit, poll, and download workflow, including status semantics and rate-limit behavior on polling, see Video Generation.

Endpoint Coverage​

A Zhipu AI provider key resolves the openai adapter, so route support follows that adapter plus each route's own provider rules:

RouteBehavior with a zhipuai model alias
/v1/chat/completionsSupported, buffered and streaming.
/v1/embeddingsSupported when the alias names a Zhipu AI embedding model, such as embedding-3. AISIX appends /embeddings to api_base, reaching the provider's text-embedding endpoint.
/v1/responsesSupported through the Responses bridge for request features the OpenAI adapter can express.
/v1/videos and its status and content routesSupported. See Generate Videos with CogVideoX.
/v1/images/generationsNot supported. This route accepts only models whose configured provider is openai.
/v1/rerankNot supported. This route accepts only the openai, cohere, and jina provider values.
/passthrough/zhipuai/*restSupported for provider-native APIs that AISIX has not modeled, with limited gateway normalization.

See Provider Compatibility for the full endpoint and provider matrix.

Next Steps​

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