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/*라우트는 구현되어 있지만 현재 업스트림이 구성되지 않았습니다. 호출하면 502inference_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 참고).