POST https://api.wylon.cn/v1/chat/completions

Chat Completions

基于一组消息生成模型回复。与 OpenAI 协议完全兼容；流式输出、函数调用与结构化输出通过请求参数控制。

cURL：最小调用

curl https://api.wylon.cn/v1/chat/completions \
  -H "Authorization: Bearer $WYLON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ZhipuAI/GLM-5.3",
    "messages": [{"role": "user", "content": "用一句话解释 KV 缓存。"}]
  }'

鉴权

Authorization string · header 必填

Bearer 令牌。可前往控制台创建 API 密钥，并将其保存为环境变量 $WYLON_API_KEY。

请求参数

Content-Type: application/json

model string 必填

调用的模型 ID，例如 ZhipuAI/GLM-5.3。可用模型列表见模型目录或调用列出模型接口。

messages array 必填

有序的对话轮次，每项为带 role 与 content 的对象。

role enum 必填

取值 system、user、assistant 或 tool。

content string · array 必填

文本内容；视觉语言模型支持 {type, text|image_url} 数组形式的多模内容块。

tool_call_id string 可选

仅当 role="tool" 时使用，关联到上一轮 assistant 发起的工具调用 ID。

stream boolean false

为 true 时以 SSE 流（text/event-stream）逐 Token 返回；末尾以 data: [DONE] 结束。

temperature number 可选

采样温度，范围 0-2。值越高回答越随机；建议与 top_p 二选一调节。

top_p number 可选

核采样阈值，范围 0-1。仅从累计概率达到 top_p 的最小候选集合中采样。

top_k integer 可选

每步从概率最高的 K 个候选中采样；0 表示不限制。

max_tokens integer 可选

本次生成的最大 Token 数，不可超过模型的上下文窗口。未设置时使用模型默认上限。

n integer 1

为同一组消息返回 N 个候选回复。注意计费按 n × completion_tokens 计算。

stop string · array 可选

最多 4 个停止序列，命中即截断输出。

presence_penalty number 0

范围 -2.0-2.0。正值减少重复主题，鼓励引入新话题。

frequency_penalty number 0

范围 -2.0-2.0。正值按词频惩罚，抑制逐字重复。

seed integer 可选

尽力而为的确定性采样种子，相同输入可复现相同输出。

tools array 可选

模型可调用的函数定义集合。每项为 {type: "function", function: {name, description, parameters}}。详见函数调用。

tool_choice string · object "auto"

控制工具调用："auto" 由模型决定；"none" 禁用；"required" 强制至少一次；或指定 {type:"function", function:{name:"..."}} 强制调用某个函数。

response_format object 可选

强制响应格式：{type:"json_object"} 或 {type:"json_schema", json_schema:{...}}。详见结构化输出。

logprobs boolean false

是否在响应中返回每个采样 Token 的对数概率。

top_logprobs integer 可选

当 logprobs 为 true 时返回每步前 N 个候选的概率，范围 0-20。

user string 可选

终端用户的稳定标识，用于滥用监控与组织级审计。

响应结构

非流式：返回 chat.completion 对象。
流式（stream=true）：以 SSE 形式逐块返回 chat.completion.chunk，末尾以 data: [DONE] 终止。

idstring

本次请求的唯一标识。

objectstring

固定为 chat.completion 或 chat.completion.chunk（流式）。

createdinteger

UNIX 时间戳（秒）。

modelstring

实际服务该请求的模型 ID。

choicesarray

候选回复列表。

indexinteger

候选序号，从 0 开始。

messageobject

非流式时返回完整 {role, content, tool_calls?}。

deltaobject

流式时返回的增量内容片段。

finish_reasonenum

stop / length / tool_calls / content_filter。

usageobject

Token 用量统计。

prompt_tokensinteger

输入 Token 数。

completion_tokensinteger

输出 Token 数。

total_tokensinteger

合计 Token 数。

cache_hit_rationumberwylon 扩展

本次请求命中系统级上下文缓存的比例（0-1）。重复前缀越多，比例越高、计费越优。

示例响应

{
  "id": "cmpl-9f1c7b2e8a41",
  "object": "chat.completion",
  "created": 1744828800,
  "model": "ZhipuAI/GLM-5.3",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "KV cache stores …" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 128,
    "total_tokens": 152,
    "cache_hit_ratio": 0.71
  }
}

参数错误、鉴权失败或触发速率限制。响应体为 OpenAI 兼容错误信封。

error.typestring

错误大类，如 invalid_request_error、authentication_error、rate_limit_exceeded。

error.messagestring

人类可读的错误说明。

error.codestring

细分错误码（可选），便于程序判断。

示例：429 限流

{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Rate limit reached for ZhipuAI/GLM-5.3 on tier 2.",
    "retry_after": 3.4
  }
}

服务端瞬时故障。建议带抖动的指数退避重试。

示例：503

{
  "error": {
    "type": "server_overloaded",
    "message": "Upstream model is temporarily unavailable, please retry."
  }
}

错误码与处理建议

请求失败时，接口会返回 OpenAI 兼容的错误体。建议同时检查 HTTP 状态码以及响应中的 error.type、error.code 和 error.message。

HTTP 状态码	常见原因	建议操作
`400`	缺少必填字段、字段类型或取值不正确、模型 ID 不可用	根据 `error.message` 修正请求参数，不要直接重试原请求
`401`	API 密钥缺失、无效或已撤销	检查 `Authorization: Bearer ...` 请求头和密钥状态
`403`	当前身份没有模型或接口访问权限	检查 API 密钥所属账户、用户等级及模型权限
`429`	请求频率、并发或 Token 用量达到限制	按照 `retry_after` 或 `Retry-After` 等待，并使用带抖动的指数退避重试
`500`、`503`	服务内部异常或上游模型暂时不可用	稍后使用带抖动的指数退避重试；持续失败时记录错误信息并联系支持

仅建议自动重试 429 和临时性 5xx 错误。排查时请记录 HTTP 状态码与公开错误字段，不要记录或提交完整 API 密钥。