NNexithDocs
状态控制台 ↗
概览与快速开始模型目录指南API 参考集成OAuth2 / OIDC

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/json

Body#

字段 类型 必填 说明
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 与最近 内容),不会报错。
  • 错误:见 错误与限流。