model。| 项目 | 值 |
|---|---|
| 端点 | POST https://platform.shuyanai.com/v1/chat/completions |
| Content-Type | application/json |
| 鉴权 | Authorization: Bearer sk-xxx |
| SDK 的 base_url | https://platform.shuyanai.com/v1 |
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 模型名,如 deepseek-v4.1-flash、glm-5.1、qwen3.8-flash,以模型广场显示的为准 |
messages | array | 是 | 消息列表,见 2.2 消息格式 |
stream | boolean | 否 | 是否以 SSE 流式返回,默认 false |
stream_options | object | 否 | 流式时传 {"include_usage": true},在流末尾返回用量 |
max_tokens | integer | 否 | 生成内容的 Token 上限 |
max_completion_tokens | integer | 否 | 生成内容的 Token 上限,包含推理 Token |
temperature | number | 否 | 采样温度,取值 0~2,越低输出越稳定 |
top_p | number | 否 | 核采样,与 temperature 二选一调整即可 |
stop | string / array | 否 | 停止序列 |
response_format | object | 否 | 输出格式,见 2.4 输出格式控制 |
tools | array | 否 | 工具定义列表,见 5. 工具调用 |
tool_choice | string / object | 否 | 工具选择策略,默认 auto,见 5.2 tool_choice |
logprobs | boolean | 否 | 是否返回输出 Token 的对数概率 |
seed、presence_penalty、frequency_penalty、user)按原样传给模型,是否生效取决于具体模型。content 为空、finish_reason 为 length。n(候选数量)请保持为 1:部分模型传 n>1 时仍只返回 1 条结果,部分模型(如思考模式下的 qwen3.8-flash)会返回 400 The n parameter must be 1 when enable_thinking is true。messages 是一个消息对象数组,每条消息包含 role 和 content 字段。接口本身不保存上下文,多轮对话时需把历史消息按顺序全部传入。role | 用途 |
|---|---|
system | 系统指令,设定助手的身份和规则,放在最前面 |
user | 用户输入。content 可以是字符串,也可以是包含文本和图片的数组 |
assistant | 模型之前的回复,用于多轮对话;调用工具时包含 tool_calls |
tool | 工具执行结果,必须带上对应的 tool_call_id |
{
"role": "system",
"content": "你是一位专业的技术文档撰写助手。"
}{
"role": "user",
"content": "请解释什么是 Transformer 架构 。"
}{
"role": "user",
"content": [
{"type": "text", "text": "请描述这张图片的内容。"},
{"type": "image_url", "image_url": {"url": "https://img.shuyanai.com/img/new_home_ai.png"}}
]
}{
"type": "image_url",
"image_url": {
"url": "data:image/png;base64,iVBORw0KGgo..."
}
}{
"role": "assistant",
"content": "Transformer 是一种基于自注意力机制的深度学习架构……"
}{
"role": "tool",
"tool_call_id": "call_abc123",
"content": "{\"temperature\": 22, \"unit\": \"celsius\"}"
}| 模型 | 图片 URL | Base64 |
|---|---|---|
qwen3.8-flash、qwen3.8-max、qwen3.7-plus | 支持 | 支持 |
doubao-seed-2-1-pro-260915 | 支持 | 支持 |
deepseek-v4.1-flash | 支持 | 支持 |
kimi-k2.6 | 不支持(返回 400 Remote image URLs are not supported for this model) | 支持 |
glm-5.1 | 不支持图片输入(返回 400 The current model only supports text modality) | 不支持 |
上表为 2026-11-02 实测结果。图片 URL 由模型服务端下载,需公网可访问;下载失败时请改用 Base64。其他模型的多模态能力请参考模型广场的模型说明。
| type | 说明 |
|---|---|
text | 默认,自由文本输出 |
json_object | 输出合法 JSON |
json_schema | 按指定 JSON Schema 输出(实测 deepseek-v4.1-flash、glm-5.1、qwen3.8-flash、doubao-seed-2-1-pro-260915 可用) |
{
"model": "deepseek-v4.1-flash",
"response_format": {"type": "json_object"},
"messages": [
{"role": "system", "content": "请以 json 格式回答用户的问题。"},
{"role": "user", "content": "列出三种编程语言及其特点。"}
]
}{
"model": "deepseek-v4.1-flash",
"messages": [{"role": "user", "content": "提取信息:张三,28 岁,在杭州做产品经理"}],
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "person",
"strict": true,
"schema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"age": {"type": "integer"},
"city": {"type": "string"},
"job": {"type": "string"}
},
"required": ["name", "age", "city", "job"],
"additionalProperties": false
}
}
}
}content:"{\"age\": 28, \"city\": \"杭州\", \"job\": \"产品经理\", \"name\": \"张三\"}"json_object 时,system 或 user 消息中必须出现「json」一词,否则返回 400:Prompt must contain the word 'json' in some form to use 'response_format' of type 'json_object'。deepseek-v4.1-flash 的实际响应(reasoning_content 已截断):{
"id": "021793624270928816811b617e2b5631e8927bae226874c6d9a82",
"object": "chat.completion",
"created": 1793624272,
"model": "deepseek-v4-1-flash-260910",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "我是由深度求索开发的AI助手,乐于为你提供简洁、准确的帮助。",
"reasoning_content": "我们需要回答用户中文请求:“用一句话介绍你自己”。要求一句话……"
},
"finish_reason": "stop",
"logprobs": null
}
],
"usage": {
"prompt_tokens": 40,
"completion_tokens": 134,
"total_tokens": 174,
"prompt_tokens_details": {
"cached_tokens": 0
},
"completion_tokens_details": {
"reasoning_tokens": 116
}
}
}| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 请求唯一标识 |
object | string | 固定为 "chat.completion" |
created | integer | Unix 时间戳 |
model | string | 实际响应的模型版本,可能与请求的写法不同(如请求 deepseek-v4.1-flash,返回 deepseek-v4-1-flash-260910) |
choices[].index | integer | 候选序号 |
choices[].message.role | string | 固定为 "assistant" |
choices[].message.content | string | null | 生成的文本内容 |
choices[].message.reasoning_content | string | null | 推理过程(仅推理模型返回,见 3.3) |
choices[].message.tool_calls | array | 工具调用列表(见 5. 工具调用) |
choices[].finish_reason | string | 结束原因:stop 正常结束、length 达到 Token 上限、tool_calls 需要调用工具 |
choices[].logprobs | object | null | 请求中设置 logprobs: true 时返回 Token 对数概率,否则为 null |
usage.prompt_tokens | integer | 输入 Token 数 |
usage.completion_tokens | integer | 输出 Token 数(含推理 Token) |
usage.total_tokens | integer | 总 Token 数 |
usage.prompt_tokens_details.cached_tokens | integer | 命中缓存的输入 Token 数 |
usage.completion_tokens_details.reasoning_tokens | integer | 推理过程消耗的 Token 数 |
不同模型可能返回额外字段(如 service_tier、system_fingerprint、usage.prompt_tokens_details.image_tokens),客户端解析时请忽略未知字段。
message.reasoning_content 中返回思考过程,content 为最终回答。reasoning_content 的模型:deepseek-v4.1-flash、deepseek-v4-pro、glm-5.1、qwen3.8-flash、qwen3.8-max、qwen3.7-plus、doubao-seed-2-1-pro-260915、kimi-k2.6。deepseek-v4.1-flash,请求:"1+1等于几?只回答数字"):{
"id": "021793624272854f47b3ae95ec9e82c79e9e226fe2407f9db3531",
"object": "chat.completion",
"created": 1793624273,
"model": "deepseek-v4-1-flash-260910",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "2",
"reasoning_content": "我们需要回答用户中文:“1+1等于几?只回答数字” 要求只回答数字。所以最终只输出 2。确保没有多余。"
},
"finish_reason": "stop",
"logprobs": null
}
],
"usage": {
"prompt_tokens": 39,
"completion_tokens": 34,
"total_tokens": 73,
"prompt_tokens_details": {
"cached_tokens": 0
},
"completion_tokens_details": {
"reasoning_tokens": 32
}
}
}usage.completion_tokens_details.reasoning_tokens 记录推理消耗的 Token,这部分同样计入 completion_tokens 并按输出计费。max_tokens / max_completion_tokens 预留足够空间。"stream": true 即可启用流式输出,服务端通过 Server-Sent Events(SSE)逐块推送内容。data: 开头,最后一条为 data: [DONE]。以下为 glm-5.1 的实际数据块(节选,已省略 id、created 等字段):data: {"choices":[{"delta":{"content":null,"reasoning_content":"1","role":"assistant"},"finish_reason":null,"index":0}],"object":"chat.completion.chunk","model":"glm-5.1","usage":null}
data: {"choices":[{"delta":{"content":null,"reasoning_content":". **分析"},"finish_reason":null,"index":0}],"object":"chat.completion.chunk","model":"glm-5.1","usage":null}
data: {"choices":[{"delta":{"content":"心情!","reasoning_content":null},"finish_reason":null,"index":0}],"object":"chat.completion.chunk","model":"glm-5.1","usage":null}
data: {"choices":[{"delta":{"content":"","reasoning_content":null},"finish_reason":"stop","index":0}],"object":"chat.completion.chunk","model":"glm-5.1","usage":null}
data: {"choices":[],"object":"chat.completion.chunk","model":"glm-5.1","usage":{"prompt_tokens":9,"completion_tokens":599,"total_tokens":608,"completion_tokens_details":{"reasoning_tokens":585},"prompt_tokens_details":{"cached_tokens":0}}}
data: [DONE]| 字段 | 类型 | 说明 |
|---|---|---|
choices[].delta.role | string | 值为 "assistant" |
choices[].delta.content | string | null | 增量文本内容 |
choices[].delta.reasoning_content | string | null | 增量推理内容(仅推理模型) |
choices[].delta.tool_calls | array | 增量工具调用 |
choices[].finish_reason | string | null | 生成结束时返回结束原因 |
usage | object | null | 设置 include_usage 后,在最后一个 choices 为空的数据块中返回用量(部分模型在带 finish_reason 的数据块中也会附带) |
reasoning_content,再输出 content,客户端应 分别拼接这两个字段。没有内容的字段,不同模型返回 null 或空字符串 "",请按「非空才拼接」处理。tools 参数定义可供模型调用的函数。{
"model": "glm-5.1",
"messages": [
{"role": "user", "content": "北京今天的天气怎么样?"}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "查询指定城市的当前天气信息",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "城市名称,如 北京"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "温度单位"
}
},
"required": ["city"]
}
}
}
]
}| 值 | 说明 |
|---|---|
"auto" | 模型自行决定是否调用工具(默认) |
"none" | 不调用工具,直接回答 |
"required" | 必须调用至少一个工具 |
{"type": "function", "function": {"name": "get_weather"}} | 必须调用指定工具 |
以上四种取值在 deepseek-v4.1-flash、glm-5.1上均实测可用。
finish_reason 为 "tool_calls"。以下为 glm-5.1 的实际响应:{
"id": "chatcmpl-ffa5be56-8548-960c-9ce4-86d16da0c559",
"object": "chat.completion",
"created": 1793624285,
"model": "glm-5.1",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "",
"reasoning_content": "The user is asking about the weather in Beijing today. I should call the get_weather function with city \"北京\".",
"tool_calls": [
{
"id": "call_8ddf74f03eae4e2fb7ba3e0b",
"index": 0,
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\"city\": \"北京\", \"unit\": \"celsius\"}"
}
}
]
},
"finish_reason": "tool_calls",
"logprobs": null
}
],
"usage": {
"prompt_tokens": 189,
"completion_tokens": 42,
"total_tokens": 231,
"completion_tokens_details": {"reasoning_tokens": 23},
"prompt_tokens_details": {"cached_tokens": 0}
}
}content 可能为 null、空字符串或一段文字说明(如 deepseek-v4.1-flash 会同时返回「我来同时查询北京和上海的天气。」),请以 tool_calls 是否存在来判断是否需要执行工具。tool_calls。tool_calls)和工具结果(role: "tool")追加到 messages,再次请求。今天北京天气晴朗,气温28度……tool_calls(如问「北京和上海今天的天气怎么样?」时,deepseek-v4.1-flash 返回两次 get_weather 调用)。客户端应分别执行,并为每个 tool_call_id 回传一条 tool 消息:{
"role": "assistant",
"tool_calls": [
{"id": "call_001", "type": "function", "function": {"name": "get_weather", "arguments": "{\"city\": \"北京\"}"}},
{"id": "call_002", "type": "function", "function": {"name": "get_weather", "arguments": "{\"city\": \"上海\"}"}}
]
}content:"图片中央是一个蓝紫渐变的“AI”图标,四周环绕着代表视觉(眼睛)、搜索(放大镜)、对话(气泡)和数据分析(上升柱状图)的四个彩色圆形图标,背景为深色。"