本文介绍网易云信大模型 API（以下简称 AIHub） 与智谱 GLM 兼容的对话生成接口的使用说明。

云信 AIHub 使用 zhipu provider 接入智谱 GLM 的 OpenAI Chat Completions 与 Anthropic Messages 的同协议原生能力。您只需使用网易云信的 logical model，并改用云信下发的 API Key 即可无缝接入。

请求说明

协议	路径	示例
Chat Completions	POST /v1/chat/completions	POST https://ai.yunxinapi.com/hub/v1/chat/completions
Anthropic Messages	POST /v1/messages	POST https://ai.yunxinapi.com/hub/v1/messages

请求参数

Header 参数

参数	协议/位置	必填	说明	示例
Authorization	OpenAI/Responses/Anthropic 可选 Header	必填或可选	AIHub API Key Bearer 鉴权；统一 HTTP 客户端推荐使用。	Bearer <AIHUB_API_KEY>
x-api-key	Anthropic Messages Header	Anthropic SDK 常用	AIHub API Key，Anthropic SDK 形态。	<AIHUB_API_KEY>
Content-Type	Header	必填	请求体类型。	application/json

Body 参数

OpenAI Chat Completions 参数

适用入口：POST https://ai.yunxinapi.com/hub/v1/chat/completions。以下参数表格直接合并 OpenAI-compatible Chat 参数；厂商私有差异请参见下文的 厂商扩展参数。

