NNexithDocs
상태대시보드 ↗
개요 및 빠른 시작모델 카탈로그가이드API 레퍼런스연동OAuth2 / OIDC

Nexith API 문서

버전: v1 · 업데이트: 2026-11-19 적용 대상: https://api.nexith.ai/v1 (동등한 별칭 https://gateway.nexith.ai/v1)

Nexith는 OpenAI 호환 추론 게이트웨이를 제공합니다. 채팅, Responses, Anthropic Messages, 이미지 생성/편집, 비동기 작업(job), 파일 업로드와 대화 동기화가 모두 동일한 /v1 인터페이스와 동일한 API Key를 사용합니다. 그 위에 소수의 nexith_* 요청 필드와 nexith.* 응답 프레임이 웹 검색, 이미지 생성 의도 인식, 장기 메모리 등 플랫폼 기능을 제공합니다. 이러한 필드를 포함하지 않는 일반 OpenAI 클라이언트의 동작은 전혀 바뀌지 않습니다.


문서 맵#

섹션 내용
모델 카탈로그 사용 가능한 모델, 기능, 컨텍스트, 가격
nexith-core 텍스트/추론/비전 주력 모델
nexith-image 이미지 생성 및 편집
가격 텍스트 token, 캐시, 이미지 과금 기준
지원 종료 기록 지원 종료된 모델과 마이그레이션 방법
스트리밍 프로토콜 SSE 프레임 형식, nexith.* 사이드 채널 프레임
이미지 가이드 생성/편집/비동기 작업 전체 흐름
오류와 속도 제한 오류 코드, HTTP 상태, 429와 재시도
Chat Completions POST /v1/chat/completions
Responses POST /v1/responses
Messages POST /v1/messages(Anthropic 호환)
Images POST /v1/images/generations, /v1/images/edits
Jobs 비동기 작업 조회, 취소, SSE
Files POST /v1/files
Conversations 대화 동기화 CRUD
Models GET /v1/models

Base URL#

환경 Base URL 설명
프로덕션(권장) https://api.nexith.ai/v1 OpenAI 스타일 단일 도메인, 모든 모델 엔드포인트 사용 가능
프로덕션(별칭) https://gateway.nexith.ai/v1 권장 주소와 동작이 완전히 동일
로컬 개발 http://localhost:8080/v1 gateway 직접 연결

api.nexith.ai는 콘솔 BFF(/v1/billing, /v1/api-keys, /v1/admin 등)도 함께 제공합니다. 이들은 모델 엔드포인트가 아니며 이 문서의 범위가 아닙니다.


인증#

모든 /v1 모델 엔드포인트에는 인증이 필요합니다. 두 가지 자격 증명을 지원합니다:

방식 Header 적용 대상
API Key(권장) Authorization: Bearer nx-... 모든 엔드포인트
JWT(로그인 세션) Authorization: Bearer eyJ... 모든 엔드포인트(chat 사이트 내부 사용)
Anthropic 방식 x-api-key: nx-... /v1/messages, /v1/messages/count_tokens 전용

API Key는 개발자 콘솔(platform.nexith.ai)에서 생성하며 nx-xxxxxxxx 형태입니다. Key의 권한, RPM/TPM, 잔액은 모두 서버 기록을 기준으로 합니다. 요청에 포함된 user 필드는 업스트림으로 그대로 전달되는 메타데이터일 뿐이며, 인증이나 과금 귀속에 관여하지 않습니다.

/v1/images/edits는 chat 사이트 전용 이미지 편집 엔드포인트입니다. JWT만 허용하며 nx- Key는 일괄 403입니다.


빠른 시작#

curl#

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": "用一句话解释什么是向量数据库"}]
  }'

OpenAI Python SDK#

from openai import OpenAI

client = OpenAI(
    api_key="nx-...",
    base_url="https://api.nexith.ai/v1",
)

resp = client.chat.completions.create(
    model="nexith-core",
    messages=[{"role": "user", "content": "hello"}],
)
print(resp.choices[0].message.content)

이미지 생성(비동기 작업)#

# 1) 提交作业
curl https://api.nexith.ai/v1/images/generations \
  -H "Authorization: Bearer $NEXITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nexith-image", "prompt": "a red apple on a white table"}'
# → 202 {"id": 123, "status": "pending", ...}

# 2) 轮询(或订阅 /v1/jobs/123/events)
curl https://api.nexith.ai/v1/jobs/123 \
  -H "Authorization: Bearer $NEXITH_API_KEY"
# → {"status":"completed","artifacts":["https://..."]}

엔드포인트 개요#

메서드 경로 설명 문서
POST /v1/chat/completions OpenAI Chat Completions 상세
POST /v1/responses OpenAI Responses 어댑터(Codex 등) 상세
POST /v1/messages Anthropic Messages 어댑터(Claude Code) 상세
POST /v1/messages/count_tokens Anthropic token 카운트 상세
GET /v1/models 사용 가능한 모델 목록 상세
POST /v1/images/generations 이미지 생성 작업 제출 상세
POST /v1/images/edits 이미지 편집 작업 제출(JWT 전용) 상세
GET /v1/jobs/:id 작업 상태와 산출물 상세
GET /v1/jobs/:id/events 작업 이벤트 SSE 상세
POST /v1/jobs/:id/cancel 작업 취소 상세
POST /v1/files 이미지 업로드, nx-file:// 참조 반환 상세
GET/POST /v1/conversations 대화 목록 / 생성 상세
GET/PATCH/DELETE /v1/conversations/:id 대화 조회 / 업데이트 / 삭제 상세

/v1/embeddings, /v1/audio/* 라우트는 구현되어 있지만 현재 업스트림이 구성되지 않았습니다. 호출하면 502 inference_unavailable을 반환하며, 공개 문서에서 아직 약속하지 않습니다. 출시 후 별도로 공지합니다.


호환성#

클라이언트 연동 방식 설명
OpenAI SDK base_url=https://api.nexith.ai/v1 Chat Completions / Responses 모두 사용 가능
Codex CLI wire_api = "responses" Responses 참고
Claude Code ANTHROPIC_BASE_URL=https://api.nexith.ai Messages 참고
OpenCode / 기타 OpenAI Chat 호환 Chat Completions 참고

규약#

  • 금액 단위: 문서와 API의 가격은 모두 USD이며, 과금 내부에서는 마이크로달러(1e-6 USD) 정수로 기록합니다.
  • 시간: 모든 타임스탬프는 Unix 초(created) 또는 RFC3339 UTC 문자열입니다.
  • 오류 형식: {"error":{"message","type","code"}}로 통일되어 있습니다. 오류와 속도 제한을 참고하세요.
  • 스트리밍: text/event-stream이며, 프레임은 data: <json>으로 전송되고 data: [DONE]으로 끝납니다.
  • 불투명성: 업스트림 공급자, 실제 모델 이름, 내부 오류 원문은 응답에 나타나지 않습니다. 작업 실패 시 불투명한 사유만 반환합니다(Jobs 참고).