SupaNexus
开始使用

Chat Completions

Markdown 版本

示例中的 <BASE_URL> 请从 接入点 选择并替换。

为多轮对话创建模型回复。

POST <BASE_URL>/v1/chat/completions

协议说明：本接口是 OpenAI 形态入口，可调用目录中任意可售卖模型。客户端形态与上游协议可不一致，由网关转换（如调 anthropic/* 时转 Anthropic Messages）。发图到 Claude 请用 /v1/messages。

认证

必需：Authorization: Bearer <API_KEY>

请求头

头必需说明
Authorization是Bearer API Key
Content-Type是application/json
Idempotency-Key否24 小时内防止重复调用
Accept-Language / X-Locale否影响部分错误的本地化文案

请求体

SupaNexus 接受 OpenAI Chat Completions JSON 格式，识别 model 与 stream；其余字段按 OpenAI 兼容方式处理。多模态（图片 image_url、视频 video_url 仅公网 URL）见 参数 → 多模态输入。

{
  "model": "deepseek/deepseek-chat",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ],
  "stream": false,
  "temperature": 0.7,
  "max_tokens": 1024
}
字段必需说明
model是GET /v1/models 返回的模型 id（如 deepseek/deepseek-chat）
messages是OpenAI 格式消息数组
stream否true 启用 SSE 流式 — 见 流式响应

非流式响应

返回 OpenAI 兼容 JSON。示例：

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "Hello! How can I help?"},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 2000,
    "completion_tokens": 300,
    "total_tokens": 2300,
    "prompt_tokens_details": {
      "cached_tokens": 1500
    }
  }
}

prompt_tokens_details.cached_tokens（OpenAI）表示 命中 Prompt Cache 的输入 token 数。SupaNexus 据此与平台配置的 缓存输入单价 计费；未配置分档时仍按全部输入 token 计 输入价。

用量与 Prompt Cache 计费

SupaNexus 不运行 Prompt Cache，但会 读取 响应 usage 中的缓存字段并计入账单：

服务商典型字段
OpenAIusage.prompt_tokens_details.cached_tokens
Anthropicusage.cache_read_input_tokens

计费（简化）：

费用 ≈ (prompt_tokens − cached_hit) × 输入单价 + cached_hit × 缓存输入单价 + completion_tokens × 输出单价

价目表以 模型广场 为准，详见 模型定价。服务端用量明细可含 cached_input_tokens。

响应头（SupaNexus）

头说明
X-SNX-Trace-ID唯一请求 ID，联系支持时可提供
X-SNX-Model本次请求使用的模型 id
X-SNX-Provider实际提供推理的服务商标识

幂等

发送 Idempotency-Key: <唯一字符串> 可在 24 小时 内按 API Key 去重。若 Key 已处理过：

  • HTTP 409
  • error.code: duplicate_request

未提供 Idempotency-Key 时，可能回退使用 X-SNX-Trace-ID。

路由

SupaNexus 根据你请求的模型 id 选择可用服务。若暂时无法完成请求，可能返回 502 或 503。

数据与隐私

SupaNexus 不保存跨请求的对话历史：每次请求由调用方自行拼装 messages[]。

处理方式说明
请求体SupaNexus 默认不持久化 prompt/completion 正文
用量记录调用时间、模型、Token 数量等计费所需信息
排障联系支持时可提供 X-SNX-Trace-ID

开发者控制台文本对话体验窗中的聊天记录仅保存在当前浏览器会话；刷新或关闭页面后不会从 SupaNexus 服务端恢复。

详见 隐私政策 与 服务条款。

常见错误

HTTP说明
400缺少 model、JSON 无效；非法 video_url（非公网 http(s)）
401认证失败
413请求体超过默认 64 MB
402账户余额不足（error.code=402）
404未知或不可用模型
408请求超时（默认 120s）
409幂等冲突
429用量配额已用尽
502服务暂时不可用
503服务暂时不可用

完整说明见 错误处理。

相关