AIHub 在 https://ai.yunxinapi.com/hub/v1 下提供 OpenAI-compatible Chat Completions 入口。已有 OpenAI SDK 代码通常只需替换 Base URL、API Key 和模型名称即可接入。

请求 URL

httpPOST https://ai.yunxinapi.com/hub/v1/chat/completions

同协议 OpenAI-compatible 路由会优先保留原始请求体并转发到上游，因此 temperature、tools、metadata 等 OpenAI 原生字段可以随请求进入渠道；跨协议 bridge 路由只保证 model、messages、n 等稳定语义。

请求头

Header	必填	说明
Authorization	是	AIHub 访问令牌，格式为 Bearer <AIHUB_TOKEN>
Content-Type	是	固定使用 application/json

请求体参数

核心参数

字段	类型	必填	说明
model	string	是	AIHub 逻辑模型名，用于模型授权、限流、路由选择和上游模型映射。
- messages	object[]	是	对话消息数组，按上下文顺序传入。
role	string	是	消息角色：system、developer、user、assistant、tool。
content	string/object[]	否	消息内容，可为纯文本或多模态数组。
name	string	否	消息发送者名称。
tool_call_id	string	否	role=tool 时用于关联模型发起的工具调用。
tool_calls	object[]	否	assistant 消息中的工具调用列表。
reasoning_content	string	否	部分推理模型返回或接收的思考内容字段。
stream	bool	否	是否启用 SSE 流式输出。true 时请求模式为流式；默认非流式。
stream_options	object	否	流式选项，如 {"include_usage": true} 要求末尾返回 usage；是否支持取决于上游。
n	int	否	返回候选数量。多数生产模型建议保持 1。
max_tokens	int	否	旧版最大输出 token 数。部分新模型更推荐 max_completion_tokens。
max_completion_tokens	int	否	最大补全 token 数，适用于较新的 OpenAI-compatible 模型。
reasoning_effort	string	否	推理强度，例如 low、medium、high；仅推理模型或兼容渠道生效。

采样控制参数

字段	类型	必填	说明
temperature	number	否	随机性控制。值越高输出越发散；常见范围为 0-2。
top_p	number	否	nucleus sampling 参数；通常不建议与 temperature 同时大幅调整。
top_k	int	否	部分上游支持的候选截断参数；非 OpenAI 标准字段。
frequency_penalty	number	否	频率惩罚，减少重复表达；范围依上游模型而定。
presence_penalty	number	否	存在惩罚，鼓励引入新主题；范围依上游模型而定。
seed	number	否	随机种子；仅部分上游支持可复现输出。

工具与输出控制

字段	类型	必填	说明
- tools	object[]	否	工具定义数组，当前稳定支持 type=function。
type	string	是	工具类型，函数工具固定为 function。
function.name	string	是	函数名称。
function.description	string	否	函数说明，供模型判断何时调用。
function.parameters	object	否	JSON Schema 参数定义。
tool_choice	string/object	否	工具选择策略，如 auto、none、required 或指定函数。
response_format	object	否	输出格式约束，如 {"type":"json_object"} 或 json_schema。
parallel_tool_calls	bool	否	是否允许模型并行调用多个工具。
stop	string/string[]	否	停止序列，模型生成命中后停止输出。

扩展与高级参数

字段	类型	必填	说明
logprobs	bool	否	是否返回 token log probability；仅部分模型支持。
top_logprobs	int	否	配合 logprobs 使用，返回每个位置的候选 token 数。
metadata	object	否	客户侧元数据，透传给支持该字段的上游，也可用于排查。
user	string/object	否	终端用户标识；可能被上游用于风控或审计。
store	bool	否	是否允许上游存储请求/响应数据。渠道配置可禁用该字段透传。
service_tier	string	否	上游服务层级。默认会被过滤，需渠道允许后才透传。
safety_identifier	string	否	安全风控用户标识。默认会被过滤，需渠道允许后才透传。
prompt_cache_key	string	否	上游 prompt cache 复用键，支持情况取决于渠道。
prompt_cache_retention	string/object	否	上游 prompt cache 保留策略，支持情况取决于渠道。
modalities	string[]	否	多模态输出类型，例如文本、音频；仅多模态模型支持。
audio	object	否	音频输出配置；仅支持音频输出的上游模型生效。
prediction	object	否	预测输出提示，用于部分代码编辑/补全场景。
web_search_options	object	否	Web 搜索选项，支持情况取决于模型和渠道。
enable_thinking	bool/object	否	部分 Qwen 等模型的思考模式开关。
extra_body	object	否	特定上游的扩展参数；建议仅在明确渠道支持时使用。

