MOXI-API Retail Gateway
返回零售站 管理 API 密钥
MOXI RETAIL API

把模型接入你的产品。

MOXI-API 提供统一的 OpenAI 兼容入口，支持对话、Responses、嵌入、图像和音频模型。 只需一个 API 密钥，就能在现有 SDK 和自动化工具中切换模型。

API Base URL https://api.supermoxi.cn/v1
认证方式 Authorization: Bearer
01

概览

统一入口、透明计费、可核对的调用记录。

MOXI-API 将多个模型供应商整理为一个兼容 OpenAI 的 API。你可以继续使用熟悉的 OpenAI SDK，只需要替换 base_url 和 API 密钥。

可用模型、价格和限额以控制台实时信息为准。每次请求都可以在零售站的调用日志中查看， 方便核对请求状态、用量和费用。

请求骨架
Base URL
https://api.supermoxi.cn/v1
Header
Authorization: Bearer MOXI_API_KEY
Content-Type
application/json
02

快速开始

三步完成第一条模型请求。

  1. 1

    注册并登录

    在 supermoxi.cn 创建账户，完成邮箱验证后进入控制台。

  2. 2

    创建 API 密钥

    打开“API 密钥”，创建一枚专用密钥。密钥只在创建时完整显示，请放入服务端环境变量。

  3. 3

    发送请求并查看日志

    选择控制台中可用的模型，发送下面的请求，再到“调用日志”核对结果。

第一次请求：列出可用模型
curl https://api.supermoxi.cn/v1/models \
  -H "Authorization: Bearer $MOXI_API_KEY"
第一次对话请求
curl https://api.supermoxi.cn/v1/chat/completions \
  -H "Authorization: Bearer $MOXI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [{"role": "user", "content": "你好，介绍一下你自己。"}]
  }'
提示示例中的 YOUR_MODEL_ID 请替换为 模型列表 中当前可用的模型 ID。
03

工具调用

用函数调用让模型连接你的业务系统。

对支持工具调用的模型，在请求中传入 tools 和可选的 tool_choice。 MOXI 会保留 OpenAI 兼容的请求结构，并将模型返回的工具参数原样交给你的应用处理。

天气查询工具示例
{
  "model": "YOUR_MODEL_ID",
  "messages": [{"role": "user", "content": "北京今天的天气怎么样？"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "查询城市当前天气",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }]
}
调用流程
  1. 模型返回 tool_calls。
  2. 你的服务执行对应函数。
  3. 将 tool 消息带回同一会话。
计费提示

工具调用可能按模型 token 用量或平台配置的工具单价计费，具体以控制台价格页为准。

04

模型与计费

先查模型，再根据场景选择速度、质量和价格。

模型目录会随上游供应商和零售线路变化。不要把旧的模型名写死在部署配置中，建议在启动时调用模型列表，或在控制台确认可用状态。

能力常用端点适用场景
文本对话/v1/chat/completions聊天、摘要、结构化输出
Responses/v1/responses多模态输入、工具编排
向量嵌入/v1/embeddings检索增强、相似度搜索
图像与音频/v1/images、/v1/audio生成、转写、语音合成
价格平台展示价格可能按输入、输出、缓存、图片或工具单价拆分。以 零售站价格页 和调用日志为最终依据。
05

API 端点

所有公开请求都从同一个零售 API Base URL 开始。

POST

/v1/chat/completions

发送一轮或多轮对话，支持流式输出、工具调用和 JSON 输出。

POST

/v1/responses

使用 Responses 风格请求，适合多模态输入和更复杂的工具编排。

POST

/v1/embeddings

将文本转换为向量，用于检索、聚类和语义相似度计算。

GET

/v1/models

读取当前账号可见的模型目录和模型元信息。

Responses 示例
curl https://api.supermoxi.cn/v1/responses \
  -H "Authorization: Bearer $MOXI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "input": "用三句话总结这段文字。"
  }'
06

SDK 接入

兼容主流 OpenAI SDK，只替换地址和密钥。

Python
from openai import OpenAI

client = OpenAI(
    api_key="MOXI_API_KEY",
    base_url="https://api.supermoxi.cn/v1",
)

response = client.chat.completions.create(
    model="YOUR_MODEL_ID",
    messages=[{"role": "user", "content": "你好"}],
)
print(response.choices[0].message.content)
JavaScript / TypeScript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.MOXI_API_KEY,
  baseURL: "https://api.supermoxi.cn/v1",
});

const response = await client.chat.completions.create({
  model: "YOUR_MODEL_ID",
  messages: [{ role: "user", content: "你好" }],
});

生产环境请从环境变量或密钥管理服务读取 API 密钥，不要把密钥提交到仓库、前端代码或日志。

07

错误处理

保留请求 ID，按 HTTP 状态码处理重试和提示。

状态含义建议动作
400请求体或参数不符合模型要求检查模型名、消息结构和 JSON 格式
401密钥缺失或无效确认 Bearer 密钥和环境变量是否正确
403当前账号没有访问该模型的权限改用控制台可见模型或联系平台支持
429限流、余额或上游暂时繁忙使用指数退避重试，并核对余额和线路状态
5xx平台或上游服务暂时异常记录响应中的 request ID，稍后重试并查看状态页
排查顺序先确认 Base URL 和密钥，再确认模型可见性，最后查看 服务状态 与调用日志。
08

常见问题

接入前后最常遇到的几个问题。

API Base URL 应该填写什么？

OpenAI 兼容客户端填写 https://api.supermoxi.cn/v1。如果 SDK 会自动拼接 /v1，则按该 SDK 的要求填写不带后缀的地址。

在哪里查看可用模型和价格？

登录 零售站价格页 或调用 GET /v1/models。模型和价格会随线路状态变化。

怎么核对用量和费用？

进入零售站控制台查看钱包、账单和调用日志。单次请求的模型、token、工具和状态都以日志记录为准。

遇到持续 429 或 5xx 怎么办？

先降低并发并使用指数退避；确认余额和模型权限后，查看服务状态页。如果仍然持续，请附上 request ID 联系支持。

09

架构与运营

面向生产部署的边界、缓存和账号池隔离原则。

MOXI-API 以官方 new-api 为强基线，MOXI-specific 行为通过可审计的 patch overlay 叠加。每次主分支发布都会先应用全部补丁、执行前端和后端检查，再构建 GHCR 镜像。

网站、API、文档站和内部上游通过 Caddy 与 Docker 网络分层。CLIProxyAPI 账号池只允许内网访问，零售、企业和 reserve 池使用独立容器、配置、日志和 auth 目录。

数据边界
持久化业务数据
PostgreSQL：new-api 与 Sub2API
可重建状态
Redis：缓存和会话
账号池凭证
服务器运行目录，永不提交 Git
文档站
docs/site 只读挂载到 Caddy
区域生产规则回滚方式
视频背景公开首页只播放 720p；首次连接只等待 canplay；后台工作台只显示静态海报，不预取 4K，也不注册视频 Service Worker。回滚 0013/0012 补丁，保留官方 new-api 基线和已批准的早期 overlay。
账号池retail、enterprise、reserve 独立容器与 auth 目录；管理端口不对公网开放。切换 new-api/Sub2API 上游到备用池，不触碰业务数据库。
网站更新先推送 GitHub 并等待镜像成功，再在服务器备份 PostgreSQL，只更新 new-api/Caddy 需要的容器。使用上一个镜像 tag，恢复 Caddy 文件；数据库卷保持原样。
完整记录部署清单、账号池布局、视频缓存规格和 lint 基线会随仓库同步：查看 MOXI-API 文档目录。