Zhipu AI (GLM)

Zhipu AI 通过托管 API 提供 GLM 语言模型和 CogVideoX 视频生成能力。应用使用 AISIX 调用方密钥和模型别名访问这两项能力，上游凭证则由网关保存。

本指南介绍如何通过一个 Zhipu AI 服务提供方密钥处理 GLM Chat 流量和 CogVideoX 视频任务。

准备工作

开始前，请准备以下内容：

• 一套 AISIX 环境：
  • 对于 AISIX Cloud，需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
  • 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 环境。配置网关以加载声明式资源文件。
• 从智谱 AI 开放平台获取的 Zhipu AI API Key。
• curl 和 jq。

使用 AISIX Cloud 配置

导出 AISIX Cloud 连接信息：

# AISIX_CP 是 Admin API 基础 URL；应包含 /api，且不含尾部斜杠
# 本地私有化部署快速入门使用 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"

为由 GLM 支持的 Chat Completions 路由创建服务提供方密钥、模型别名和调用方 API Key。

由于 Zhipu AI 提供 OpenAI 兼容 API，AISIX 会通过 openai 适配器进行连接，并使用 Zhipu AI API 根地址作为 api_base。同一个服务提供方密钥也可用于网关的视频生成路由。

创建服务提供方密钥

创建用于存储 Zhipu AI 凭证和 API 根地址的服务提供方密钥：

# 请替换为实际值
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 为 zhipuai，即智谱 AI 开放平台的目录服务提供方 ID。AISIX Cloud Admin API 会从目录服务提供方派生适配器；adapter 字段仅在 BYO 服务提供方密钥上被接受。

❷ api_key 存储 Zhipu AI API Key，并在上游调用中作为 Bearer Token 发送。其行为遵循服务提供方密钥中的凭证处理方式。

❸ api_base 使用一种特殊的路径格式：版本路径段为 v4，位于 /api/paas 下，而不是大多数 OpenAI 兼容服务商使用的 /v1 根地址。AISIX 会将端点路径原样追加到 api_base，因此此值会生成 https://open.bigmodel.cn/api/paas/v4/chat/completions。对此服务提供方，该字段为可选字段；省略时，AISIX Cloud Admin API 会填入相同的规范值。当密钥指向其他 Zhipu AI 部署时，请显式设置该字段。

该命令会把返回的服务提供方密钥 ID 保存到 PROVIDER_KEY_ID。

Zhipu AI 运营两个使用不同目录服务提供方 ID 的平台。对于位于 open.bigmodel.cn 的中国大陆平台，请使用 zhipuai；对于 API 根地址为 https://api.z.ai/api/paas/v4 的国际 Z.ai 平台，请使用 zai。这两个 ID 不能互换。已建模的视频路由只会分发 zhipuai（以及简写 zhipu），因此 zai 服务提供方密钥可以处理 Chat 流量，但在 /v1/videos 上会返回未实现错误。

与部分其他 OpenAI 兼容目录条目不同，zhipuai 条目不需要请求或响应覆盖项。Zhipu AI 接受标准字段名称，并且已经在规范字段上返回推理文本，因此 AISIX 会原样发送 OpenAI 请求格式，不会重命名任何参数。请参阅控制思考模式。

创建模型

Zhipu AI 模型 ID 遵循 glm-<version> 格式。glm-5.2 等不带后缀的版本表示该代旗舰文本模型；-flash、-flashx 或 -air 后缀表示更轻量、更经济的服务级别；末尾的 v（例如 glm-5v-turbo）表示视觉模型。创建模型别名前，请在 Zhipu AI 模型概览中确认当前目录。

创建调用方将在请求中发送的模型别名：

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 是调用方在 model 中发送的别名。

❷ model_name 是 Zhipu AI 模型 ID，例如 glm-5.2、glm-5 或 glm-4.7。

❸ provider_key_id 将别名关联到 Zhipu AI 服务提供方密钥。

创建调用方 API Key

创建可访问该模型别名的调用方 API Key。明文密钥由服务器生成，并且只在响应中返回一次，因此请立即保存：

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"

allowed_models 值必须引用上一步保存的模型 ID，使该密钥只能访问已创建的别名。写入后，配置会自动投射到已关联的网关。

