Chat Completions

对话补全、流式输出、工具调用与结构化输出。

Chat Completions 对话补全

通过 POST /v1/chat/completions 提交消息历史，获得模型的下一条回复。支持普通 JSON 响应和 SSE 流式输出；工具调用、结构化输出、图片等能力取决于所选模型与渠道。

本文以 deepseek-v4-flash 为 WisGate 公开模型名示例。调用前需确认该模型已对当前 API Key 开放。兼容 OpenAI 请求格式不意味着支持 OpenAI 所有模型专属功能。

连接信息

项目	值
HTTP 地址	`https://api.wisgate.cn/v1/chat/completions`
方法	`POST`
鉴权	`Authorization: Bearer YOUR_API_KEY`
请求类型	`Content-Type: application/json`
OpenAI SDK base URL	`https://api.wisgate.cn/v1`

下文假设服务端已经设置环境变量 WISGATE_API_KEY。

最小请求

curl --fail-with-body https://api.wisgate.cn/v1/chat/completions \
  -H "Authorization: Bearer $WISGATE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {"role": "system", "content": "请用简洁的中文回答。"},
      {"role": "user", "content": "解释什么是 API。"}
    ],
    "max_tokens": 1024,
    "stream": false
  }'

响应结构示例，ID、文本和用量为示意值：

{
  "id": "chatcmpl_example",
  "object": "chat.completion",
  "created": 1791504000,
  "model": "deepseek-v4-flash",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "API 是程序之间交换信息的接口。"},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 24, "completion_tokens": 16, "total_tokens": 40}
}

读取 choices[].message.content。调用工具时正文可能为空，需同时检查 message.tool_calls。返回的 model 可能是渠道映射后的名称。usage 是用量信息，不是人民币金额。

消息与多轮对话

字段	类型	要求与含义
`model`	string	必填，使用 WisGate 模型名
`messages`	array	必填且非空，按时间顺序提供对话
`messages[].role`	string	常用 `system`、`user`、`assistant`；工具结果用 `tool`
`messages[].content`	string / array	文本或模型支持的内容块；基础示例使用字符串
`messages[].tool_calls`	array	assistant 发出的函数调用列表
`messages[].tool_call_id`	string	`tool` 消息对应的调用 ID

下一轮应发送所需历史，网关没有为此端点提供自动会话存储：

{
  "model": "deepseek-v4-flash",
  "messages": [
    {"role": "system", "content": "请用简洁的中文回答。"},
    {"role": "user", "content": "解释什么是 API。"},
    {"role": "assistant", "content": "API 是程序之间交换信息的接口。"},
    {"role": "user", "content": "再举一个天气查询的例子。"}
  ]
}

常用控制参数

下列参数的实际支持范围取决于所选模型与渠道。

参数	类型	本平台处理与使用建议
`stream`	boolean	`true` 使用 SSE；省略时非流式
`stream_options.include_usage`	boolean	流式请求可申请用量块；断流时可能收不到
`max_tokens`	integer	输出预算；本页 DeepSeek 示例使用此字段
`max_completion_tokens`	integer	兼容字段，适合要求此名称的模型；不要同时发送两个预算字段
`temperature`	number	采样温度；是否生效及范围由模型决定
`top_p`	number	核采样；建议不要同时调整 temperature 和 top_p
`stop`	string / string[]	停止序列，依赖模型
`frequency_penalty`、`presence_penalty`	number	惩罚参数，依赖模型
`tools`	array	基础函数工具声明，见后文
`tool_choice`	string / object	工具选择策略，依赖模型和适配路径
`parallel_tool_calls`	boolean	并行工具请求开关，不保证上游并行执行
`response_format`	object	JSON 输出或 JSON Schema；需模型支持
`reasoning_effort`、`thinking`	string / object	分别是推理强度和供应商扩展，不能跨模型盲目套用
`seed`、`n`、`logprobs`、`top_logprobs`	number / boolean	字段可解析；支持范围由上游决定，默认不发送

