OpenAI 兼容-Chat
用 OpenAI Chat Completions 协议调用平台上的文本模型。已有 OpenAI SDK 或兼容 OpenAI 的工具,只需把 Base URL 换成 https://www.nextai-code.com/v1、API Key 换成平台的 API Key 即可。Claude、Gemini 等非 OpenAI 模型也能通过这个接口调用,平台会自动转换协议。
| 项 | 值 |
|---|---|
| 方法与路径 | POST /v1/chat/completions |
| 鉴权 | Authorization: Bearer YOUR_API_KEY |
| Content-Type | application/json |
| 流式 | stream: true 时返回 text/event-stream(SSE) |
快速示例
示例模型名仅作演示,可用模型以 GET /v1/models 返回为准。
cURL
curl https://www.nextai-code.com/v1/chat/completions \
-H "Authorization: Bearer $NEXTAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-v4.1-flash",
"messages": [
{"role": "system", "content": "你是一个简洁的助手。"},
{"role": "user", "content": "用一句话介绍你自己。"}
]
}'
Python
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["NEXTAI_API_KEY"],
base_url="https://www.nextai-code.com/v1",
)
completion = client.chat.completions.create(
model="deepseek-v4.1-flash",
messages=[
{"role": "system", "content": "你是一个简洁的助手。"},
{"role": "user", "content": "用一句话介绍你自己。"},
],
)
print(completion.choices[0].message.content)
Node.js
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.NEXTAI_API_KEY,
baseURL: "https://www.nextai-code.com/v1",
});
const completion = await client.chat.completions.create({
model: "deepseek-v4.1-flash",
messages: [
{ role: "system", content: "你是一个简洁的助手。" },
{ role: "user", content: "用一句话介绍你自己。" },
],
});
console.log(completion.choices[0].message.content);
请求参数
参数遵循 OpenAI Chat Completions 规范。调用 Claude、Gemini 等非 OpenAI 模型时,平台会转换能对应上的参数,对应不上的参数会被忽略。标注「透传」的参数会原样发给模型服务商,是否生效取决于模型。请只使用下列表格中的参数,不在表中的字段不保证会被转发。
核心参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model |
string | 是 | 模型名称。缺失时返回 400 未指定模型名称,模型名称不能为空。 |
messages |
array | 是 | 对话消息列表,结构见下方 messages。为空时返回 400 messages 字段不能为空(FIM 补全请求带 prefix / suffix 时可省略)。 |
stream |
boolean | 否 | 是否以 SSE 流式返回,默认 false。见 流式输出。 |
stream_options |
object | 否 | 仅 stream: true 时有效。平台默认在流末尾返回用量;传 {"include_usage": false} 可关闭。 |
max_tokens |
integer | 否 | 最大输出 token 数。实际上限以模型为准。 |
max_completion_tokens |
integer | 否 | 最大输出 token 数(含推理 token),同时设置时优先于 max_tokens。o 系列和 gpt-5 系列模型只传 max_tokens 也可以,平台会按 max_completion_tokens 处理。 |
temperature |
number | 否 | 采样温度。o 系列和 gpt-5 系列不支持该参数,传了会被忽略。 |
top_p |
number | 否 | 核采样。传 0 等同于不传。 |
top_k |
integer | 否 | Top-K 采样。对 Claude 等原生支持该参数的模型生效;OpenAI 官方模型不支持。 |
stop |
string | array | 否 | 停止序列。 |
n |
integer | 否 | 生成的候选数。透传。 |
seed |
number | 否 | 随机种子。透传。 |
frequency_penalty |
number | 否 | 频率惩罚。透传。 |
presence_penalty |
number | 否 | 存在惩罚。透传。 |
logit_bias |
object | 否 | token 偏置。透传。 |
logprobs |
boolean | 否 | 是否返回 logprobs。透传。 |
top_logprobs |
integer | 否 | 每个位置返回的候选数。透传。 |
user |
string | 否 | 终端用户标识。透传。 |
工具与输出格式
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
tools |
array | 否 | 工具列表,每项为 {"type": "function", "function": {"name", "description", "parameters"}}。见 Function Calling。 |
tool_choice |
string | object | 否 | auto / none / required,或用 {"type": "function", "function": {"name": "..."}} 指定某个函数。 |
parallel_tool_calls |
boolean | 否 | 是否允许并行调用工具。 |
functions |
array | 否 | 旧版函数调用字段,建议改用 tools。透传。 |
response_format |
object | 否 | 输出格式:{"type": "text"}、{"type": "json_object"},或 {"type": "json_schema", "json_schema": {...}}。见 结构化输出。 |
推理与思考
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
reasoning_effort |
string | 否 | 推理强度,常用 low / medium / high。不同模型的效果见 深度思考。 |
reasoning |
object | 否 | OpenRouter 风格的推理配置,例如 {"effort": "high"} 或 {"max_tokens": 2048}。调用 Claude 时,max_tokens 即思考预算。 |
thinking |
object | 否 | 思考开关,例如 {"type": "enabled"}。适用于豆包、智谱等支持该字段的模型。 |
enable_thinking |
boolean | 否 | 阿里通义千问的思考开关。 |
verbosity |
string | 否 | gpt-5 系列的输出详略程度。透传。 |
其他
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
modalities / audio |
array / object | 否 | 音频输出相关字段。透传。 |
prediction |
object | 否 | 预测输出。透传。 |
metadata |
object | 否 | 元数据。透传。 |
prompt_cache_key |
string | 否 | OpenAI 提示缓存键。透传。 |
store |
boolean | 否 | 是否让模型服务商存储本次对话。平台不保证转发,请勿依赖。 |
service_tier |
string | 否 | 服务层级。平台不保证转发,请勿依赖它切换服务等级。 |
safety_identifier |
string | 否 | OpenAI 安全标识。平台不保证转发,请勿依赖。 |
web_search_options |
object | 否 | 联网搜索选项,search_context_size 可选 low / medium / high(默认 medium),传其他值返回 400。调用 Claude 时会开启 Claude 的联网搜索工具。 |
extra_body |
object | 否 | 请求体中名为 extra_body 的字段,目前用于 Gemini 思考配置:{"google": {"thinking_config": {"thinking_budget": 2048, "include_thoughts": true}}}。用 Python SDK 传法见 深度思考。 |
prefix / suffix |
string | 否 | FIM(中间补全)请求使用,仅对支持的模型(如 DeepSeek、硅基流动)有效。 |
messages
| 字段 | 类型 | 说明 |
|---|---|---|
role |
string | system / developer / user / assistant / tool。调用 o 系列(早期 mini、preview 版本除外)和 gpt-5 系列模型时,首条 system 消息按 developer 处理。 |
content |
string | array | 纯文本,或内容块数组。内容块 type 可为 text、image_url、input_audio、file、video_url(视频理解,仅部分模型支持)。 |
name |
string | 可选,参与者名称。 |
tool_calls |
array | assistant 消息中模型发起的工具调用,回传历史时原样带上。 |
tool_call_id |
string | tool 消息必填,对应 tool_calls[].id。 |
reasoning_content |
string | assistant 消息中的思考内容,回传历史时可带上(如 DeepSeek 多轮工具调用)。 |
响应
非流式
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1762560000,
"model": "deepseek-v4.1-flash",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "我是一个 AI 助手,可以回答问题、写作和编程。"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 25,
"completion_tokens": 18,
"total_tokens": 43,
"prompt_tokens_details": { "cached_tokens": 0 },
"completion_tokens_details": { "reasoning_tokens": 0 }
}
}
| 字段 | 类型 | 说明 |
|---|---|---|
id |
string | 本次响应 ID。 |
object |
string | 固定 chat.completion。 |
created |
integer | Unix 时间戳(秒)。 |
model |
string | 实际返回的模型名,可能与请求的 model 不完全一致(如带日期版本号)。 |
choices[].index |
integer | 候选序号。 |
choices[].message.role |
string | 固定 assistant。 |
choices[].message.content |
string | null | 回复正文;只调用工具时可能为 null。 |
choices[].message.reasoning_content |
string | 思考内容,仅思考模型返回。部分模型用 reasoning 字段返回,建议两个都兼容。 |
choices[].message.tool_calls |
array | 模型请求调用的工具,见 Function Calling。 |
choices[].finish_reason |
string | stop(自然结束或命中停止序列)、length(达到长度上限)、tool_calls(需要调用工具)、content_filter 等。 |
usage.prompt_tokens |
integer | 输入 token 数,包含缓存命中部分。 |
usage.completion_tokens |
integer | 输出 token 数,包含推理 token。 |
usage.total_tokens |
integer | 合计。 |
usage.prompt_tokens_details.cached_tokens |
integer | 命中缓存的输入 token 数。 |
usage.completion_tokens_details.reasoning_tokens |
integer | 推理 token 数。 |
模型服务商未返回用量时,平台会按文本估算
usage;计费以控制台用量日志为准。
流式
stream: true 时返回 SSE。每个事件是一行 data: {chunk},以 data: [DONE] 结束:
data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1762560000,"model":"deepseek-v4.1-flash","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}
data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1762560000,"model":"deepseek-v4.1-flash","choices":[{"index":0,"delta":{"content":"我是"},"finish_reason":null}]}
data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1762560000,"model":"deepseek-v4.1-flash","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1762560000,"model":"deepseek-v4.1-flash","choices":[],"usage":{"prompt_tokens":25,"completion_tokens":18,"total_tokens":43}}
data: [DONE]
| 字段 | 说明 |
|---|---|
object |
固定 chat.completion.chunk。 |
choices[].delta.content |
本块新增的正文。 |
choices[].delta.reasoning_content |
本块新增的思考内容(部分模型为 reasoning)。 |
choices[].delta.tool_calls |
工具调用增量,按 index 拼接 function.arguments。 |
choices[].finish_reason |
最后一个内容块给出结束原因,其余为 null。 |
usage |
只在用量块中出现,此时 choices 为空数组。 |
- 流中可能出现以
:开头的注释行(如: PING),是平台的保活心跳,SSE 客户端会自动忽略,自己解析时跳过即可。 - 流式中途出错时,平台会发送
data: {"error": {...}}后紧跟data: [DONE],此时 HTTP 状态码已是 200,请检查事件内容判断是否出错。格式见 错误码。
进阶用法
流式输出
Python
stream = client.chat.completions.create(
model="deepseek-v4.1-flash",
messages=[{"role": "user", "content": "写一首四行短诗"}],
stream=True,
stream_options={"include_usage": True},
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
if chunk.usage: # 最后的用量块,choices 为空
print("\n用量:", chunk.usage.total_tokens)
Node.js
const stream = await client.chat.completions.create({
model: "deepseek-v4.1-flash",
messages: [{ role: "user", content: "写一首四行短诗" }],
stream: true,
stream_options: { include_usage: true },
});
for await (const chunk of stream) {
const delta = chunk.choices[0]?.delta?.content;
if (delta) process.stdout.write(delta);
if (chunk.usage) console.log("\n用量:", chunk.usage.total_tokens);
}
关于 stream_options.include_usage:
- 不传
stream_options或传{"include_usage": true}:流末尾返回用量块。 - 传
{"include_usage": false}:通常不单独返回用量块,但个别模型仍可能在流中附带usage,客户端不要假定它一定不存在。 - 用量块的
choices是空数组,先判断再取choices[0]。
视觉输入
在 content 中传 image_url 内容块。url 可以是公网可访问的图片地址,也可以是 Base64 Data URL(data:image/png;base64,...)。detail 可选 low / high / auto。
completion = client.chat.completions.create(
model="deepseek-v4.1-flash",
messages=[{
"role": "user",
"content": [
{"type": "text", "text": "图里有什么?"},
{"type": "image_url", "image_url": {"url": "https://example.com/cat.jpg", "detail": "auto"}},
],
}],
)
print(completion.choices[0].message.content)
- 调用 Claude、Gemini 等模型时,平台会先下载图片再发给模型,因此 URL 必须能被公网访问;内网地址或需要登录的地址请改用 Data URL。
- 模型是否支持图片输入以模型本身能力为准,纯文本模型传图会报错或忽略图片。
深度思考
思考模型的思考过程放在 reasoning_content 字段(非流式在 message 里,流式在 delta 里),正文仍在 content。部分模型使用 reasoning 字段名,建议两个都兼容:
stream = client.chat.completions.create(
model="deepseek-v4.1-flash",
messages=[{"role": "user", "content": "9.11 和 9.9 哪个大?"}],
stream=True,
)
for chunk in stream:
if not chunk.choices:
continue
delta = chunk.choices[0].delta
thinking = getattr(delta, "reasoning_content", None) or getattr(delta, "reasoning", None)
if thinking:
print(thinking, end="", flush=True)
if delta.content:
print(delta.content, end="", flush=True)
少数情况下思考内容会以
<think>…</think>标签包裹出现在content开头,而reasoning_content为空。需要区分正文时,建议同时处理这种形式。
开启和控制思考有三种写法,按模型选用:
1. reasoning_effort(推荐,通用)
| 模型 | 效果 |
|---|---|
OpenAI o 系列 / gpt-5 系列 |
直接生效,取值以 OpenAI 文档为准(如 minimal / low / medium / high)。 |
| Claude | 开启思考,思考预算:low = 1280、medium = 2048、high = 4096 tokens。max_tokens 需大于思考预算。 |
| 通过 OpenRouter 提供的模型 | 等价于 reasoning: {"effort": ...}。 |
| Gemini | 不生效。请用下文的 extra_body.google.thinking_config 控制思考。 |
| 其他模型 | 透传,是否生效取决于模型。 |
completion = client.chat.completions.create(
model="claude-sonnet-5-5",
messages=[{"role": "user", "content": "证明根号 2 是无理数"}],
reasoning_effort="medium",
max_tokens=8000,
)
msg = completion.choices[0].message
print(getattr(msg, "reasoning_content", None))
print(msg.content)
2. 模型原生字段
| 字段 | 适用模型 | 示例 |
|---|---|---|
reasoning |
Claude(max_tokens 即思考预算,优先级高于 reasoning_effort)、OpenRouter |
{"max_tokens": 4096} |
thinking |
豆包、智谱等 | {"type": "enabled"} |
enable_thinking |
阿里通义千问 | true |
extra_body.google.thinking_config |
Gemini | {"thinking_budget": 2048, "include_thoughts": true} |
这些字段 SDK 没有声明。Python SDK 用 extra_body 传,它会把内容合并进请求体顶层;而 Gemini 需要请求体里有一个名为 extra_body 的字段,所以 Python 要写两层 extra_body。Node.js SDK 直接把字段写进请求对象即可(TypeScript 可能需要 // @ts-expect-error)。
completion = client.chat.completions.create(
model="gemini-3.8-flash",
messages=[{"role": "user", "content": "解释一下快速排序"}],
extra_body={"extra_body": {"google": {"thinking_config": {"thinking_budget": 2048, "include_thoughts": True}}}},
)
const completion = await client.chat.completions.create({
model: "gemini-3.8-flash",
messages: [{ role: "user", content: "解释一下快速排序" }],
extra_body: { google: { thinking_config: { thinking_budget: 2048, include_thoughts: true } } },
});
同理,reasoning / thinking / enable_thinking 在 Python 中写成 extra_body={"thinking": {"type": "enabled"}}(一层即可,因为它们本身就是请求体顶层字段)。
Gemini 的
thinking_config字段名必须是下划线写法;写成thinkingConfig/thinkingBudget会直接返回错误。
3. 模型名后缀
部分模型可以通过模型名后缀开启思考,前提是带后缀的模型名出现在 GET /v1/models 返回中:
| 后缀 | 适用模型 | 效果 |
|---|---|---|
-thinking |
Claude,模型名加 -thinking 后缀 |
开启思考,思考预算按 max_tokens 的一部分分配(max_tokens 至少按 1280 计);此时 temperature 固定为 1,top_p 不生效。 |
-high / -medium / -low / -minimal |
OpenAI o 系列 / gpt-5 系列 |
等价于设置对应的 reasoning_effort。 |
Function Calling
完整流程:带上 tools 请求 → 模型返回 tool_calls → 你执行函数 → 把结果作为 role: "tool" 消息追加 → 再次请求拿到最终回答。
import json
tools = [{
"type": "function",
"function": {
"name": "get_weather",
"description": "查询城市天气",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string", "description": "城市名"}},
"required": ["city"],
},
},
}]
messages = [{"role": "user", "content": "北京今天天气怎么样?"}]
first = client.chat.completions.create(model="deepseek-v4.1-flash", messages=messages, tools=tools)
msg = first.choices[0].message
if msg.tool_calls:
messages.append(msg) # 带上 assistant 的 tool_calls
for call in msg.tool_calls:
args = json.loads(call.function.arguments)
result = {"city": args["city"], "weather": "晴", "temp": 22} # 替换成你的实现
messages.append({
"role": "tool",
"tool_call_id": call.id,
"content": json.dumps(result, ensure_ascii=False),
})
final = client.chat.completions.create(model="deepseek-v4.1-flash", messages=messages, tools=tools)
print(final.choices[0].message.content)
响应中的 tool_calls 结构:
{
"role": "assistant",
"content": null,
"tool_calls": [
{
"id": "call_abc123",
"type": "function",
"function": { "name": "get_weather", "arguments": "{\"city\":\"北京\"}" }
}
]
}
finish_reason为tool_calls时表示需要调用工具。function.arguments是 JSON 字符串,需要自行解析。- 流式模式下,参数分多块到达,按
tool_calls[].index拼接function.arguments。 - 调用 Claude 时,
tool_choice与parallel_tool_calls同样生效。
结构化输出
用 response_format 约束输出为 JSON:
{"type": "json_object"}:输出合法 JSON。多数模型要求提示词中出现“JSON”字样。{"type": "json_schema", "json_schema": {...}}:按给定 Schema 输出。
completion = client.chat.completions.create(
model="deepseek-v4.1-flash",
messages=[{"role": "user", "content": "提取:张三,28 岁,住在上海"}],
response_format={
"type": "json_schema",
"json_schema": {
"name": "person",
"strict": True,
"schema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"age": {"type": "integer"},
"city": {"type": "string"},
},
"required": ["name", "age", "city"],
"additionalProperties": False,
},
},
},
)
print(completion.choices[0].message.content) # JSON 字符串
const completion = await client.chat.completions.create({
model: "deepseek-v4.1-flash",
messages: [{ role: "user", content: "提取:张三,28 岁,住在上海" }],
response_format: { type: "json_object" },
});
console.log(JSON.parse(completion.choices[0].message.content));
| 模型 | 支持情况 |
|---|---|
| OpenAI 及兼容 OpenAI 的模型 | 按 OpenAI 规范生效。 |
| Gemini | json_object / json_schema 均生效;Schema 中的 additionalProperties 会被忽略。 |
| Claude | response_format 不生效。需要 JSON 时请在提示词中约束,或改用 Function Calling。 |
错误
本接口特有的错误:
| HTTP 状态码 | 错误信息 | 原因 |
|---|---|---|
| 400 | 未指定模型名称,模型名称不能为空 |
请求体没有 model。 |
| 400 | messages 字段不能为空 |
messages 为空且未传 prefix / suffix。 |
| 400 | max_tokens 参数不合法 |
max_tokens 数值异常(远超任何模型上限)。请按模型实际上限设置。 |
| 400 | search_context_size 参数不合法,可选值:high、medium、low |
web_search_options.search_context_size 取值不对。 |
| 400 | 请求体格式错误,请检查 JSON |
请求体不是合法 JSON,或字段类型不对(例如 max_tokens 传了字符串)。 |
错误响应格式为 {"error": {"message", "type", "param", "code"}}。通用错误(鉴权、余额、限流、模型不可用等)见 错误码。