使用开源 AISIX 网关配置

导出上游凭证，并选择应用将发送给网关的调用方 API Key：

export ZHIPU_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

对于新网关，请使用这份完整的资源文件。对于现有网关，请将这些条目合并到其当前文件中，并保留其他资源：

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"

如果 AISIX 安装在本地，请在加载前验证文件：

aisix validate --resources resources.yaml

验证后，在网关进程环境中提供文件引用的环境变量，再启动网关。仅当这些变量已经可供进程使用时，才重新加载现有网关；否则，请使用更新后的环境重启网关。

如果使用 Docker，请调整开源 AISIX 网关快速入门中的验证和启动命令。挂载此 resources.yaml 文件，并在两条命令中使用 -e 传入它引用的每个环境变量。资源加载后，准备下文共用的验证请求：

export AISIX_API_KEY="$CALLER_API_KEY"

验证服务提供方连接

导出 AISIX 网关 Origin：

# AISIX_PROXY 不含尾部斜杠或端点路径
# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"

通过 AISIX 代理发送 Chat Completions 请求：

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."
      }
    ]
  }'

网关会返回 OpenAI 兼容响应，其中回显面向调用方的别名 glm-flagship-prod。由于模型默认进行推理，助手消息除了 content 外还会携带 reasoning_content 字段。如果请求失败，请检查服务提供方密钥的 api_key、api_base，以及 model_name 中的 Zhipu AI 模型 ID。

控制思考模式

GLM 推理模型默认启用思考。如需对单个请求关闭思考，请在 Chat Completions 请求体中添加服务提供方的 thinking 对象：

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

AISIX 会将其本身不解析的字段原样转发到上游，因此该控制项会按写入内容到达 Zhipu AI。可接受的值为 enabled 和 disabled。GLM-5.2 还支持在思考开启时通过 reasoning_effort 控制推理深度。当前各模型的行为和可接受的强度值请参阅深度思考。

Zhipu AI 在 reasoning_content 上返回思考文本：非流式响应使用 message.reasoning_content，流式响应使用 delta.reasoning_content。这是 AISIX 保留的规范字段，因此该服务提供方不需要在服务提供方密钥上设置 response.reasoning_field 覆盖项。

使用 CogVideoX 生成视频

同一个服务提供方密钥可驱动网关的已建模视频路由。请创建第二个别名，指向 Zhipu AI 视频模型，例如 CogVideoX-3：

在 AISIX Cloud 中，创建视频别名和仅限该别名的调用方密钥：

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')

对于开源 AISIX 网关，请将 glm-video-prod 添加到现有 models 集合。将现有 zhipuai-caller 条目替换为下面更新后的条目，使其允许两个模型别名。保留无关条目和集合：

resources.yaml（视频模型访问）

models:
  - 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"

按照上文说明验证并重新加载或重启声明式资源文件，然后使用现有调用方密钥发送视频请求：

export VIDEO_API_KEY="$CALLER_API_KEY"

提交任务：

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"
  }'

在为此路由编写脚本前，需要了解以下五项服务提供方特定行为：

• Chat 的 api_base 会原样复用。 AISIX 会识别 /api/paas/v4 后缀，从中派生服务商根地址，并在其下组成服务提供方的原生任务路径。已经为 GLM Chat 流量配置的服务提供方密钥无需更改即可用于视频路由。
• 参数直接映射。 seconds 会作为服务提供方的整数 duration 转发，size 则会原样传递，因为 Zhipu AI 文档使用的 WIDTHxHEIGHT 写法与统一请求相同。AISIX 会在联系服务提供方前验证格式。
• 服务提供方原生视频字段需要透传路由。 标准化请求只建模 prompt、seconds 和 size；其他字段会被忽略。若要发送 image_url、quality、with_audio 或 fps 等 CogVideoX 字段，请通过 /passthrough/zhipuai/videos/generations 发送原生正文和准确的模型 ID，并通过 /passthrough/zhipuai/async-result/{id} 轮询任务。透传不会返回统一的 AISIX 视频对象或网关编码的任务 ID。本页的 /passthrough/zhipuai 路径假定一条透传路由认领该前缀，target_url 设为该服务提供方的 API 根地址；在调用方 Key 的 allowed_routes 上授予路由名称。
• 不存在排队状态。 Zhipu AI 从接受任务起就将其报告为处理中，因此统一状态会直接变为 in_progress，永远不会报告 queued。请轮询 GET /v1/videos/{id}，直到其报告 completed。
• 已完成的视频通过重定向交付。 GET /v1/videos/{id}/content 返回 302，并在 Location 请求头中提供指向服务提供方签名下载 URL 的地址。字节数据会从 Zhipu AI 存储直接传输到客户端，不会经过网关，因此下载时请使用 curl -L。