非透传渠道会把请求解码为已知字段再发送。未知字段可能被丢弃；当前普通 Chat 转换路径不保留 tools[].function.strict，请勿依赖该字段实现严格工具 Schema。response_format.json_schema 则保留为原始 JSON，两者不是同一个支持结论。store、safety_identifier 等字段还可能受渠道过滤设置影响。

流式输出

curl --fail-with-body -N https://api.wisgate.cn/v1/chat/completions \
  -H "Authorization: Bearer $WISGATE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "用三句话介绍杭州。"}],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

分片示意（不是完整事件序列）：

data: {"id":"chatcmpl_example","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"杭州"},"finish_reason":null}]}

data: {"id":"chatcmpl_example","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

逐个 SSE 事件解析 choices[].delta.content，不要把一次网络读取当作一个完整 JSON。用量分片可能 choices=[]；工具分片应按调用 index 累积 function.arguments 后再解析 JSON。出现 reasoning_content 时与最终正文分开处理。网络提前关闭不等于生成完成。OpenAI 流式参数参考

函数工具调用

工具由你的服务端执行，网关不会替你运行函数。以下为可合并到请求的完整示例：

{
  "model": "deepseek-v4-flash",
  "messages": [{"role": "user", "content": "杭州现在多少度？"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "查询城市当前天气",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }],
  "tool_choice": "auto"
}

若返回 finish_reason=tool_calls，先校验工具名和参数，再执行允许的函数。将原请求历史、完整 assistant 工具调用消息及每个工具结果一并发送。第二轮结构示例：

{
  "model": "deepseek-v4-flash",
  "messages": [
    {"role": "user", "content": "杭州现在多少度？"},
    {"role": "assistant", "content": null, "tool_calls": [
      {"id": "call_example", "type": "function", "function": {"name": "get_weather", "arguments": "{\"city\":\"杭州\"}"}}
    ]},
    {"role": "tool", "tool_call_id": "call_example", "content": "{\"city\":\"杭州\",\"temperature_c\":24}"}
  ]
}

示例省略了推理内容；真实调用如果返回了上游要求回传的推理字段，应保留原消息，不能只手工重建工具 ID。工具结果示例中的天气为虚构测试数据。

JSON 输出

{
  "model": "deepseek-v4-flash",
  "messages": [
    {"role": "system", "content": "只输出 JSON 对象，包含 city 和 country 两个字符串字段。"},
    {"role": "user", "content": "杭州属于哪个国家？"}
  ],
  "response_format": {"type": "json_object"},
  "max_tokens": 1024
}

平台支持传递 json_object 和 json_schema 格式配置；目标模型是否执行严格 Schema 约束取决于渠道能力。应用仍需处理截断、拒绝、空内容和 JSON 校验失败。

SDK 示例

Python（安装 openai，API Key 从环境变量读取）：

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["WISGATE_API_KEY"], base_url="https://api.wisgate.cn/v1")
response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "解释什么是 API。"}],
    max_tokens=1024,
)
print(response.choices[0].message.content)

JavaScript / TypeScript（安装 openai，在 Node.js 服务端运行）：

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.WISGATE_API_KEY,
  baseURL: "https://api.wisgate.cn/v1",
});
const stream = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [{ role: "user", content: "解释什么是 API。" }],
  stream: true,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

响应与错误处理

字段/情况	处理
`finish_reason=stop`	正常结束
`finish_reason=length`	输出预算不足，正文或 JSON 可能不完整
`finish_reason=tool_calls`	执行工具往返流程
其他 finish_reason	保留原值，按模型文档处理；不要强行视为成功文本
`usage.prompt_tokens/completion_tokens/total_tokens`	请求、生成、总 Token；缓存/推理明细可能另外返回
400 类参数错误	检查 model、messages、参数类型，不要原样无限重试
401 / 403	检查密钥、权限和模型开放范围
429 / 暂时性 5xx	有界退避重试，避免高并发立即重发

典型错误结构为 {"error":{"message":"...","type":"...","code":"..."}}，具体文案和 HTTP 状态可能受渠道映射影响。流已开始后还要处理 SSE 内错误和连接中断。

图片、音频、内置联网搜索和 OpenAI 新增工具类型不列为本页 DeepSeek 示例的已验证能力。参见 Responses 与 Claude Messages 了解其他协议。