参数	类型/位置	必填	说明	示例
model	string，body 顶层	必填	AIHub logical model。AIHub 会按 API Key、模型授权、operation 和路由配置解析为上游模型；可见模型不等于支持所有字段。	"glm-5-turbo"
messages	array，body 顶层	必填	按时间顺序排列的对话历史。普通对话至少包含一条 user 消息；工具调用场景必须保留 assistant tool_calls 和后续 tool 结果。	[{"role":"user","content":"你好"}]
messages[].role	string	必填	消息角色。常见为 developer、system、user、assistant、tool；具体角色支持取决于目标模型。	"user"
messages[].content	string、content part[] 或 null	通常必填	消息正文。文本可直接传 string；多模态、文件、音频等输入使用 content part 数组；assistant 只有工具调用时可为空。	"总结这段文本"
messages[].name	string	可选	发言者名称，只作为提示上下文，不是鉴权身份，也不能替代 role。部分上游会忽略。	"product_manager"
messages[].tool_calls	array	条件必填	assistant 发起的工具调用历史。续接工具闭环时必须原样保存 id、函数名和参数。	[{"id":"call_1","type":"function","function":{"name":"search","arguments":"{}"}}]
messages[].tool_call_id	string	条件必填	role: "tool" 消息关联的工具调用 ID，必须匹配前一轮 assistant tool_calls[].id。	"call_1"
messages[].reasoning_content	string	厂商条件字段	Qwen、Kimi、DeepSeek、GLM 等推理模型的历史推理字段。只有目标厂商要求保留时才原样回传，不要拼入 content。	"上一轮推理内容"
messages[].partial	boolean	厂商条件字段	Kimi Partial Mode 预填标识，通常只放在最后一条 assistant 消息。不是 OpenAI 标准字段。	true
messages[].content[].type	string	content part 必填	content part 类型，例如 text、image_url、input_audio、file。必须与同一对象里的字段匹配。	"text"
messages[].content[].text	string	文本 part 必填	文本内容，承载用户可见自然语言、代码或结构化文本；不要混入历史推理字段。	"识别图片里的文字"
messages[].content[].image_url	object	图片 part 必填	图像输入配置，通常包含 url 和可选 detail；URL、data URL、格式和大小由目标模型决定。	{"url":"https://example.com/a.png","detail":"high"}
messages[].content[].input_audio	object	音频 part 必填	音频输入配置，通常包含 base64 data 和 format；仅向支持音频输入的模型发送。	{"data":"BASE64","format":"wav"}
messages[].content[].file	object	文件 part 必填	文件输入，可传上游文件 ID、内联文件数据或文件名。AIHub 不转换跨厂商文件 ID。	{"file_id":"file_abc"}
temperature	number，body 顶层	可选	采样随机度。值越低越稳定，值越高越发散；通常不要和 top_p 同时大幅调节。	0.2
top_p	number，body 顶层	可选	nucleus sampling 阈值，从累计概率覆盖该阈值的候选 token 中采样。	0.9
max_completion_tokens	integer，body 顶层	可选	最大 completion token 数。推理模型通常同时消耗可见输出和推理 token；新请求优先使用该字段。	1024
max_tokens	integer，body 顶层	可选，旧字段	旧式输出 token 上限。部分新模型要求使用 max_completion_tokens，不要让两个字段表达冲突上限。	1024
stop	string 或 string[]	可选	停止序列。模型生成到匹配文本时停止，通常不会输出停止序列本身。	["END"]
n	integer	可选	候选回复数量。每个候选都会计费；工具调用和多数跨协议场景建议保持 1。	1
seed	integer	可选	随机种子，用于尽量提高可复现性，不保证绝对确定。	1234
presence_penalty	number	可选	鼓励引入新概念或主题，适合降低重复话题，不替代格式校验。	0.1
frequency_penalty	number	可选	降低高频 token 重复，过高可能伤害术语、代码和固定格式。	0.2
logit_bias	object	可选	按 token ID 调整采样概率。tokenizer 强相关，不保证跨模型复用，也不做跨协议转换。	{"50256":-100}
logprobs	boolean	可选	是否返回输出 token 对数概率。会增大响应体，且并非所有模型支持。	true
top_logprobs	integer	条件可选	仅 logprobs: true 时有效，返回每个位置的候选 token 概率数量。	5
response_format	object	可选	结构化输出控制，可请求文本、JSON object 或 JSON Schema；服务端仍需解析和校验。	{"type":"json_object"}
response_format.type	string	可选	常见值为 text、json_object、json_schema；可用值以模型和厂商为准。	"json_schema"
response_format.json_schema	object	json_schema 条件必填	JSON Schema 输出定义，通常包含 name、description、schema 和可选 strict。	{"name":"todo","schema":{"type":"object"},"strict":true}
tools	array	可选	可供模型调用的工具定义。AIHub 稳定公共子集是 OpenAI 风格 function 工具。	[{"type":"function","function":{"name":"lookup","parameters":{"type":"object"}}}]
tools[].type	string	工具项必填	工具类型。公共 function calling 使用 function；其他厂商工具只在同协议原生入口使用。	"function"
tools[].function.name	string	function 必填	函数名，应与业务工具注册表一致，并在工具闭环中保持稳定。	"get_weather"
tools[].function.description	string	建议填写	说明何时调用、参数含义和副作用。描述越清楚，模型越不容易误调。	"查询城市天气"
tools[].function.parameters	JSON Schema object	建议填写	函数参数 schema。模型输出仍不可信，服务端必须校验、鉴权和限流。	{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}
tools[].function.strict	boolean	可选	请求严格按 schema 输出工具参数。开启后 schema 必须满足目标模型支持的子集。	true
tool_choice	string 或 object	可选	控制模型是否、以及如何选择工具。常见为 none、auto、required 或指定 function。	{"type":"function","function":{"name":"get_weather"}}
parallel_tool_calls	boolean	可选	是否允许并行工具调用。设置为 false 可降低编排复杂度，但不替代服务端幂等控制。	false
stream	boolean	可选	true 时返回 SSE 增量事件；流式只改变传输模式，不改变采样和工具语义。	true
stream_options.include_usage	boolean	条件可选	流式最后请求附带 usage 汇总；中途断流时最终 usage 可能收不到。	{"include_usage":true}
modalities	string[]	可选	请求输出模态，例如文本或音频。启用音频时还需提供 audio，且模型必须支持。	["text"]
audio	object	条件必填	音频输出配置。只有输出模态包含音频时使用，字段由模型支持矩阵决定。	{"format":"wav","voice":"alloy"}
audio.format	string	条件必填	请求的音频编码或封装格式。	"wav"
audio.voice	string	条件必填	音色或语音名称，受模型和账号授权限制。	"alloy"
prediction	object	可选	预测型输出优化候选内容，适合大部分输出可提前预知的编辑场景。	{"type":"content","content":"固定前缀"}
reasoning_effort	string	可选	推理强度提示。枚举、计费和是否生效由厂商与模型决定。	"high"
service_tier	string	可选	上游服务档位或延迟优先级。是否可用由账号、渠道和模型决定。	"standard"
prompt_cache_key	string	可选	提示缓存分组键或会话亲和提示。不要放密钥或敏感正文。	"session_42"
safety_identifier	string	可选	匿名稳定用户标识，用于安全追踪和滥用识别，避免传 PII。	"user_hash_abc123"
store	boolean	可选	请求上游存储响应或用于其平台功能。AIHub 不以此替代自身审计和日志策略。	false
metadata	object	可选	业务元数据，应短小且非敏感。metadata.aihub_* 为 AIHub 保留并会被剥离。	{"trace_id":"req_123"}
user	string	可选，旧兼容字段	终端用户匿名标识，供部分上游做安全监测。新接入优先用厂商推荐字段。	"user_123"
functions	array	可选，已弃用	旧版 function calling 定义。新请求应使用 tools。	[{"name":"lookup","parameters":{"type":"object"}}]
function_call	string 或 object	可选，已弃用	旧版函数选择控制。新请求应使用 tool_choice。	"auto"
web_search_options	object	可选，兼容字段	个别 OpenAI-compatible 上游的旧式联网搜索配置，不是跨厂商统一能力。	{"search_context_size":"medium"}

