文本对话与视觉理解

选择模型和消息

文本与支持视觉的模型都使用 POST /chat/completions。model 是公开模型别名，messages 是消息数组。先完成 快速开始，再增加目标模型支持的参数。

模型的上下文、单次输出上限和默认值不是同一个概念。不要把上下文长度作为 max_tokens；不要将某个模型的默认输出上限推广到所有服务。模型详情提供服务当前开放的参数范围。

带图片的消息

先按 素材上传 上传图片，取回 asset.assetId。支持视觉输入的服务使用以下消息内容，素材必须属于当前调用身份并适配同一模型：

{
  "model": "<MODEL_ALIAS>",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "按画面顺序描述这个场景"},
      {"type": "image_url", "image_url": {"url": "asset://<ASSET_ID>"}}
    ]
  }]
}

只有服务明确声明时才可使用外部图片 URL 或内联 Base64；Qwen3.8 的兼容格式见下文。其他服务继续使用素材上传与 asset:// 引用。图像续写也由同一真实模型能力决定；体验中心中的模板是提示词辅助，不是特殊 API。

消费流式响应

只有目标服务声明支持流式时才设置 stream: true。cURL 加 --no-buffer；服务端客户端按 SSE 事件边界解析，不按 TCP 数据块直接 JSON 解码。

1. 确認 HTTP 成功，响应类型为 text/event-stream。
2. 累积数据直到完整事件边界，再解析 data:；一个网络块可能包含半条或多条事件。
3. 合并 choices[].delta.content，保留 finish_reason；Qwen3.8 开启思考时另行累计 delta.reasoning_content，不要混入最终答案。
4. 只有收到 data: [DONE] 才认为流传输正常结束；若 finish_reason=length，仍需向用户说明内容受到长度限制。
5. 连接提前关闭时保留“部分内容”状态，不标记成功，不自动把同一请求再发一次。

服务端期限与客户端等待预算分别生效。HTTP 响应开始前的超时可能是 504；已开始的 SSE 出错可能以连接关闭表现，不能只依赖 HTTP 状态。

可运行的流式示例

下载服务端 JavaScript 示例，设置快速开始的三个环境变量后运行 node chat-stream.mjs。需要支持内置 fetch 的 Node.js，不能在浏览器中运行或把 Key 编译到网页里。

示例处理 UTF-8 跨网络块、LF/CRLF 事件行、连续事件、[DONE]、流内错误和非正常关闭；finish_reason=length 会明确提醒内容受到长度限制，不将它显示为完整回答。示例不会自动重试计费调用。它在普通模式使用 330 秒、思考模式使用 1900 秒客户端等待预算，真实服务允许的时限和输出范围仍以模型合同为准。

请求字段和响应 · 错误恢复。

进阶多模态内容分析

qwen3-6-35b-a3b 使用原“进阶多模态内容分析”服务入口。模型广场的服务卡片在 API 接入 中提供当前合同与 cURL、Python、Node.js 示例；旧 Console 和新 Portal 使用相同的公开模型别名。以下能力仅适用于服务当前声明的合同：

本节 qwen3-6-35b-a3b 不接受调用方扩大素材预算、开启思考模式或传入内部结构化生成控制项；Qwen3.8 的思考用法见下文。提示词优化器使用的模型由平台独立配置，此服务升级不意味着优化器已切换。

视频消息把图片示例的内容项换成 {"type":"video_url","video_url":{"url":"asset://<VIDEO_ASSET_ID>"}}。多素材按 content 数组顺序组合；每个素材都先以同一身份、同一模型上传。超出预算会拒绝，不能依赖服务自动丢图或缩减合法引用。

“多模态内容分析”和“进阶多模态内容分析”启用扩展版本后，可在一次消息中提交9张纯图片或8张图片与1个视频。旧版本仍按服务卡片声明的上限接收。 扩展版本保留2个视频及2图＋2视频的用法，总媒体最多9项；包含2个视频时最多配2张图。数量按全部消息累计，单素材大小、采样帧数和 token 预算同时生效。 每张图片使用独立 image_url，视频使用独立 video_url，无需拼图；SDK 同步与异步调用使用同一消息结构。

Qwen3.8 多模态理解

公开模型别名为 qwen38-27b，使用同一个 /v1/chat/completions 接口。调用前在模型广场确认服务可用及当前合同。图片和视频混合时，数量上限随视频个数变化。

输入和输出上限不能分别取满：例如输入 262080 tokens 时，输出预算最多剩余 64。显式设置适合业务的 max_tokens；默认 64 很容易让较长回答以 finish_reason=length 结束。素材同时消耗上下文预算，文件大小合规不表示一定满足 token 预算。不要把历史测试图片或视频的尺寸当作任意尺寸都可接收的保证；不要传入私有预处理参数扩大服务合同。

curl --no-buffer --max-time 1900 https://api.jusuanhub.com/v1/chat/completions \
  -H "Authorization: Bearer $JUSP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"qwen38-27b","messages":[{"role":"user","content":"用三句话解释推理服务的并发限制。"}],"max_tokens":256,"stream":true,"stream_options":{"include_usage":true}}'

