数眼智能
官网主页控制台API文档
条款与协议
官网主页控制台API文档
条款与协议
  1. 文本生成API
  • 快速开始
    • 平台简介
    • 控制台(入门)
    • API key
    • Base URL
  • 开发工具接入
    • OpenClaw
    • Claude Code
    • Claude Code IDE
    • Codex
    • OpenCode
    • Cline
    • Grok CLI
    • Gemini CLI
    • N8N
    • AutoClaw
    • 其他工具
  • AI大模型API
    • 文本生成API
      • 对话补全 Chat Completions
    • 视频生成接口API
      • 豆包Seedance视频生成
        • 00-概述
        • 01-创建视频生成任务
        • 02-查询视频生成任务
        • 03-查询视频生成任务列表
        • 04-取消或删除视频生成任务
        • Seedance 私域素材库 API
      • 海螺Hailuo视频生成
        • 00-概述
        • 01-文生视频-T2V
        • 02-图生视频-I2V
        • 03-首尾帧生成视频-FL2V
        • 04-主体参考视频-S2V
        • 05-查询任务状态
        • 06-视频下载
        • 07-附录-运镜指令与回调
      • MiniMax-H3视频生成
        • 00-概述
        • 01-创建视频生成任务
        • 02-创建视频再生成任务
        • 03-创建H3-Context-IR任务
        • 04-查询任务
        • 05-查询任务列表
        • 06-取消或删除任务
      • 可灵AI视频生成-新版接口
        • 00-概述
        • 01-文生视频
        • 02-图生视频
        • 03-Omni视频生成
        • 04-动作控制
        • 05-查询任务
      • 可灵AI视频生成-原版接口
        • 00-概述
        • 01-文生视频
        • 02-图生视频
        • 03-视频Omni
        • 04-多图参考生视频
        • 05-动作控制
        • 06-多模态视频编辑
        • 07-视频延长
        • 08-对口型
        • 09-数字人
        • 10-文生音效
        • 11-视频配音效
        • 12-语音合成
        • 13-音色克隆
        • 14-图像识别
        • 15-主体管理
        • 16-视频特效
      • Vidu视频生成
        • 00-概述
        • 01-文生视频
        • 02-图生视频
        • 03-参考生视频
        • 04-首尾帧
        • 05-智能多帧
        • 06-场景特效模板
        • 07-模板成片
        • 08-查询任务
      • 即梦视频生成
        • 00-概述
        • 01-3.0Pro视频生成
        • 02-720P文生视频
        • 03-720P图生视频-首帧
        • 04-720P图生视频-首尾帧
        • 05-720P图生视频-运镜
        • 06-1080P文生视频
        • 07-1080P图生视频-首帧
        • 08-1080P图生视频-首尾帧
        • 09-错误码
      • 万相视频生成
        • 00-概述
        • 01-文生视频
        • 02-图生视频
        • 03-参考生视频
        • 04-视频编辑
        • 05-首尾帧生视频
        • 06-动作迁移与视频换人
        • 07-数字人视频
        • 08-通用视频编辑-VACE
        • 09-查询任务
      • HappyHorse
        • HappyHorse-文生视频
        • HappyHorse-图生视频-基于首帧
        • HappyHorse-参考生视频
        • HappyHorse-视频编辑
    • 通用图像生成API
      • 图像生成接口文档
    • Rerank重排序模型
      • 重排序
  • 搜索/阅读API
    • 网页阅读API
      • Web Reader API
    • 联网搜索API
      • 搜索API
      • 搜索+阅读API
    • 模态卡API
      • 天气
        • 天气模态卡
        • 城市 ID 对照表
        • 天气查询API
      • 搜索 API(旧)
      • 热搜 API
    • 文件OCR解析API
      • PDF文件
      • URL解析
  • 进阶与系统接口
    • CODE&错误码
    • HTTP注意事项
    • 身份验证
    • 接入指南
    • 在线调试
    • 数据更新相关
    • API 密钥与额度查询接口
    • API 密钥管理接口文档
    • 额度与密钥查询
    • Models(列出模型)
    • 查询账户信息
  1. 文本生成API

对话补全 Chat Completions

1. 接口概述#

对话补全(Chat Completions)是平台最核心的接口,采用 OpenAI 兼容格式,支持多轮对话、流式输出、工具调用、结构化输出、图片理解等能力。切换模型只需修改 model。
项目值
端点POST https://platform.shuyanai.com/v1/chat/completions
Content-Typeapplication/json
鉴权Authorization: Bearer sk-xxx
SDK 的 base_urlhttps://platform.shuyanai.com/v1
快速示例:

2. 请求参数#

2.1 顶层参数#

