文本对话与视觉理解

选择模型和消息

文本与支持视觉的模型都使用 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 塞进不支持的字段。图像续写也由同一真实模型能力决定；体验中心中的模板是提示词辅助，不是特殊 API。

消费流式响应

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

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

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

下一步

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