思考模式

在普通 Qwen3.8 对话中设置 enable_thinking: true；也可只设置非 none 的 reasoning_effort 来开启。两者都省略时关闭。它们是请求 JSON 的顶层字段，不放在 messages、提示词文字或自定义请求头中；其他模型不能据此推定支持思考。

同时设置开关和档位时必须一致：true 可配非 none 档位，false 可配 none；冲突返回 400。顶层与 chat_template_kwargs 的同名字段也不能冲突。上述别名实际归为三个思考档位，不表示七种独立计算预算。

下面是非流式调用。将 JUSP_API_KEY 设置为自己的 Key；max_tokens 同时覆盖思考和最终回答，不能再沿用默认的 64 tokens 期待完整推理回答。

curl --max-time 1900 https://api.jusuanhub.com/v1/chat/completions \
  -H "Authorization: Bearer $JUSP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"qwen38-27b","messages":[{"role":"user","content":"比较两个方案，并给出推荐理由。"}],"enable_thinking":true,"reasoning_effort":"medium","max_tokens":4096,"stream":false}'

非流式从 choices[0].message.reasoning_content 读取思考，从 choices[0].message.content 读取最终答案；两者分别展示，不拼接为答案。关闭思考时思考字段可能不存在。流式对应 choices[].delta.reasoning_content 和 choices[].delta.content，两类增量应分别累计；只读 delta.content 的客户端在思考阶段可能暂时没有可展示的答案。

将请求改为 stream: true 并加入 stream_options: {"include_usage": true} 即可使用 SSE。使用本页服务端 JavaScript 示例时设置 JUSP_MODEL=qwen38-27b、JUSP_ENABLE_THINKING=true，可选 JUSP_REASONING_EFFORT=medium；已有的 JUSP_BASE_URL 和 Key 设置沿用快速开始。示例解析器提供两类增量回调并保留最终 usage；命令行只输出答案，思考保留在返回值的 reasoning 中，不在文档网页执行计费调用。

finish_reason=length 表示输出预算耗尽，可能只有思考而没有最终答案；即使收到 [DONE] 也不能标记为完整回答。思考消耗包含在 usage.completion_tokens 中，不另加一次；用量事件可能没有 choices，须继续读到结束。HTTP 200 不代替流完成，连接中断不自动重放。开启思考可能增加等待和输出用量，max_tokens 仍受输入输出总预算约束。

思考可用于普通文本与所选服务支持的视觉、工具对话；工具结果按下文两跳协议提交。response_format.type=json_schema 必须关闭思考与流式，不组合 tools 或 stop。关闭时省略档位，或同时使用 enable_thinking: false 与 reasoning_effort: "none"。多轮调用保留原始 assistant 消息及其中已有的 reasoning_content、tool_calls，不要把思考正文改写成 user 消息。

结构化输出与历史缓存

结构化调用示例：

{"model":"qwen38-27b","messages":[{"role":"user","content":"将春季新品发布计划整理为主题与摘要。"}],"enable_thinking":false,"stream":false,"max_tokens":512,"response_format":{"type":"json_schema","json_schema":{"name":"summary","strict":true,"schema":{"type":"object","properties":{"topic":{"type":"string"},"summary":{"type":"string"}},"required":["topic","summary"],"additionalProperties":false}}}}

历史缓存不需要提交 session ID 或缓存身份请求头。继续对话时保留完整、有序的历史消息和模型原始回答，再追加新问题。只有精确历史匹配且命中同一后端的有效缓存才可能复用；不同 Key、调用者、应用和工作空间隔离。cached_tokens 是输入 tokens 的子集，不另外加进 total_tokens。请求结束后仍以平台用量记录与实际计费规则为准。

后端更新或重建可能使历史缓存未命中；调用方沿用 qwen38-27b 与现有请求格式，以实际 usage.prompt_tokens_details.cached_tokens 判断本次复用。

多轮对话不设固定轮数上限，限制的是每次请求的完整上下文。系统提示、工具定义、历史消息、工具结果及视觉 tokens 都占用输入预算，并须为本次输出预留空间；入口 32MiB 正文和整段历史的媒体数量限制也同时生效。调用方负责在接近预算时裁剪历史或生成摘要，保留仍需引用的图片，以及完整配对的工具调用和结果。平台不会自动丢弃历史或替客户端生成摘要；上下文超限会返回错误。缓存复用减少重复计算，不扩大上下文窗口。

八并发与 256K 是不同维度：不能据此推断八路各占满 256K 时仍全部立即执行。图片数量合规也不代表任意尺寸均能通过显存检查。语言初始化在服务就绪前完成，动态图片和视频仍可能有首次处理开销。

