一个统一 BaseURL
调度全部模型资源
遵循 OpenAI 兼容协议,聚合上百款公有模型、本地私有化部署开源模型;由 Agent 智能驱动任务编排,
自动规划调用链路,减少冗余推理,节省算力消耗;仅切换 model 参数即可调用不同模型,业务代码无需改动。
平台提供智能路由、故障切换、并发限流、租户鉴权、计费对账、全链路审计能力, 支持同步对话、异步图像、视频生成等多模态任务。
{ "model": "deepseek-chat", "messages": [{ "role": "user", "content": "你好,介绍一下自己" }], "stream": true }
智能路由
Agent 规划调用链路,按价格、时延与可用性自动选路,减少冗余推理。
故障容灾
渠道熔断与自动切换,单点故障不落请求,全程可观测。
租户隔离
Key 鉴权、并发限流、配额独立,多业务线互不干扰。
按量计费
先冻结后结算、差额即退,逐笔账单可对账、可审计。
模型目录
按 model 字段切换,请求与响应格式保持一致。点卡片可直接复制模型 ID。
GET /v1/models 返回的 pricing 字段同源;
实际可调用集合以该接口为准——渠道未开通或整体熔断的模型不会出现在列表里。
三步接入,不用改代码
任何支持 OpenAI 协议的 SDK、框架、低代码平台都能直接用;迁移成本只有两个环境变量。
注册,立刻拿到 Key
手机号 + 密码即可开通,注册成功当场签发一把 mass-sk- Key,不必等人工审核。
改 base_url
把现有 OpenAI 客户端的地址指向下面这个域名,Key 换成平台签发的 Key。
换 model 字段
用 GET /v1/models 拉已开通模型,想换供应商只改一行字符串。
复制就能跑
下面是能直接运行的代码。流式、非流式、视频异步任务各一段,右上一个按钮复制全文。
# pip install openai from openai import OpenAI client = OpenAI( base_url="https://www.bitvox.cn/v1", api_key="mass-sk-...", ) resp = client.chat.completions.create( model="deepseek-chat", # 换模型只改这一行 messages=[{"role": "user", "content": "用一句话解释向量数据库"}], ) print(resp.choices[0].message.content)
// npm i openai import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://www.bitvox.cn/v1", apiKey: process.env.MASS_API_KEY, }); const stream = await client.chat.completions.create({ model: "qwen-plus", messages: [{ role: "user", content: "写一段商品文案" }], stream: true, }); for await (const chunk of stream) { process.stdout.write(chunk.choices[0]?.delta?.content ?? ""); }
# 非流式 curl https://www.bitvox.cn/v1/chat/completions \ -H "Authorization: Bearer $MASS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"你好"}]}' # 流式:加 "stream": true,返回 SSE(data: {...} 逐帧,末帧 data: [DONE]) # 查余额(credit,1 credit = ¥1) curl https://www.bitvox.cn/v1/balance -H "Authorization: Bearer $MASS_API_KEY" # 查模型与价格 curl "https://www.bitvox.cn/v1/models?type=video" -H "Authorization: Bearer $MASS_API_KEY"
curl https://www.bitvox.cn/v1/video/generations \ -H "Authorization: Bearer $MASS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "doubao-seedance-2-5-my-test", "prompt": "雨夜霓虹街头,橘猫缓步走过", "duration": 5, "resolution": "720p" }'
# queued → processing → completed / failed # failed 全额退款,不会扣一分钱 curl https://www.bitvox.cn/v1/video/generations/vid_xxx \ -H "Authorization: Bearer $MASS_API_KEY" # 上游不提供公开直链时,成品从这里取 curl -L https://www.bitvox.cn/v1/video/generations/vid_xxx/content \ -H "Authorization: Bearer $MASS_API_KEY" -o out.mp4
端点清单
业务端点全部要求 Bearer 鉴权;账户端点用 Cookie 会话,只在网页端使用。
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /v1/chat/completions | 对话补全。支持 stream:true、工具调用、多模态 content 数组 |
| GET | /v1/models | 可调用模型列表,带 type(chat / video)与 pricing 单价;可加 ?type=video |
| GET | /v1/balance | 余额:available / frozen / spent / debt,单位 credit |
| POST | /v1/video/generations | 提交视频任务,返回任务 id 与冻结金额 |
| GET | /v1/video/generations/{id} | 查询任务状态与结果(读平台记录,不回源上游,可放心高频轮询) |
| GET | /v1/video/generations/{id}/content | 取成品视频。有直链时 302,无直链时由平台代理转发 |
| POST | /v1/auth/register | 注册(手机号 + 密码)。成功即登录,响应含一次性明文 Key |
| POST | /v1/auth/login | 登录。写入 HttpOnly 会话 Cookie(30 天) |
| GET | /v1/auth/me | 当前登录态、余额与 Key 掩码;未登录返回 authenticated:false |
| POST | /v1/auth/logout | 退出,清除会话 Cookie |
| GET | /healthz · /readyz | 存活 / 就绪探针,不鉴权 |
Idempotency-Key 请求头(≤255 字符)。同键重放不重复扣费、返回首次结果;
并发同键返回 409 request_in_progress。
跨域:业务端点已开放 CORS(不含凭据),浏览器里可直接调;账户端点不带跨域头。
计费只有一套账
先冻结、后结算、差额即退。每一次调用都能按请求 ID 追到上游成本,账单不需要「估算」。
预扣冻结
按候选渠道最高单价估算并冻结,余额不足直接 402,不会先把请求打出去再收钱。
按实际结算
用上游返回的真实 usage 结算,多冻的部分立即退回,余额实时可见。
失败全额退
上游报错自动换渠道重试;全部失败全额退款并返回 502,视频任务超时同样退款。
逐笔可对账
每次调用落 usage 记录,含上游成本与毛利;对账任务每天比对余额、流水与账单。
/v1/balance 返回 6 位小数。
对话按百万 token 计价,视频按秒计价,单价都能从 GET /v1/models 读到。
错误码与处置
错误体统一为 OpenAI 形态:{"error":{"message","type","code"}},程序读 code,人读 message。
| HTTP | code | 含义与处置 |
|---|---|---|
| 400 | invalid_request_error | 请求体非法、模型类型用错端点(如拿视频模型打 chat) |
| 401 | invalid_api_key | Key 缺失、格式不对或已停用 |
| 402 | insufficient_quota | 余额不足,需充值;预扣已在扣款前拦下 |
| 403 | forbidden | 视频任务不属于当前租户 |
| 404 | model_not_found | 模型未上架,或该模型当前无可用渠道 |
| 404 | task_not_found | 视频任务不存在或已过保留期(默认 24 小时) |
| 404 | account_not_found | 账户尚未初始化账本,联系管理员处理 |
| 409 | request_in_progress | 同 Idempotency-Key 的首个请求仍在处理 |
| 429 | rate_limit_exceeded | 超出 Key 的每分钟请求数,按 Retry-After 等待 |
| 429 | quota_exceeded | 触及日限额,次日恢复或申请提额 |
| 502 | upstream_error | 全部候选渠道失败,预扣已退回 |
| 503 | upstream_unavailable | 该模型当前无可用渠道(熔断中),稍后重试 |
| 503 | video_disabled | 本网关未启用视频能力 |
| 500 | internal_error | 平台内部错误,可重试;持续出现请带 X-Mass-Request-Id 联系我们 |
Idempotency-Key;
400 / 401 / 402 / 404 重试不会成功,只会放大故障。
每个响应都带 X-Mass-Request-Id,报障时贴这一串即可定位整条链路。
现在注册,一分钟内拿到 Key
手机号 + 密码即可开通,注册成功当场签发 API Key。余额为零也能先跑通链路,充值后再上量。