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、 图片生成/改图、异步作业、文件上传与会话同步都走同一套 /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

约定#

  • 金额单位:文档与接口中的价格均为 USD;账务内部以微美元(1e-6 USD)整数记账。
  • 时间:所有时间戳为 Unix 秒(created)或 RFC3339 UTC 字符串。
  • 错误格式:统一为 {"error":{"message","type","code"}},见 错误与限流。
  • 流式:text/event-stream,帧以 data: <json> 发送,以 data: [DONE] 结束。
  • 不透明性:上游供应商、真实模型名与内部错误原文不会出现在响应里;作业失败只返回 不透明原因(见 Jobs)。