请求示例

bashcurl "https://ai.yunxinapi.com/hub/v1/chat/completions" \
  -H "Authorization: Bearer $AIHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$AIHUB_MODEL"'",
    "messages": [
      {"role": "user", "content": "hello"}
    ],
    "temperature": 0.7,
    "stream": false
  }'

• AIHUB_TOKEN 为 AIHub API 密钥/访问令牌。
• AIHUB_MODEL 为 AIHub 逻辑模型名，可在控制台查看，或通过 GET https://ai.yunxinapi.com/hub/v1/models 查询。

成功响应

非流式响应默认保持 OpenAI Chat Completions 格式。

字段	类型	说明
id	string	响应 ID。
object	string	对象类型，通常为 chat.completion。
created	int	Unix 秒级创建时间。
model	string	实际响应模型名，可能是上游模型名。
choices	object[]	候选结果列表。
choices[].index	int	候选序号。
choices[].message	object	assistant 消息。
choices[].finish_reason	string	结束原因，例如 stop、length、tool_calls。
usage	object	token 用量；字段是否完整取决于上游。

流式输出

设置 "stream": true 后，接口返回 SSE 数据流。

若上游支持且设置了 stream_options.include_usage=true，流末尾可能包含 usage chunk。具体行为取决于模型、渠道和上游协议能力。

上游厂商参数映射

Chat Completions 既可走 OpenAI-compatible 同协议渠道，也可能在少数路由上进入跨协议 bridge。两者的参数保留范围不同：

目标上游/渠道类型	上游接口	AIHub 入参到上游参数	说明
OpenAI/OpenAI-compatible passthrough/DeepSeek/Moonshot/Zhipu/MiniMax	POST https://ai.yunxinapi.com/hub/v1/chat/completions 或厂商兼容路径	model 映射为渠道配置的上游模型名；messages、stream、temperature、top_p、tools、tool_choice、response_format 等同名字段进入上游	同协议 managed 路由优先保留原始请求体，适合传递厂商兼容的扩展字段
Azure OpenAI	Azure OpenAI Chat Completions 路径	model 写为 Azure deployment name；其他 OpenAI-compatible 字段保持同名	Azure 渠道按渠道配置处理 deployment 和 API version
Anthropic/Bedrock（跨协议 bridge）	厂商原生 messages/runtime 接口	model -> 上游模型；messages[].role/content -> 厂商消息结构；assistant tool_calls 和 tool 结果转换为对应工具块	仅保证文本和工具调用闭环；temperature、top_p、tools、tool_choice、response_format、stream_options 等 OpenAI 特有字段不保证保留

常见字段对应关系：

AIHub 字段	OpenAI-compatible 上游	Azure OpenAI 上游	Anthropic/Bedrock bridge
model	body.model，值为渠道映射后的上游模型名	body.model，值为 Azure deployment name	canonical model，再写入目标厂商模型字段
messages	body.messages	body.messages	转为厂商消息结构；仅稳定支持文本内容和工具调用
max_tokens/max_completion_tokens	同名字段，取决于上游模型支持	同名字段，取决于 Azure 模型支持	不保证保留
temperature/top_p/top_k	同名或厂商兼容字段	同名字段，取决于 Azure 模型支持	不保证保留
tools/tool_choice	同名字段	同名字段，取决于 Azure 模型支持	仅已有 assistant tool_calls/tool 结果会参与上下文转换；请求级工具定义不保证保留
response_format	body.response_format	body.response_format	不保证保留
reasoning_effort/enable_thinking/reasoning_content	按厂商兼容字段透传，是否生效取决于模型	取决于 Azure 模型支持	只保留消息里的 reasoning_content 语义；请求级推理参数不保证保留

路由和上游

AIHub 根据模型授权、访问组、渠道配置、路由绑定和运行时健康状态选择候选渠道。调用方只需要使用 AIHub 逻辑模型名；上游模型重定向由渠道模型配置处理。