Nexith API Documentation
Version: v1 · Updated: 2026-11-19 Applies to:
https://api.nexith.ai/v1(equivalent aliashttps://gateway.nexith.ai/v1)
Nexith provides an OpenAI-compatible inference gateway: chat, Responses, Anthropic Messages,
image generation and editing, async jobs, file uploads, and conversation sync all use the same
/v1 endpoints and the same API keys. On top of that, a small set of nexith_* request fields and
nexith.* response frames expose platform capabilities such as web search, image-intent detection,
and long-term memory; ordinary OpenAI clients that do not send these fields behave exactly as
before.
Documentation map#
| Section | Contents |
|---|---|
| Model catalog | Available models, capabilities, context, pricing |
| nexith-core | Primary text/reasoning/vision model |
| nexith-image | Image generation and editing |
| Pricing | Text tokens, caching, image billing |
| Deprecations | Retired models and migration paths |
| Streaming protocol | SSE frame format, nexith.* side-channel frames |
| Image guide | Complete generation/edit/async job flow |
| Errors and rate limiting | Error codes, HTTP statuses, 429 and retries |
| Chat Completions | POST /v1/chat/completions |
| Responses | POST /v1/responses |
| Messages | POST /v1/messages (Anthropic-compatible) |
| Images | POST /v1/images/generations, /v1/images/edits |
| Jobs | Async job lookup, cancellation, SSE |
| Files | POST /v1/files |
| Conversations | Conversation sync CRUD |
| Models | GET /v1/models |
Base URL#
| Environment | Base URL | Notes |
|---|---|---|
| Production (recommended) | https://api.nexith.ai/v1 |
OpenAI-style single domain; all model endpoints available |
| Production (alias) | https://gateway.nexith.ai/v1 |
Behaves identically to the recommended URL |
| Local development | http://localhost:8080/v1 |
Direct connection to the gateway |
api.nexith.aialso serves the console BFF (/v1/billing,/v1/api-keys,/v1/admin, etc.). Those are not model endpoints and are outside the scope of this documentation.
Authentication#
All /v1 model endpoints require authentication. The following credentials are supported:
| Method | Header | Applies to |
|---|---|---|
| API key (recommended) | Authorization: Bearer nx-... |
All endpoints |
| JWT (login session) | Authorization: Bearer eyJ... |
All endpoints (used internally by the chat site) |
| Anthropic style | x-api-key: nx-... |
Only /v1/messages, /v1/messages/count_tokens |
API keys are created in the developer console (platform.nexith.ai) and look like nx-xxxxxxxx.
A key's permissions, RPM/TPM, and balance come from the server-side record; the user field in a
request is passed through to the upstream only as metadata and does not participate in
authentication or billing attribution.
/v1/images/editsis the image editing endpoint reserved for the chat site: it accepts JWTs only, and anynx-key receives a 403.
Quickstart#
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)Image generation (async job)#
# 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://..."]}Endpoint overview#
| Method | Path | Description | Docs |
|---|---|---|---|
| POST | /v1/chat/completions |
OpenAI Chat Completions | Details |
| POST | /v1/responses |
OpenAI Responses adapter (Codex, etc.) | Details |
| POST | /v1/messages |
Anthropic Messages adapter (Claude Code) | Details |
| POST | /v1/messages/count_tokens |
Anthropic token counting | Details |
| GET | /v1/models |
List available models | Details |
| POST | /v1/images/generations |
Submit an image generation job | Details |
| POST | /v1/images/edits |
Submit an image editing job (JWT only) | Details |
| GET | /v1/jobs/:id |
Job status and artifacts | Details |
| GET | /v1/jobs/:id/events |
Job event SSE | Details |
| POST | /v1/jobs/:id/cancel |
Cancel a job | Details |
| POST | /v1/files |
Upload an image and get an nx-file:// reference |
Details |
| GET/POST | /v1/conversations |
List / create conversations | Details |
| GET/PATCH/DELETE | /v1/conversations/:id |
Read / update / delete a conversation | Details |
/v1/embeddingsand/v1/audio/*are implemented, but no upstream is configured yet. Calls return 502inference_unavailable, and these routes are not yet part of the public commitment. They will be announced separately when they go live.
Compatibility#
| Client | Integration | Notes |
|---|---|---|
| OpenAI SDK | base_url=https://api.nexith.ai/v1 |
Chat Completions / Responses both work |
| Codex CLI | wire_api = "responses" |
See Responses |
| Claude Code | ANTHROPIC_BASE_URL=https://api.nexith.ai |
See Messages |
| OpenCode / others | OpenAI Chat compatible | See Chat Completions |
Conventions#
- Currency unit: prices in this documentation and in the API are in USD; accounting is recorded internally as integer microdollars (1e-6 USD).
- Time: all timestamps are Unix seconds (
created) or RFC3339 UTC strings. - Error format: uniformly
{"error":{"message","type","code"}}, see Errors and rate limiting. - Streaming:
text/event-stream; frames are sent asdata: <json>and terminated bydata: [DONE]. - Opacity: upstream providers, real model names, and raw internal error text never appear in responses; failed jobs return only an opaque reason (see Jobs).