参数类型必填说明
modelstring是模型名,如 deepseek-v4.1-flash、glm-5.1、qwen3.8-flash,以模型广场显示的为准
messagesarray是消息列表,见 2.2 消息格式
streamboolean否是否以 SSE 流式返回,默认 false
stream_optionsobject否流式时传 {"include_usage": true},在流末尾返回用量
max_tokensinteger否生成内容的 Token 上限
max_completion_tokensinteger否生成内容的 Token 上限,包含推理 Token
temperaturenumber否采样温度,取值 0~2,越低输出越稳定
top_pnumber否核采样,与 temperature 二选一调整即可
stopstring / array否停止序列
response_formatobject否输出格式,见 2.4 输出格式控制
toolsarray否工具定义列表,见 5. 工具调用
tool_choicestring / object否工具选择策略,默认 auto,见 5.2 tool_choice
logprobsboolean否是否返回输出 Token 的对数概率
其余 OpenAI 兼容参数(如 seed、presence_penalty、frequency_penalty、user)按原样传给模型,是否生效取决于具体模型。
备注
推理模型的推理 Token 通常也计入输出上限。上限设得过小时,可能只输出了推理内容,content 为空、finish_reason 为 length。
n(候选数量)请保持为 1:部分模型传 n>1 时仍只返回 1 条结果,部分模型(如思考模式下的 qwen3.8-flash)会返回 400 The n parameter must be 1 when enable_thinking is true。

2.2 消息格式(messages)#

messages 是一个消息对象数组,每条消息包含 role 和 content 字段。接口本身不保存上下文,多轮对话时需把历史消息按顺序全部传入。
role用途
system系统指令,设定助手的身份和规则,放在最前面
user用户输入。content 可以是字符串,也可以是包含文本和图片的数组
assistant模型之前的回复,用于多轮对话;调用工具时包含 tool_calls
tool工具执行结果,必须带上对应的 tool_call_id

系统消息(system)#

{
  "role": "system",
  "content": "你是一位专业的技术文档撰写助手。"
}

用户消息(user)#

纯文本:
{
  "role": "user",
  "content": "请解释什么是 Transformer 架构。"
}
图文混合(图片地址或 Base64 Data URL 二选一):
{
  "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..."
  }
}

助手消息(assistant)#

{
  "role": "assistant",
  "content": "Transformer 是一种基于自注意力机制的深度学习架构……"
}

工具消息(tool)#

{
  "role": "tool",
  "tool_call_id": "call_abc123",
  "content": "{\"temperature\": 22, \"unit\": \"celsius\"}"
}

2.3 图片理解支持说明#

模型图片 URLBase64
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。其他模型的多模态能力请参考模型广场的模型说明。

2.4 输出格式控制(response_format)#

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 可用)
json_object 示例:
{
  "model": "deepseek-v4.1-flash",
  "response_format": {"type": "json_object"},
  "messages": [
    {"role": "system", "content": "请以 json 格式回答用户的问题。"},
    {"role": "user", "content": "列出三种编程语言及其特点。"}
  ]
}
json_schema 示例:
{
  "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\": \"张三\"}"
警告
DeepSeek 系列使用 json_object 时,system 或 user 消息中必须出现「json」一词,否则返回 400:Prompt must contain the word 'json' in some form to use 'response_format' of type 'json_object'。

3. 响应格式#

3.1 非流式响应#

以下为 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
    }
  }
}

3.2 响应字段说明#

字段类型说明
idstring请求唯一标识
objectstring固定为 "chat.completion"
createdintegerUnix 时间戳
modelstring实际响应的模型版本,可能与请求的写法不同(如请求 deepseek-v4.1-flash,返回 deepseek-v4-1-flash-260910)
choices[].indexinteger候选序号
choices[].message.rolestring固定为 "assistant"
choices[].message.contentstring | null生成的文本内容
choices[].message.reasoning_contentstring | null推理过程(仅推理模型返回,见 3.3)
choices[].message.tool_callsarray工具调用列表(见 5. 工具调用)
choices[].finish_reasonstring结束原因:stop 正常结束、length 达到 Token 上限、tool_calls 需要调用工具
choices[].logprobsobject | null请求中设置 logprobs: true 时返回 Token 对数概率,否则为 null
usage.prompt_tokensinteger输入 Token 数
usage.completion_tokensinteger输出 Token 数(含推理 Token)
usage.total_tokensinteger总 Token 数
usage.prompt_tokens_details.cached_tokensinteger命中缓存的输入 Token 数
usage.completion_tokens_details.reasoning_tokensinteger推理过程消耗的 Token 数
不同模型可能返回额外字段(如 service_tier、system_fingerprint、usage.prompt_tokens_details.image_tokens),客户端解析时请忽略未知字段。

3.3 推理内容(reasoning_content)#

