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

云信 AIHub 使用 Moonshot provider 提供接入 Kimi 的 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 和路由配置解析为上游模型；可见模型不等于支持所有字段。	"kimi-k2.6"
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 上有可用路由。	"kimi-k2.6"
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"

Partial Mode 的用法是在 messages 末尾添加一条 role: "assistant" 的消息并设置 partial: true，模型会从该前缀继续生成。不要与 response_format: {"type":"json_object"} 混用；如需 JSON，优先使用 Structured Output。

Kimi 厂商扩展参数

参数	类型/位置	必填	说明	示例
logprobs	boolean，body 顶层	可选	是否在响应 message 的 logprobs 中返回输出 token 的对数概率。	true
top_logprobs	integer，body 顶层	条件可选	每个 token 位置返回的候选 token 数，范围以 Kimi 原厂为准。	5
prediction	object，body 顶层	可选	Predicted Output，适合大部分输出可提前预知的场景，可降低延迟。	{"type":"content","content":"已有文件内容"}
prediction.type	string	条件必填	当前 Kimi Chat 仅支持 content。	"content"
prediction.content	string 或 text part[]	条件必填	静态预测内容；数组元素仅使用 text 类型。	"固定前缀"
max_completion_tokens	integer，body 顶层	可选	最大生成 token 数。Kimi K3 默认和上限较高，仍受上下文限制。	2048
response_format	object，body 顶层	可选	输出格式控制，支持 text、json_object、json_schema。	{"type":"json_schema","json_schema":{"name":"todo","schema":{"type":"object"}}}
response_format.json_schema.name	string	json_schema 必填	结构化输出 schema 名称。	"todo"
response_format.json_schema.schema	object	json_schema 必填	Moonshot Flavored JSON Schema；复杂 schema 建议先自检。	{"type":"object","properties":{"items":{"type":"array"}}}
response_format.json_schema.strict	boolean	可选	是否严格按 schema 约束，默认倾向严格。	true
stop	string 或 string[]	可选	停止词，Kimi 原厂限制数量和字节长度。	["END"]
stream_options.include_usage	boolean	可选	流式 [DONE] 前发送 usage chunk，断流时可能收不到。	true
prompt_cache_key	string，body 顶层	可选	缓存分组键。Coding Agent 场景通常传 session id 或 task id。	"release-session-42"
safety_identifier	string，body 顶层	可选	稳定用户标识，用于安全与滥用检测，应使用哈希或不可逆 ID。	"user_hash_abc123"
reasoning_effort	string，body 顶层	Kimi K3 可选	kimi-k3 控制推理力度，支持 low、high、max，默认 max。	"high"
thinking	object，body 顶层	模型条件字段	kimi-k2.5、kimi-k2.6、kimi-k2.7-code 的思考模式控制。	{"type":"enabled","keep":"all"}
thinking.type	string	模型条件字段	Kimi k2.5/k2.6 支持 enabled、disabled；k2.7-code 固定开启。	"enabled"
thinking.keep	string 或 null	模型条件字段	all 表示保留历史推理；省略或 null 的行为按模型而定。	"all"
messages[].content[].image_url	string 或 object	多模态条件字段	用于传输图片，支持对象形式 {"url": "..."} 或直接传入 URL 字符串。	{"url":"https://example.com/file_abc"}
messages[].content[].video_url	string 或 object	多模态条件字段	用于传输视频，支持对象形式 {"url": "..."} 或直接传入 URL 字符串。	{"url":"https://example.com/a.mp4"}
messages[].partial	boolean	可选	Partial Mode 标识，通常放在最后一条 assistant 消息，用于预填输出前缀。	true
tools[].function.strict	boolean	可选	是否严格按 MFJS/JSON Schema 生成工具参数。	true

注意：

• 当 image_url 传入对象时，其字段说明如下：

  参数名称	是否必须	说明	类型
  url	required	使用 base64 编码指定的图片内容	string

• 当 video_url 传入对象时，其字段说明如下：

  参数名称	是否必须	说明	类型
  url	required	使用 base64 编码指定的视频内容，例如 data:video/mp4;base64,...	string

• 无论使用对象形式（url 字段）还是字符串简写，均支持 base64 编码（data:image/png;base64,... 或 data:video/mp4;base64,...）。

请求示例

json{
  "model": "kimi-k2.6",
  "messages": [
    {
      "role": "user",
      "content": "写一个三步发布检查清单。"
    }
  ],
  "thinking": {
    "type": "enabled",
    "keep": "all"
  },
  "stream_options": {
    "include_usage": true
  },
  "prompt_cache_key": "release-session-42",
  "safety_identifier": "user_hash_abc123",
  "max_completion_tokens": 2048
}

Kimi 的 Partial Mode、prompt_cache_key、prediction、MFJS response_format 等 OpenAI-compatible 私有能力应走 https://ai.yunxinapi.com/hub/v1/chat/completions。

响应示例

以下为 Chat Completions 的典型非流式成功响应。开启 thinking 后，Kimi 可能将推理内容放在 reasoning_content，最终可见答案仍位于 content。

json{
  "id": "chatcmpl-aihub-kimi-example",
  "object": "chat.completion",
  "created": 1786406400,
  "model": "kimi-k2.6",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "reasoning_content": "检查清单应覆盖变更确认、自动化验证和发布后观察。",
        "content": "1. 确认变更范围与回滚方案。\n2. 跑完自动化测试和发布前检查。\n3. 发布后观察错误率、延迟与核心业务指标。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 73,
    "total_tokens": 98
  }
}

reasoning_content 是否返回及其保留规则取决于具体 Kimi 模型；多轮 Preserved Thinking 场景应按原字段回传，不要并入 content。