Anthropic Messages 参数

适用入口：POST https://ai.yunxinapi.com/hub/v1/messages。使用 Anthropic SDK 时保留 x-api-key Header 形态。

参数	类型/位置	必填	说明	示例
model	string，body 顶层	必填	AIHub logical model。必须对当前 API Key 可见，并在 Messages operation 上有可用路由。	"glm-5-turbo"
max_tokens	integer，body 顶层	必填	本次最多生成的输出 token。thinking、工具输入和多模态输出可能影响实际 token 使用。	1024
messages	array，body 顶层	必填	用户与 assistant 的对话消息。系统指令不放在数组内，使用 system。	[{"role":"user","content":"你好"}]
messages[].role	string	必填	常用 user 或 assistant。跨协议转换时 system/developer 重排风险较高，应优先同协议调用。	"user"
messages[].content	string 或 content block[]	必填	消息正文。简单文本用 string；图像、文档、工具、thinking 或缓存标记使用 block 数组。	[{"type":"text","text":"解释一下"}]
system	string 或 content block[]	可选	系统提示词，独立于 messages。使用缓存时通常把 cache_control 放在 system text block 上。	"以简洁中文回答"
content[].type	string	block 必填	内容块类型，如 text、image、document、thinking、tool_use、tool_result。	"text"
content[].text	string	text block 必填	文本内容。可附带 citations 或 cache_control，具体由厂商支持度决定。	"请总结"
content[].image.source	object	image block 必填	图像来源，可为 base64、URL 或上游文件资源，具体字段取决于厂商。	{"type":"base64","media_type":"image/png","data":"BASE64"}
content[].document.source	object	document block 必填	文档来源。AIHub 不转换任一厂商文件资源 ID 或文档引用。	{"type":"base64","media_type":"application/pdf","data":"BASE64"}
content[].thinking	string	thinking block 条件字段	模型输出的思考 block。多轮时仅在目标厂商要求时原样回带，不要修改或拼入 text。	"上一轮 thinking"
content[].signature	string	thinking block 条件字段	思考签名。续接时需要原样保留，不能伪造、截断或改写。	"sig_abc"
content[].tool_use.id	string	tool_use 必填	assistant 请求调用工具的 ID，后续 tool_result.tool_use_id 必须匹配。	"toolu_1"
content[].tool_use.name	string	tool_use 必填	客户端工具名称，必须与业务工具注册表一致。	"get_weather"
content[].tool_use.input	object	tool_use 必填	模型生成的工具输入。执行前必须做 schema、权限、限流和幂等校验。	{"city":"杭州"}
content[].tool_result.tool_use_id	string	tool_result 必填	工具结果关联 ID，必须匹配已有 tool_use.id。	"toolu_1"
content[].tool_result.content	string 或 block[]	tool_result 必填	工具执行结果。失败时用 is_error，避免暴露凭证或内部堆栈。	"杭州 28 摄氏度"
content[].tool_result.is_error	boolean	可选	标记工具结果是否为错误。	false
source.type	string	source 必填	资源来源类别，例如 base64、URL 或上游文件资源。	"base64"
source.media_type	string	base64 条件字段	MIME 类型，必须与真实数据一致。	"image/png"
source.data	string	base64 条件字段	base64 编码数据，注意请求大小、重试成本和日志脱敏。	"BASE64"
source.url	string	URL 条件字段	上游可访问 URL。调用方要保证权限、有效期和可达性。	"https://example.com/file.pdf"
temperature	number	可选	采样随机度。不同模型可能限制范围、固定采样或拒绝组合参数。	0.2
top_p	number	可选	nucleus sampling 阈值。通常与 temperature 二选一调节。	0.9
top_k	integer	可选	每步采样考虑的候选 token 数。不是所有模型支持。	40
stop_sequences	string[]	可选	停止序列数组。应避免前缀歧义。	["END"]
thinking	object	可选	扩展思考配置。支持度、预算范围和是否能关闭由厂商模型决定。	{"type":"enabled","budget_tokens":1024}
thinking.type	string	thinking 条件字段	思考模式类型，可用枚举因厂商和模型不同而不同。	"enabled"
thinking.budget_tokens	integer	可选	分配给思考的 token 预算。DeepSeek Messages 可能忽略，详见厂商差异。	1024
tools	array	可选	客户端 function tool 或厂商服务器工具定义；高级工具只在原生支持时使用。	[{"name":"get_weather","input_schema":{"type":"object"}}]
tools[].name	string	客户端 tool 必填	工具稳定名称，必须与业务工具注册表一致。	"get_weather"
tools[].description	string	建议填写	说明何时调用、输入语义、输出形式和副作用。	"查询城市天气"
tools[].input_schema	JSON Schema object	客户端 tool 必填	工具输入 schema。模型输出仍需服务端校验、鉴权和限流。	{"type":"object","properties":{"city":{"type":"string"}}}
tools[].cache_control	object	可选	工具定义参与提示缓存时的缓存控制。位置和 TTL 语义由上游决定。	{"type":"ephemeral"}
tools[].type	string	server tool 条件字段	上游服务器工具或高级工具类型。只在目标厂商原生 Messages 路由使用。	"web_search_20250305"
tool_choice	object	可选	指定工具选择行为，例如自动、任意工具、指定工具或禁用并行工具。	{"type":"auto","disable_parallel_tool_use":true}
tool_choice.type	string	tool_choice 条件字段	工具选择类型，枚举由目标模型决定。	"auto"
tool_choice.name	string	指定工具条件字段	指定某个客户端工具时使用，必须匹配 tools[].name。	"get_weather"
output_config	object	可选	输出行为配置，例如结构化输出或推理强度。不是所有兼容厂商都实现。	{"format":{"type":"json_schema"}}
output_config.format	object	可选	结构化输出格式，模型生成后仍需服务端验证。	{"type":"json_schema","schema":{"type":"object"}}
output_config.effort	string	可选	部分 Anthropic-compatible 厂商用于表达推理力度。	"high"
metadata	object	可选	调用元数据，应非敏感。metadata.aihub_* 为 AIHub 保留并剥离。	{"user_id":"user_hash_abc"}
metadata.user_id	string	可选	业务终端用户的匿名稳定标识，不要传 PII。	"user_hash_abc"
stream	boolean	可选	true 时返回 Anthropic SSE 事件，如 message_start、content_block_delta 和 message_stop。	true
service_tier	string	可选	上游服务档位。是否可用由账号、区域、模型和厂商决定。	"standard"
container	string 或 object	可选	上游容器资源标识或配置，不是跨厂商资源。	"container_abc"
context_management	object	可选	长会话上下文管理策略，使用前评估截断或清理工具历史的业务影响。	{"edits":[{"type":"clear_tool_uses_20250919"}]}
mcp_servers	array	可选	远程 MCP server 声明，需要额外审计授权、网络出口和工具权限。	[{"name":"crm","url":"https://mcp.example.com"}]
mcp_servers[].authorization_token	string	可选	远程 MCP 授权 token。不要写进普通提示或长期日志。	"Bearer token"
cache_control.type	string	缓存 block 条件字段	缓存策略类型，例如上游规定的 ephemeral 策略。只能用于允许位置。	"ephemeral"
cache_control.ttl	string	可选	缓存生命周期提示。支持值、最大缓存点和计费由上游决定。	"1h"

