推理/对话请求

对话请求

wylon 新云 Token 工厂提供两种兼容协议的对话接口：与 OpenAI Chat Completions 兼容的 /v1/chat/completions，以及与 Anthropic Messages 兼容的 /v1/messages。你向接口提交一组消息，即可获取模型生成的助手回复。本页正文以 OpenAI 协议为主进行说明，Anthropic 接入方式见下文。流式输出、函数调用与结构化输出都通过请求参数开启。整体能力可参考推理概览。

端点

POSThttps://api.wylon.cn/v1/chat/completions

Anthropic Messages 接入

除上面的 OpenAI 协议外，wylon 同时提供与 Anthropic Messages 兼容的端点，可直接使用 Anthropic 官方 SDK——把 base_url 指向 https://api.wylon.cn 即可。

POSThttps://api.wylon.cn/v1/messages

与 OpenAI 协议相比，主要差异：

max_tokens 为必填字段；
系统提示通过顶层 system 字段传入，不放进 messages；
停止序列字段名为 stop_sequences（而非 stop）；
响应为 Anthropic Message 形态：content 内容块数组、stop_reason，以及 usage.input_tokens / output_tokens。

from anthropic import Anthropic
import os

client = Anthropic(
    api_key=os.environ["WYLON_API_KEY"],
    base_url="https://api.wylon.cn",
)

resp = client.messages.create(
    model="moonshotai/Kimi-K2.6",
    max_tokens=512,
    system="你是一名资深工程师。",
    messages=[{"role": "user", "content": "用一句话解释 KV 缓存。"}],
)
print(resp.content[0].text)

curl https://api.wylon.cn/v1/messages \
  -H "x-api-key: $WYLON_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "moonshotai/Kimi-K2.6",
    "max_tokens": 512,
    "system": "你是一名资深工程师。",
    "messages": [{"role": "user", "content": "用一句话解释 KV 缓存。"}]
  }'

完整字段与响应说明见 API 手册对话请求（Anthropic）。

请求参数

请求体为 JSON 对象，支持以下参数：

参数	类型	说明
`model` 必填	string	模型 ID，例如 `moonshotai/Kimi-K2`。可前往模型目录查看可用模型，或调用 `GET /v1/models` 获取模型列表。
`messages` 必填	array	按顺序传入的对话轮次。角色支持 `system`、`user`、`assistant`、`tool`。
`temperature`	number	采样温度，范围 `0`–`2`。值越高，输出越发散。
`top_p`	number	核采样阈值，范围 `0`–`1`。通常与 `temperature` 二选一调节。
`top_k`	integer	每步从概率最高的 K 个候选中采样；`0` 表示不限制。
`max_tokens`	integer	本次最多生成的 Token 数，不可超过模型上下文窗口长度。
`n`	integer	为同一组消息返回 N 个候选回复，默认值为 `1`。
`stream`	boolean	是否以 SSE 流返回增量内容，默认 `false`。详见下文流式输出。
`stop`	string / array	最多设置 4 个停止序列；命中后会立即停止生成。
`presence_penalty`	number	取值 `-2.0` 至 `2.0`。对已出现的 Token 施加惩罚，鼓励模型引入新内容。
`frequency_penalty`	number	取值 `-2.0` 至 `2.0`。按出现频次惩罚 Token，用于减少重复表达。
`seed`	integer	尽力保持确定性的采样种子；相同输入在相同条件下更容易复现结果。
`tools`	array	声明模型可调用的函数。详见函数调用。
`tool_choice`	string / object	控制工具调用策略：`"auto"`（默认）/ `"none"` / `"required"` / 指定函数。
`response_format`	object	约束输出为 JSON 或指定结构。详见结构化输出。
`logprobs`	boolean	是否返回每个采样 Token 的对数概率。
`top_logprobs`	integer	当 `logprobs` 为 `true` 时，返回每步前 N 个候选的概率，取值 `0`–`20`。
`user`	string	终端用户的稳定标识，用于滥用监控与组织层级审计。

info

上表中没有列出 temperature、top_p 等的默认值。不同模型的默认采样配置可能不同，调用前请以模型目录中对应模型的说明。

消息结构