图片的 image_url.url 支持三种形式：既有 asset://<ASSET_ID>、公网 HTTPS 443 图片地址，以及 data:image/png;base64,...（也支持 JPEG、WebP）。外部图片由平台自动导入临时素材，无需客户端先调用上传接口；仍受单图 16MiB、16777216 解码像素、整次请求媒体数量和上下文预算限制。URL 必须可由服务端公开访问，可带签名查询参数，不能依赖登录 Cookie 或额外鉴权头；私网、localhost、非 HTTPS 与非 443 端口拒绝。

聊天入口的整个 JSON 请求体最多 32MiB，包含 Base64 编码、所有历史和工具定义；Base64 通常比原文件大约三分之一。单图 16MiB 是解码后文件上限，多个内联图片仍可能超过请求体上限。较大素材建议使用公网 HTTPS 地址或先上传后引用 asset://。

视频继续按素材上传以同一 Key、同一模型上传，再在 video_url 中引用 asset://<ASSET_ID>。图文和视频工具的两跳消息格式与本页示例相同，将 model 改为 qwen38-27b 并保留原始媒体消息；使用 stop 时须移除媒体和工具，并设置 stream: false。纯文本可用字符串或标准文本片段数组，平台会规范化后转发。升级灰度期间以目标服务的公开能力为准：toolsTextOnly: true 时仍仅允许纯文本工具请求。

WorkBuddy 自定义模型

选择 OpenAI Chat Completions 格式，基础地址填写 https://api.jusuanhub.com/v1（关闭“完整 URL”）；模型 ID 为 qwen38-27b，填写自己的 API Key。启用工具调用与图片输入；思考可按需开启，客户端须能传递上述参数并分别处理思考与答案，不能只凭界面开关判断已生效。输出预算建议显式设置为 8192，输入预算不得超过服务公开上限。若使用完整 URL，则填写 https://api.jusuanhub.com/v1/chat/completions。

WorkBuddy 可直接发送 Base64 图片；无需把图片手动上传到外部图床。平台会处理已知的客户端消息附加字段、空 annotations 和工具调用的空正文，并保持工具 ID、参数、结果和历史顺序。图片应放在 user 消息中；后续对话保留原始图片消息、assistant 的 tool_calls 及对应 tool 结果。工具必须开启时也可识图，但目标服务须已开放图文工具组合。客户端取消、超时或 SSE 提前结束时，不自动重放已有用量的请求。

多个后端的总容量不是单个调用者的额度：个人用户的所有 API Key 与页面调用共享一份账号同步额度（默认 5：每秒最多发起 5 个新请求，且同时最多 5 个请求在处理，流式响应结束后才释放），不另设单 Key 门槛，服务后端容量独立生效。遇到 429 时保留错误码：ACCOUNT_REQUEST_RATE_LIMITED 表示每秒请求过多，ACCOUNT_CONCURRENCY_LIMITED 表示同时进行的请求已满，应等待已有请求完成；都要遵守 Retry-After 退避，不无限重试。需要更高额度请联系平台管理员调整。首次遇到新输入长度或视觉形状仍可能有额外处理开销，首次请求耗时不代表热态生成速度。客户端 1900 秒是等待预算示例，不是响应时间承诺；服务当前上游期限为 1860 秒。

性能比较须区分首字延迟（TTFT）、整次请求耗时和生成阶段 token/s。后台同步调用的耗时包括服务执行等待，输出吞吐按完整调用计时，不能直接和 Runtime 的纯 Decode TPS 对比。

函数工具与两跳消息

目标服务公开 tools 参数时，可发送以下请求。tool_choice 支持 auto、none、required 或指定函数对象；parallel_tool_calls: false 要求一次最多返回一个调用。平台不代替你的应用执行函数，也不会替调用方授权业务操作。

{
  "model": "qwen3-6-35b-a3b",
  "messages": [{"role": "user", "content": "查询杭州的天气"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "查询指定城市天气",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }],
  "tool_choice": {"type": "function", "function": {"name": "get_weather"}},
  "parallel_tool_calls": false,
  "max_tokens": 256,
  "stream": false
}

当 finish_reason 为 tool_calls 时，解析返回的 message.tool_calls[].function.arguments JSON，校验函数名、参数和调用人的权限，再执行自己的函数。下一次请求保留原消息和完整的 assistant 消息（包括原始工具调用 ID，content 可以为 null），为每个结果追加 {"role":"tool","tool_call_id":"<RETURNED_TOOL_CALL_ID>","content":"<YOUR_TOOL_RESULT>"}。不要自己生成或改写 tool_call_id。第二跳仍是一次独立计费调用。

工具调用使用 SSE 时，按 delta.tool_calls[].index 合并 ID、函数名和参数片段，完整结束后再解析参数和执行函数。当前服务会先完整校验工具参数再分片返回，不能把它当作逐 Token 的工具参数推送。收到流内错误或提前 EOF 时，不执行不完整调用，不自动重试计费请求。

自定义停止文本

例如请求加入 "stop": ["【结束】"]。停止文本可为 Unicode；命中后正文不包含该文本，响应保留正常的结束原因与实际用量。finish_reason=length 表示达到输出预算，不能标记为完整答案。不要用 stop 截断工具参数 JSON。