GLM Chat 同协议原生调用会执行兼容性规范化：top_p >= 1 改为 0.99；max_completion_tokens 映射为 max_tokens；字符串 stop 规范化为单元素数组。GLM 私有字段应优先走 Chat Completions 同协议原生入口。

GLM 厂商扩展参数

智谱官方 OpenAPI 描述该接口支持文本、图片、音频、视频、文件，多模型，流式和非流式输出，采样、最大 token 和工具调用。

参数	类型/位置	必填	说明	示例
thinking	object，body 顶层	可选	控制 GLM 是否开启思维链。官方 schema 说明 GLM-4.5 及以上模型支持。	{"type":"disabled"}
thinking.type	string	条件字段	常见值为 enabled/disabled，是否返回 reasoning_content 由模型决定。	"enabled"
thinking.clear_thinking/clear_thinking	boolean	可选	控制跨轮历史 thinking blocks。true 清理历史推理，false 保留。	false
messages[].reasoning_content	string	条件字段	GLM-4.5、GLM-4.1v-thinking 等模型返回的思维链内容，多轮时原样回传。	"上一轮推理"
reasoning_effort	string，body 顶层	可选	推理强度。智谱原生是否支持和取值随模型变化。	"high"
stream	boolean，body 顶层	可选	是否流式输出；工具参数和 reasoning 可能分片。	true
temperature	number，body 顶层	可选	采样温度。若关闭采样，模型会忽略 temperature 和 top_p。	0.2
top_p	number，body 顶层	可选	nucleus sampling，官方常见范围 [0.01, 1]；AIHub 会把 top_p >= 1 规范化为 0.99。	0.8
max_tokens	integer，body 顶层	可选	输出 token 上限。官方按模型系列给出不同最大输出长度，建议至少 1024。	2048
tool_stream	boolean，body 顶层	可选	GLM 工具参数流式输出。复杂参数可设为 true 降低等待超时风险。	true
tools	array，body 顶层	可选	支持函数调用、知识库检索和网络搜索；function tools 最多数量以原厂为准。	[{"type":"function","function":{"name":"lookup"}}]
tool_choice	string 或 object	可选	控制模型选择工具的方式，视觉模型部分场景仅支持 auto。	"auto"
response_format	object，body 顶层	可选	结构化输出配置，服务端仍需重新校验。	{"type":"json_object"}
content[].image_url.url	string	多模态条件字段	图片输入。URL/data URL 支持度由目标模型决定。	"https://example.com/a.png"
content[].video_url.url	string	多模态条件字段	视频输入。部分模型要求 video_url 位于 content 数组第一位。	"https://example.com/a.mp4"
content[].file_url.url	string	多模态条件字段	文件输入。不要混用不兼容的文件、图片和视频组合。	"https://example.com/a.pdf"
content[].input_audio	object	多模态条件字段	音频输入，data 通常为 base64，format 描述音频格式。	{"data":"BASE64","format":"wav"}

