Nodex AI
主题

开发者文档

覆盖接入概览、鉴权、API 参考、SDK、CLI、Web Chat、SSE 续传、计费、错误码和状态支持。

概览

概览

Nodex AI 面向 API、CLI 和 Web Chat 三种产品形态提供统一账号、额度、账单、路由和会话记录。V1 公开入口以新加坡节点、Alipay 支付和 OpenAI/Claude 兼容协议为核心。

范围
Product forms: API / CLI / Web Chat
Region: Singapore
Protocols: OpenAI-compatible / Claude-compatible / SSE
Billing: subscription + token metering
Session storage: metadata + encrypted request/response body references

快速开始

先在 Console 创建 API key，然后将 SDK base URL 指向 Nodex。所有付费请求都必须携带幂等键，流式请求应同时携带 session id。

cURL
curl https://api.nodex-ai.net/v1/chat/completions \
  -H "Authorization: Bearer $NODEX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: req_$(uuidgen)" \
  -H "X-Nodex-Session-Id: sess_docs_quickstart" \
  -d '{
    "model": "gpt-5.4",
    "messages": [{"role": "user", "content": "Hello Nodex"}],
    "stream": true
  }'

Bearer Token 认证

通过在 Authorization HTTP header 中以 Bearer token 形式包含 API key 来认证请求。浏览器端不要保存 runtime API key，Web Chat 由服务端代理创建短期调用凭证。

cURL Request
curl https://api.nodex-ai.net/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
保护你的密钥

API keys 拥有较高权限，请妥善保管。不要在 GitHub、客户端代码或任何公开区域共享 secret API key。

API 参考

V1 对外暴露四组模型 API：OpenAI Chat Completions、OpenAI Responses、Claude Messages 和 Models。所有端点都通过统一鉴权、路由、幂等、限流和计费层。

端点
GET  /v1/models
POST /v1/chat/completions
POST /v1/responses
POST /v1/messages

Chat Completions

Chat Completions 兼容 OpenAI SDK 的 messages 格式，支持 stream=true 返回 SSE。响应 header 会包含 Nodex request/session/node 元数据。

请求
POST https://api.nodex-ai.net/v1/chat/completions
Authorization: Bearer $NODEX_API_KEY
X-Idempotency-Key: req_01
X-Nodex-Session-Id: sess_01

{
  "model": "gpt-5.4",
  "messages": [{"role": "user", "content": "Summarize this."}],
  "stream": true
}

Responses & Messages

Responses 适合新 OpenAI 风格工作流；Messages 面向 Claude 兼容调用。Nodex 在网关边界做协议适配，同时保留统一 session 和费用记录。

示例
POST /v1/responses
{
  "model": "gpt-5.4",
  "input": "Generate a release note."
}

POST /v1/messages
{
  "model": "claude-sonnet-4.6",
  "max_tokens": 1024,
  "messages": [{"role": "user", "content": "Review this design."}]
}

SSE 流式与续传

流式请求支持 Last-Event-ID 断点续传。客户端断开后应使用同一个 X-Idempotency-Key、同一个 X-Nodex-Session-Id 和最后收到的 event id 重连。

续传 Headers
Last-Event-ID: evt_00042
X-Idempotency-Key: req_01
X-Nodex-Session-Id: sess_01

幂等与计费

幂等键用于避免网络重试导致重复扣费。Nodex 会先预估 token 并预留余额，请求完成后按最终 token 和价格版本结算。

计费 Headers
Required:
Authorization: Bearer $NODEX_API_KEY
X-Idempotency-Key: req_unique_per_business_action

Recommended:
X-Nodex-Session-Id: sess_user_visible_thread
避免重复扣费

同一个幂等键应只用于同一个业务请求。不要在不同 prompt、不同模型或不同用户之间复用。

SDKs & CLI

OpenAI SDK 只需要替换 baseURL；Claude SDK 使用兼容的 /v1/messages 入口。CLI Provider 共享同一账号余额和权限边界。

SDK / CLI
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NODEX_API_KEY,
  baseURL: "https://api.nodex-ai.net/v1",
});

// CLI
nodex login
nodex env export openai

Web Chat

Web Chat 使用 Nodex Console 登录态，不在浏览器暴露 runtime API key。对话、请求、响应、SSE 摘要和费用元数据会统一落库。

流程
Web Chat flow:
1. User signs in to Console
2. Server creates a short-lived runtime key
3. Gateway streams SSE with session metadata
4. Server revokes the short-lived key after completion

错误码

错误响应使用统一 envelope。客户端应读取 error.code 做分支处理，并记录 X-Nodex-Request-Id 方便排查。

JSON
{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key provided.",
    "request_id": "req_01..."
  }
}

Common codes:
unauthenticated, invalid_api_key, idempotency_key_required,
insufficient_balance, rate_limited, upstream_unavailable,
model_forbidden, body_too_large

状态与支持

状态页和支持入口用于排查节点、上游、支付、对账和账户问题。生产问题请提供 request id、session id、时间窗口和模型名称。

排查信息
Troubleshooting bundle:
request_id=req_...
session_id=sess_...
model=gpt-5.4
time_window=2026-05-11T10:00:00Z/2026-05-11T10:05:00Z
symptom=stream_disconnected