messages 中的每一项都是带有角色和内容的对象。

文本模型: 可以直接传入字符串。
视觉语言模型: 支持多模态输入，可以传入由文本、图片等组成的内容块数组。

{
  "role": "user",
  "content": "什么是检索增强生成（RAG）？"
}

{
  "role": "user",
  "content": [
    {"type": "text", "text": "描述这张图片中的内容。"},
    {"type": "image_url", "image_url": {"url": "https://example.com/cat.jpg"}}
  ]
}

多轮对话

继续对话时，需要把上一轮助手回复和新的用户消息一起追加到 messages 中。模型本身不保存会话状态，历史上下文由你的应用负责维护。

下面示例展示了一个简单的多轮对话循环，使用 Python 或 Node.js SDK 调用接口。

from openai import OpenAI
client = OpenAI(base_url="https://api.wylon.cn/v1", api_key=os.environ["WYLON_API_KEY"])

history = [
    {"role": "system", "content": "你是一位言简意赅的资深工程师。"},
    {"role": "user",   "content": "为内部服务在 REST 与 gRPC 之间做选择。"},
]

while True:
    resp = client.chat.completions.create(model="moonshotai/kimi-k2.5", messages=history)
    reply = resp.choices[0].message.content
    print("助手：", reply)
    history.append({"role": "assistant", "content": reply})
    user = input("你：")
    if not user: break
    history.append({"role": "user", "content": user})

import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://api.wylon.cn/v1", apiKey: process.env.WYLON_API_KEY });

const history = [
  { role: "system", content: "你是一位言简意赅的资深工程师。" },
  { role: "user",   content: "为内部服务在 REST 与 gRPC 之间做选择。" },
];

const resp = await client.chat.completions.create({
  model: "moonshotai/kimi-k2.5", messages: history,
});
history.push(resp.choices[0].message);

流式输出

设置 stream: true 接口可通过 SSE 接收 Token 级增量。客户端可以边接收边展示，最后一个数据块为 [DONE]。

下面示例展示了一个简单的流式输出循环，使用 Python 或 cURL 调用接口。

stream = client.chat.completions.create(
    model="moonshotai/kimi-k2.5",
    messages=[{"role": "user", "content": "写一首关于 GPU 的俳句。"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta: print(delta, end="", flush=True)

curl -N https://api.wylon.cn/v1/chat/completions \
  -H "Authorization: Bearer $WYLON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"moonshotai/kimi-k2.5","messages":[{"role":"user","content":"Write a haiku about GPUs."}],"stream":true}'

响应结构

非流式响应与 OpenAI 协议保持一致。

下面示例展示了一个典型的响应体，包含 cache_hit_ratio 扩展字段。

{
  "id": "cmpl-9f1c7b2e8a41",
  "object": "chat.completion",
  "created": 1744828800,
  "model": "moonshotai/Kimi-K2",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "…" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 128,
    "total_tokens": 152,
    "cache_hit_ratio": 0.71      // wylon 扩展字段
  }
}

cache_hit_ratio 是 wylon 在 OpenAI 协议基础上增加的扩展字段，用于表示本次请求命中系统级上下文缓存的比例。系统提示、长文档等重复前缀越多，命中率通常越高，计费也更有优势。

结束原因

模型生成结束的原因会在响应体中返回 finish_reason 字段，常见值如下。

值	含义
`stop`	模型自然结束或命中自定义的 `stop` 序列。
`length`	达到 `max_tokens` 或模型上下文上限。
`tool_calls`	模型请求一次或多次工具调用。
`content_filter`	输出被内容安全策略拦截。

错误码

请求失败时，接口会返回 OpenAI 兼容的错误体：{"error": {"type": "...", "message": "..."}}。常见 HTTP 状态如下。

状态	含义
`400`	参数错误，例如缺少必填字段、取值越界、模型 ID 不存在等。
`401`	鉴权失败，例如API 密钥无效、被吊销，或未携带 `Authorization` 头等。
`403`	权限不足，例如账户未开通该模型或区域等。
`429`	触发速率限制；响应头会携带 `retry-after`。
`500 / 503`	服务端临时故障，建议使用指数退避重试。