Skip to main content
API7.ai Logo

Zhipu AI (GLM)

Zhipu AI provides GLM language models and CogVideoX video generation through hosted APIs. Applications use AISIX caller keys and model aliases for both capabilities while the gateway holds the upstream credential.

This guide covers both GLM chat traffic and CogVideoX video tasks through a single Zhipu AI provider key.

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 Zhipu AI API key from the Zhipu AI open platform.
  • 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 GLM-backed chat-completions route.

Because Zhipu AI exposes an OpenAI-compatible API, AISIX connects through the openai adapter and uses the Zhipu AI API root as api_base. The same provider key can also serve the gateway's video-generation 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 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 Zhipu AI API key and is sent as a bearer token on upstream calls. It follows the credential-handling behavior in Provider Keys.

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

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.

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 ZHIPU_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

Create a complete declarative resources file for this provider:

resources.yaml
_format_version: "1"

provider_keys:
  - display_name: "zhipuai-prod"
    provider: "zhipuai"
    adapter: "openai"
    api_key: ${ZHIPU_API_KEY}
    api_base: "https://open.bigmodel.cn/api/paas/v4"

models:
  - display_name: "glm-flagship-prod"
    provider: "zhipuai"
    model_name: "glm-5.2"
    provider_key: "zhipuai-prod"

api_keys:
  - display_name: "zhipuai-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "glm-flagship-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:

# The local quickstarts use http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"

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": "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. GLM-5.2 also accepts reasoning_effort to control the reasoning depth while thinking is enabled. See Deep Thinking for the current model-specific behavior and accepted effort values.

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:

In AISIX Cloud, create the video alias and a caller key scoped to it:

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"

VIDEO_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-video-caller",
    "allowed_models": ["'"${VIDEO_MODEL_ID}"'"]
  }' | jq -r '.plaintext')

For the open-source AISIX gateway, add the video model to the existing models collection and allow the existing caller key to use both aliases:

resources.yaml
models:
  - display_name: "glm-flagship-prod"
    provider: "zhipuai"
    model_name: "glm-5.2"
    provider_key: "zhipuai-prod"
  - display_name: "glm-video-prod"
    provider: "zhipuai"
    model_name: "cogvideox-3"
    provider_key: "zhipuai-prod"

api_keys:
  - display_name: "zhipuai-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "glm-flagship-prod"
      - "glm-video-prod"

Validate and reload or restart the declarative resources file as described above, then use the existing caller key for the video request:

export VIDEO_API_KEY="$CALLER_API_KEY"

Submit a task:

curl -sS -X POST "$AISIX_PROXY/v1/videos" \
  -H "Authorization: Bearer ${VIDEO_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"
  }'

Five 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.
  • Provider-native video fields require a passthrough route. The normalized request models only prompt, seconds, and size; extra fields are ignored. To send CogVideoX fields such as image_url, quality, with_audio, or fps, call /passthrough/zhipuai/videos/generations with the native body and exact model ID. Poll the task at /passthrough/zhipuai/async-result/{id}. Passthrough does not return the unified AISIX video object or gateway-encoded task ID. The /passthrough/zhipuai paths on this page assume a passthrough route claiming that prefix with the provider's API root as its target_url; grant the route name on the caller key's allowed_routes.
  • 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 fields the chat adapter path can express. OpenAI-specific Responses fields without a chat equivalent are ignored.
/v1/messagesSupported through AISIX translation to chat completions. /v1/messages/count_tokens is not supported because the model is not Anthropic-backed. Zhipu AI also publishes a Claude-compatible API on a different API root; the provider key configured in this guide does not target that interface.
/v1/videos and its status and content routesSupported. See Generate Videos with CogVideoX.
/v1/images/generationsNot supported through the normalized route because it accepts only models whose configured provider is openai. Use /passthrough/zhipuai/images/generations with the native body and exact image model ID.
/v1/audio/transcriptionsSupported when the alias names a Zhipu AI speech-to-text model, such as glm-asr-2512. The upstream path and multipart request shape match the AISIX route. A provider streaming response is buffered before AISIX returns it.
/v1/audio/speechSupported when the alias names glm-tts. Non-streaming audio is returned verbatim. AISIX buffers the provider response when the native stream field is enabled.
/v1/audio/translationsNot supported because Zhipu AI does not publish the corresponding upstream route.
/v1/realtimeAvailable as a WebSocket relay for a direct GLM-Realtime alias. AISIX dials wss://open.bigmodel.cn/api/paas/v4/realtime with the configured upstream model in the query and relays events without translation. If the client also sets session.model, send the exact Zhipu AI model ID because AISIX does not rewrite WebSocket frame bodies.
/v1/rerankNot supported through the normalized route because it accepts only the openai, cohere, and jina provider values. Use /passthrough/zhipuai/rerank with the native body and exact rerank model ID.
/v1/modelsReturns caller-accessible AISIX aliases, not the Zhipu AI catalog. Consult the model overview linked above for provider model IDs.
/passthrough/zhipuai/*restAvailable through a configured passthrough route for provider-native HTTP routes. Passthrough does not rewrite AISIX aliases and relays SSE incrementally. Recognized chat, completions, and Responses envelopes record supported usage fields. Requests without a recognized carrier field remain opaque: buffered responses record zero tokens, while opaque SSE can still record top-level supported usage fields.

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: