NNexithDocs
StatusDashboard ↗
Overview & quickstartModel catalogGuidesAPI referenceIntegrationsOAuth2 / OIDC

Nexith API Documentation

Version: v1 · Updated: 2026-11-19 Applies to: https://api.nexith.ai/v1 (equivalent alias https://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.ai also 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/edits is the image editing endpoint reserved for the chat site: it accepts JWTs only, and any nx- 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/embeddings and /v1/audio/* are implemented, but no upstream is configured yet. Calls return 502 inference_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 as data: <json> and terminated by data: [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).