Chat Completions
POST /v1/chat/completions· OpenAI 兼容
创建一次对话补全。这是 Nexith 的主接口:OpenAI SDK、Codex、OpenCode 等都可以直接使用。
在标准字段之上,Nexith 提供少量 nexith_* 扩展字段;不传即完全退化为标准 OpenAI 行为。
请求#
POST /v1/chat/completions
Authorization: Bearer nx-...
Content-Type: application/jsonBody#
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
model |
string | ✅ | nexith-core(别名 nexith-8b) |
messages |
array | ✅ | 见下表 |
stream |
bool | — | 默认 false |
stream_options |
object | — | {"include_usage": true} 在流末尾追加用量帧 |
temperature |
number | — | 0–2 |
top_p |
number | — | 0–1 |
max_tokens |
integer | — | 正文 + 隐藏推理的总预算(上游为推理模型时) |
frequency_penalty |
number | — | -2.0–2.0 |
presence_penalty |
number | — | -2.0–2.0 |
user |
string | — | 原样透传,不参与鉴权/计费 |
reasoning_effort |
string | — | none / low / medium / high |
tools |
array | — | OpenAI function 工具定义,原样转发 |
tool_choice |
string/object | — | auto / none / required / 指定函数 |
parallel_tool_calls |
bool | — | 是否允许一轮多个工具调用 |
messages#
| role | content |
|---|---|
system |
string 或 parts |
user |
string 或 parts(parts 可含 text、image_url) |
assistant |
string,或带 tool_calls |
tool |
工具结果,必须带 tool_call_id |
图片内容块:
{
"role": "user",
"content": [
{"type": "text", "text": "这张图里有什么?"},
{"type": "image_url", "image_url": {"url": "https://…/cat.png"}}
]
}image_url.url 支持 https URL、data:image/...;base64,...、以及 nx-file://<id>。
Nexith 扩展字段#
| 字段 | 类型 | 说明 |
|---|---|---|
nexith_capability |
string | 能力提示:code / plan / audit / reason / text / translate;只影响内部分派,不改价格 |
inject_memory |
bool | 检索该用户/应用的长期记忆并注入 system 上下文 |
return_memory |
bool | 把命中的记忆候选回传到响应 nexith.memory(仅非流式) |
remember |
bool | 回答后异步抽取事实写入长期记忆(仅非流式) |
nexith_detect_media |
bool | 用同一次 L1 分类识别生图意图,命中返回 nexith.image_request |
nexith_web_search |
bool | 允许 L1 判定需要实时资料时自动联网搜索并注入 |
nexith_deep_research |
bool | 走单轮 agentic 深度研究(规划→检索→抓正文→压缩→综合) |
nexith_coordination |
bool | 为客户端自管工具循环开启计划/评审上下文(网关不执行工具) |
这些字段不会转发给上游,也不会出现在
GET /v1/models的兼容性承诺里; 未携带时行为与标准 OpenAI 完全一致。
响应(非流式)#
{
"id": "chatcmpl-8f2a…",
"object": "chat.completion",
"created": 1795055220,
"model": "nexith-core",
"choices": [
{
"index": 0,
"message": {"role": "assistant", "content": "…"},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 320,
"completion_tokens": 2,
"total_tokens": 322,
"prompt_tokens_details": {"cached_tokens": 128},
"completion_tokens_details": {"reasoning_tokens": 0}
},
"nexith": {
"sources": [{"title": "…", "url": "…", "content": "…"}],
"memory": [{"id": "…", "content": "…", "score": 0.83}],
"steps": [{"label": "…", "model": "…", "content": "…"}]
}
}nexith为可选对象,仅当对应扩展开启且命中时出现。- 工具调用返回
message.tool_calls,格式与 OpenAI 一致。
响应(流式)#
stream=true 时返回 text/event-stream,帧格式与结束标记见
流式协议。
示例#
基础#
curl https://api.nexith.ai/v1/chat/completions \
-H "Authorization: Bearer $NEXITH_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "nexith-core",
"messages": [{"role": "user", "content": "你好"}]
}'工具调用#
{
"model": "nexith-core",
"messages": [{"role": "user", "content": "北京现在天气怎么样?"}],
"tools": [{
"type": "function",
"function": {
"name": "get_weather",
"description": "查询城市天气",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"]
}
}
}],
"tool_choice": "auto"
}流式 + 用量#
{
"model": "nexith-core",
"messages": [{"role": "user", "content": "写一段 100 字的介绍"}],
"stream": true,
"stream_options": {"include_usage": true}
}行为说明#
- 自动升级:困难任务可能被内部升级到更强上游执行,但模型 ID、计费与身份护栏
始终按
nexith-core,调用方无感知。 - 语义缓存:等价的单轮问题可能命中缓存;命中时按缓存输入价计费,响应体与普通 回答一致。
- 上下文:超过 1,048,576 tokens 的输入会被裁剪(保留 system、首条 user 与最近 内容),不会报错。
- 错误:见 错误与限流。