API 接入教程

白云 API 教程：Chat 文本接口

白云SI编辑组2026-10-09约 7 分钟阅读

Chat Completions 同步与 SSE 流式纯文本请求示例。附完整检查步骤、实操验证和错误处理。

Chat Completions 文本接口

接口地址：POST https://api.baiyun.si/v1/chat/completions。

当前提供 Chat 形式的纯文本对话，可用于明确支持 OpenAI 兼容 Chat 协议的客户端。请求要使用本站密钥，并提交本次对话需要的完整文本上下文。

请求结构

{
  "model": "gpt-6-luna",
  "messages": [
    {"role": "system", "content": "用简洁的中文回答。"},
    {"role": "user", "content": "请解释什么是 Token。"}
  ],
  "stream": false
}

model 是本站实际开放的模型名称；messages 是按顺序提交的文本消息；stream 决定同步返回或流式返回。本文只展示已开放的基础文本结构，复杂 SDK 参数及扩展功能不应默认可用。

同步调用

curl --fail-with-body https://api.baiyun.si/v1/chat/completions \
  -H "Authorization: Bearer $BAIYUN_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"gpt-6-luna","messages":[{"role":"user","content":"用一句话解释 Token。"}],"stream":false}'

生成文本位于 choices[].message.content；用量信息位于 usage。具体内容、Token 数和费用以本次实际响应及消费记录为准。

流式调用

curl --no-buffer --fail-with-body https://api.baiyun.si/v1/chat/completions \
  -H "Authorization: Bearer $BAIYUN_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model":"gpt-6-luna",
    "messages":[{"role":"user","content":"用三句话介绍 Token。"}],
    "stream":true,
    "stream_options":{"include_usage":true}
  }'

流式返回采用 SSE：读取 data: 中的 JSON，按顺序拼接 choices[].delta.content。data: [DONE] 表示该流结束；启用 include_usage 后需保留末尾用量消息。不要将 SSE 的每一个分片视为独立 HTTP 响应。

对话上下文与参数边界

当前通道使用模型默认采样。temperature、top_p、frequency_penalty 和 presence_penalty 暂不提供可调控制；客户端常见的默认值会由兼容处理移除，不会改变模型的采样设置。

多轮对话应在 messages 中提交必要的完整文本历史。当前暂停外部工具、联网、图片及文件等功能，也不提供通过不可检查的外部历史绕过文本提交的方式。

某些模型或客户端对输出参数的支持不同。即使请求填写 max_tokens、max_completion_tokens 或 8192 等数值，也不能把它当作本站已经保证的输出长度或费用硬上限。请从简短请求开始，核对消费记录，并为密钥设置适合自己的余额限制。

同一凭据最多同时进行 2 个请求；模型调用还受频率限制。遇到 429 先等待，按错误说明判断原因，避免高频循环重试。

实操前的检查清单

准备自己的账户与调用密钥，不使用他人的共享凭据。
记录客户端版本、系统和准备使用的模型，便于排查时复现。
保存原配置或截图，隐藏密钥、验证码与私人内容。
确认测试可能消费少量 DK，先用一句话、一次请求开始。
查阅当前模型广场与状态页，再决定是否启用更多功能。

详细排查：按顺序缩小问题范围

先确认账户已完善、密钥有效、DK 余额足够，再核对协议、地址与模型。用同一密钥做一次最小文本请求；它成功以后，才逐项恢复附件、工具或自动重试。客户端配置保存后重新打开会话，避免旧会话仍使用先前供应商。

怎样确认本节已经学会

不要只检查「配置保存成功」提示。你应能说清当前 Base URL、密钥用途、选用模型和请求协议，能在相应控制台核对自己的操作结果。客户端教程以一次实际纯文本响应和对应日志为初步完成标准；账户教程以安全信息完善为标准；计费教程以本金、通道费与 DK 的对应关系核对为标准。

如果出现错误，记录发生时间、HTTP 状态、脱敏错误内容以及实际期待的结果。不要截图整页密钥，也不要把密码和验证码交给其他人。对 401 应先解决认证，对 400 应先解决参数，对 429 应停止密集重试，对 404 应核对请求路径与上游是否实现，不能用重新充值解决所有报错。

一个适合练习的小任务

在自己的测试环境完成本节的最小步骤，用文字记录「原来怎么设置、改了哪一项、看到了什么结果」。不把生产数据、真实付款或不可恢复的命令当练习。遇到超出本节的功能，先查看对应协议教程，再考虑添加功能；一次只变更一个配置，容易判断哪一步导致错误。

下一步与版本边界

返回完整学习地图 · API 站精简配置 · 本站实时状态。

教程于2026年10月9日整理。具体界面与能力可能随客户端和上游版本变化；配置指引不等于所有客户端版本已经实测通过。本站余额消费、QQ / 支付宝登录及已开放通路以实际页面为准；压缩接口此前的上游 404、生图尚无可用渠道等限制不要理解为配置文件能自动消除。

返回社区，继续阅读分享我的经验