推理模型会在 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 并按输出计费。
推理 Token 通常多于最终回答,请为 max_tokens / max_completion_tokens 预留足够空间。

4. 流式响应#

4.1 启用流式#

设置 "stream": true 即可启用流式输出,服务端通过 Server-Sent Events(SSE)逐块推送内容。

4.2 流式数据格式#

每个事件以 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]

4.3 流式响应字段说明#

字段类型说明
choices[].delta.rolestring值为 "assistant"
choices[].delta.contentstring | null增量文本内容
choices[].delta.reasoning_contentstring | null增量推理内容(仅推理模型)
choices[].delta.tool_callsarray增量工具调用
choices[].finish_reasonstring | null生成结束时返回结束原因
usageobject | null设置 include_usage 后,在最后一个 choices 为空的数据块中返回用量(部分模型在带 finish_reason 的数据块中也会附带)
备注
推理模型通常先输出一段 reasoning_content,再输出 content,客户端应分别拼接这两个字段。没有内容的字段,不同模型返回 null 或空字符串 "",请按「非空才拼接」处理。

4.4 Python 流式处理示例#


5. 工具调用(Tool Calling)#

5.1 定义工具#

通过 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"]
        }
      }
    }
  ]
}

5.2 tool_choice 参数#

值说明
"auto"模型自行决定是否调用工具(默认)
"none"不调用工具,直接回答
"required"必须调用至少一个工具
{"type": "function", "function": {"name": "get_weather"}}必须调用指定工具
以上四种取值在 deepseek-v4.1-flash、glm-5.1 上均实测可用。

5.3 工具调用响应#

当模型决定调用工具时,响应的 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 是否存在来判断是否需要执行工具。

5.4 工具调用完整流程#

1.
发送用户消息和工具定义。
2.
模型返回 tool_calls。
3.
客户端执行对应函数,获取结果。
4.
将助手消息(含 tool_calls)和工具结果(role: "tool")追加到 messages,再次请求。
5.
模型根据工具结果生成最终回复。
第二次请求示例:
模型据此回答:今天北京天气晴朗,气温28度……
Python 完整示例:

5.5 并行工具调用#

模型可能在一次响应中返回多个 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\": \"上海\"}"}}
  ]
}

6. 完整请求示例#

6.1 基础对话#

6.2 多轮对话#

6.3 图片理解#

图片 URL:
响应中的 content:
"图片中央是一个蓝紫渐变的“AI”图标,四周环绕着代表视觉(眼睛)、搜索(放大镜)、对话(气泡)和数据分析(上升柱状图)的四个彩色圆形图标,背景为深色。"
本地图片(Base64):

6.4 JSON 结构化输出#


7. 错误处理#

7.1 错误响应格式#

{
  "error": {
    "code": "",
    "message": "无效的令牌 (request id: 20261102125937939026575shjpAzqo)",
    "type": "server_error"
  }
}
message 末尾的 request id 与响应头 X-Oneapi-Request-Id 一致,排查问题时请提供该 ID。

7.2 常见错误#

HTTP 状态码实际错误消息(示例)原因与处理
400field messages is required缺少必填参数,补全后重试
400Prompt must contain the word 'json' in some form ...DeepSeek 使用 json_object 时提示词缺少「json」
400The current model only supports text modality and does not support image input ...模型不支持图片输入,换用支持图片的模型
400Remote image URLs are not supported for this model ...模型不支持图片 URL,改用 Base64
401无效的令牌API Key 错误、已删除或已禁用,检查 Key
429—请求频率超限,降低频率后重试
503分组 default 下模型 xxx 无可用渠道(distributor)模型名写错,或当前 Key 无权使用该模型,核对 model 是否与模型广场一致
5xx—服务端或上游异常,稍后重试

7.3 重试建议#

错误类型是否重试策略
400 参数错误否修正参数后重新请求
401 鉴权否检查并更换 API Key
429 限流是指数退避重试(1s、2s、4s……)
5xx是指数退避重试,最多 3 次;持续失败可切换其他模型

8. 最佳实践#

场景建议
控制成本用 max_tokens 限制输出长度;按任务选择合适的模型(如 deepseek-v4.1-flash、qwen3.8-flash)
提高质量提供清晰的 system prompt;用较低的 temperature(如 0.3)获得更稳定的输出
流式体验启用 stream: true 降低首个 Token 的等待时间
结构化输出优先用 json_schema;使用 json_object 时在提示词中写明「json」和期望的字段
推理任务使用推理模型,并为 max_tokens / max_completion_tokens 预留推理空间
工具调用为函数写清楚 description;tool_choice 一般使用默认的 "auto"
多轮对话合理裁剪历史消息,避免超出模型上下文窗口
生产稳定性实现指数退避重试;监控 429/5xx 错误率;配置备选模型
上一页
其他工具
下一页
00-概述