请求示例

json{
  "model": "glm-5-turbo",
  "messages": [
    {
      "role": "user",
      "content": "根据资料生成结构化行动项。"
    }
  ],
  "thinking": {
    "type": "disabled"
  },
  "tool_stream": true,
  "response_format": {
    "type": "json_object"
  }
}

需要 GLM 私有字段时，使用 /v1/chat/completions 或 /v1/messages，不要依赖 /v1/responses 的跨协议转换。

响应示例

以下为 Chat Completions 的典型非流式成功响应。当前请求关闭 thinking，因此示例只展示最终 content；开启 thinking 的模型可能另外返回 reasoning_content。

json{
  "id": "chatcmpl-aihub-glm-example",
  "object": "chat.completion",
  "created": 1786406400,
  "model": "glm-5-turbo",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "{\"action_items\":[{\"task\":\"确认需求范围\",\"priority\":\"high\"},{\"task\":\"补齐验收证据\",\"priority\":\"medium\"}]}"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 52,
    "total_tokens": 80
  }
}

工具调用时 message.tool_calls、finish_reason 和流式增量字段会随 GLM 模型能力变化；执行任何工具前仍需校验参数、权限和幂等性。

{"object":"list","data":[{"id":"glm-4.6v","object":"model","created":0,"owned_by":"aihub"},{"id":"glm-4.7","object":"model","created":0,"owned_by":"aihub"},{"id":"glm-5","object":"model","created":0,"owned_by":"aihub"},{"id":"glm-5-turbo","object":"model","created":0,"owned_by":"aihub"},{"id":"glm-5.1","object":"model","created":0,"owned_by":"aihub"},{"id":"glm-5.2","object":"model","created":0,"owned_by":"aihub"},{"id":"glm-x-preview","object":"model","created":0,"owned_by":"aihub"}]}