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