完整的提交、轮询和下载工作流（包括状态语义和轮询时的限流行为）请参阅视频生成。

端点覆盖范围

Zhipu AI 服务提供方密钥会解析到 openai 适配器，因此路由支持情况取决于该适配器以及各路由自身的服务提供方规则：

路由	使用 zhipuai 模型别名时的行为
/v1/chat/completions	支持非流式和流式传输。
/v1/embeddings	当别名指向 Zhipu AI Embedding 模型（例如 embedding-3）时支持。AISIX 会将 /embeddings 追加到 api_base，到达服务提供方的文本 Embedding 端点。
/v1/responses	对于 Chat 适配器路径可以表达的字段，通过 Responses 桥接提供支持。没有对应 Chat 语义的 OpenAI Responses 专用字段会被忽略。
/v1/messages	默认转换到 Chat Completions。Zhipu AI 还在 https://open.bigmodel.cn/api/anthropic 提供 Claude 兼容 Messages API，但其文档没有定义 AISIX 与 apis.messages 绑定的 Token 计数路由。原生 Messages 请使用经过身份认证的透传路由，不要声明 apis.messages，否则 /v1/messages/count_tokens 也会被路由到上游。
/v1/videos 及其状态和内容路由	支持。请参阅使用 CogVideoX 生成视频。
/v1/images/generations	标准化路由不受支持，因为它只接受配置的服务提供方为 openai 的模型。请通过 /passthrough/zhipuai/images/generations 发送原生正文和准确的图像模型 ID。
/v1/audio/transcriptions	当别名指向 glm-asr-2512 等 Zhipu AI 语音转文本模型时受支持。上游路径和 multipart 请求形态与 AISIX 路由一致。服务提供方的流式响应会先被缓冲，再由 AISIX 返回。
/v1/audio/speech	当别名指向 glm-tts 时受支持。非流式音频会原样返回；启用原生 stream 字段时，AISIX 会缓冲服务提供方响应。
/v1/audio/translations	不支持，因为 Zhipu AI 未提供对应的上游路由。
/v1/realtime	直接 GLM-Realtime 别名可以使用 WebSocket 中继。AISIX 会携带配置的上游模型作为查询参数连接 wss://open.bigmodel.cn/api/paas/v4/realtime，并在不转换事件的情况下进行中继。如果客户端还设置 session.model，请发送准确的 Zhipu AI 模型 ID，因为 AISIX 不会重写 WebSocket 帧正文。
/v1/rerank	标准化路由不受支持，因为它只接受 openai、cohere 和 jina 服务提供方值。请通过 /passthrough/zhipuai/rerank 发送原生正文和准确的 rerank 模型 ID。
/v1/models	返回调用方可访问的 AISIX 别名，而不是 Zhipu AI 目录。服务提供方模型 ID 请查阅上文链接的模型概述。
/passthrough/zhipuai/*rest	通过已配置的透传路由可用于服务提供方原生 HTTP 路由。透传不会重写 AISIX 别名，并会增量中继 SSE。哪些请求形态会记录 Token 用量，参见信封识别与用量。

完整端点和服务提供方矩阵请参阅服务提供方兼容性。

后续步骤

你已将 AISIX 连接到 Zhipu AI，并验证了模型别名。接下来可阅读以下指南：

• 模型别名：为此别名配置路由、重试行为或成本元数据。
• 路由与故障转移：在 Zhipu AI 和另一个服务提供方之间进行故障转移。
• 视频生成：按照完整的提交、轮询和下载工作流处理 CogVideoX 任务。
• 服务提供方兼容性：查看支持的代理端点和服务提供方特定边界。