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 메시지, 최근 내용 유지), 오류를 내지 않습니다.
- 오류: 오류와 속도 제한을 참고하세요.