開發者文件

覆蓋接入概覽、驗證、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