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/jsonBody#
| 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": "…"}]
}
}nexithis 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.