NNexithDocs
StatusDashboard ↗
Overview & quickstartModel catalogGuidesAPI referenceIntegrationsOAuth2 / OIDC

Chat Completions

POST /v1/chat/completions · OpenAI-compatible

Creates a chat completion. This is Nexith's primary endpoint: OpenAI SDK, Codex, OpenCode, and others can use it directly. On top of the standard fields, Nexith provides a small set of nexith_* extension fields; omit them and behavior falls back entirely to standard OpenAI.


Request#

POST /v1/chat/completions
Authorization: Bearer nx-...
Content-Type: application/json

Body#

Field Type Required Description
model string ✅ nexith-core (alias nexith-8b)
messages array ✅ See the table below
stream bool — Defaults to false
stream_options object — {"include_usage": true} appends a usage frame at the end of the stream
temperature number — 0–2
top_p number — 0–1
max_tokens integer — Total budget for output plus hidden reasoning (when the upstream is a reasoning model)
frequency_penalty number — -2.0–2.0
presence_penalty number — -2.0–2.0
user string — Passed through verbatim; does not participate in authentication or billing
reasoning_effort string — none / low / medium / high
tools array — OpenAI function tool definitions, forwarded verbatim
tool_choice string/object — auto / none / required / a specific function
parallel_tool_calls bool — Whether multiple tool calls are allowed in one turn

messages#

role content
system string or parts
user string or parts (parts may contain text, image_url)
assistant string, or with tool_calls
tool Tool result; must carry tool_call_id

Image content block:

{
  "role": "user",
  "content": [
    {"type": "text", "text": "这张图里有什么?"},
    {"type": "image_url", "image_url": {"url": "https://…/cat.png"}}
  ]
}

image_url.url accepts https URLs, data:image/...;base64,..., and nx-file://<id>.

Nexith extension fields#

Field Type Description
nexith_capability string Capability hint: code / plan / audit / reason / text / translate; affects internal dispatch only, never price
inject_memory bool Retrieve this user/app's long-term memory and inject it into the system context
return_memory bool Return matched memory candidates in the response's nexith.memory (non-streaming only)
remember bool Asynchronously extract facts into long-term memory after answering (non-streaming only)
nexith_detect_media bool Detect image-generation intent in the same L1 classification pass; returns nexith.image_request on a match
nexith_web_search bool Let L1 automatically run a web search and inject the results when it decides live information is needed
nexith_deep_research bool Run single-round agentic deep research (plan → search → fetch page bodies → compress → synthesize)
nexith_coordination bool Enable planning/review context for client-managed tool loops (the gateway does not execute tools)

These fields are not forwarded upstream, and they are not part of the compatibility promise behind GET /v1/models; when omitted, behavior is exactly that of standard OpenAI.


Response (non-streaming)#

{
  "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 is an optional object that appears only when the corresponding extension is enabled and matched.
  • Tool calls are returned in message.tool_calls, in the same format as OpenAI.

Response (streaming)#

With stream=true, returns text/event-stream; see Streaming protocol for the frame format and terminator.


Examples#

Basic#

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": "你好"}]
  }'

Tool calling#

{
  "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"
}

Streaming + usage#

{
  "model": "nexith-core",
  "messages": [{"role": "user", "content": "写一段 100 字的介绍"}],
  "stream": true,
  "stream_options": {"include_usage": true}
}

Behavior notes#

  • Automatic escalation: difficult tasks may be escalated internally to a stronger upstream, but the model ID, billing, and identity guardrails always follow nexith-core; callers notice nothing.
  • Semantic cache: equivalent single-turn questions may hit the cache; cache hits are billed at the cached input price, and the response body is the same as a normal answer.
  • Context: inputs over 1,048,576 tokens are trimmed (the system message, the first user message, and the most recent content are kept) rather than returning an error.
  • Errors: see Errors and rate limiting.