API 接入文档

更新时间：2026-08-14 10:07:57

BitaHub 提供标准化的大模型 API 聚合网关，全面兼容 OpenAI 协议规范。用户无需自行购买 GPU 租赁算力或部署推理镜像，即可通过统一的 Base URL 与 API Key，按需接入全球主流大语言模型。

---

一、适用场景与权限体系

1.1 核心适用场景

• 按量调用大模型：按 Token 用量或按次计费调用第三方主流大模型，无需维护底层 GPU 实例。
• 无缝对接客户端：在 Cursor、Cherry Studio、Open WebUI、LangChain、LobeChat 等兼容 OpenAI 的生态工具中，仅需修改 Base URL 即可直接使用。
• 透明比价选型：在模型广场中直观对比各厂商模型的输入价、缓存读取价与输出价，选择最具性价比的模型。

1.2 页面入口与角色权限

平台主入口位于顶部导航栏 「模型 API」（或访问 https://www.bitahub.com/model-api）。用户可在页面内切换「全部模型」、「API Key 管理」及「调用管理」。

角色类型	可操作权限	受限操作
访客	浏览上架模型列表、查看接入文档、查看模型单价	创建 API Key、在线调试体验、查看调用账单
子账号	浏览模型列表、查看接入文档	API Key 管理、调用管理（点击提示联系主账号授权）
主账号	全部能力：创建/启停/删除 Key、模型在线体验、查看账单与充值	在门户端创建模型或修改模型官方定价

账号提示

子账号若直接访问受限管理路由，系统将自动重定向回「全部模型」页面并提示联系主账号。

---

二、模型选型与计费规则

2.1 模型浏览与厂商筛选

进入模型广场后，可按厂商单选过滤（如 DeepSeek、OpenAI、Anthropic 等）。卡片区展示当前所有可调用的模型列表，支持一键点击复制 模型 ID（如 deepseek-r1、gpt-4o）。

2.2 价格阅读规则

计费维度	说明
输入价格	用户发送 Prompt 消耗的 Token 单价，单位通常为 元 / M tokens
缓存读取价	命中网关 Context Caching 缓存时的读取单价，通常大幅低于常规输入价
输出价格	模型生成回答消耗的 Completion Token 单价

• 对话补全类：通常按上述三项 Token 维度独立计价并实时结算。
• 多模态/生图/视频类：若不按 Token 计费，卡片将展示「按结果计费」或「查看价格详情」。
• 价格待确认：任一单价暂未录入时，该项显示「价格待确认」，其余价格项照常展示。

---

三、创建与管理 API Key

API Key 为主账号级别通用凭证，创建后默认可调用当前账号权限范围内的所有上架模型。

3.1 创建 API Key

1. 登录主账号，进入 模型 API 页面，点击右侧 【API Key 管理】。
2. 点击 【创建 API Key】 按钮，填写以下配置：
   • Key 名称：必填，1–32 个字符，支持中英文、数字、下划线及连字符；
   • 额度上限：选填，留空表示不设上限，或填写大于等于 0 的金额（单位：元）；
   • 过期时间：选填，留空表示永不过期。
3. 提交后系统自动完成账户额度映射并生成可调用凭证。
4. 安全保存：创建成功后，控制台仅展示一次完整明文 Key（形如 sk-xxxxxxxx），关闭弹窗后不可再查，请立即复制并妥善保存至密码管理器或服务端环境变量中。

3.2 密钥安全与运维规范

• 状态生命周期：API Key 支持在「启用」与「停用」之间随时切换；删除为不可逆操作，删除后 Key 立即失效。
• 严禁客户端硬编码：切勿将 API Key 写入前端代码、小程序安装包、公开 Git 仓库或截图中。
• 分业务独立发号：建议不同业务服务使用独立的 Key，以便在「调用管理」中按 Token 标签精准核算成本。

---

四、接口规范与代码示例

4.1 基础服务地址

配置项	地址 / 规范
Base URL	https://api.bitahub.com
OpenAI SDK Base URL	https://api.bitahub.com/v1
对话补全接口 (Chat)	POST https://api.bitahub.com/v1/chat/completions
获取模型列表接口	GET https://api.bitahub.com/v1/models
鉴权请求头	Authorization: Bearer <YOUR_API_KEY>
Content-Type	application/json

4.2 常用调用代码示例

cURL (终端)

curl https://api.bitahub.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-r1",
    "messages": [
      {"role": "system", "content": "你是由 BitaHub 驱动的智能助手。"},
      {"role": "user", "content": "你好，请做个自我介绍！"}
    ],
    "stream": false,
    "temperature": 0.7
  }'

Python (OpenAI SDK)

from openai import OpenAI
import os

client = OpenAI(
    base_url="https://api.bitahub.com/v1",
    api_key=os.environ.get("BITAHUB_API_KEY", "sk-your-api-key")
)

response = client.chat.completions.create(
    model="deepseek-r1",
    messages=[
        {"role": "system", "content": "你是由 BitaHub 驱动的智能助手。"},
        {"role": "user", "content": "用三句话介绍量子计算的核心原理。"}
    ],
    temperature=0.7,
    stream=False
)

print(response.choices[0].message.content)
print("Token 消耗统计:", response.usage)

Node.js (JavaScript)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.bitahub.com/v1",
  apiKey: process.env.BITAHUB_API_KEY || "sk-your-api-key",
});

async function main() {
  const completion = await client.chat.completions.create({
    model: "deepseek-r1",
    messages: [
      { role: "system", content: "你是由 BitaHub 驱动的智能助手。" },
      { role: "user", content: "请列出 3 个高效学习编程的建议。" }
    ],
  });

  console.log(completion.choices[0].message.content);
  console.log("Token 用量:", completion.usage);
}

main();

4.3 核心请求参数说明

参数名称	类型	必填	说明与默认值
model	string	是	模型 ID（可在模型广场卡片上一键复制）
messages	array	是	对话上下文数组，包含 role (system/user/assistant/tool) 与 content
stream	boolean	否	是否开启流式传输，默认 false。开启后按 SSE 格式持续返回数据块
temperature	number	否	采样温度 (0–2)，控制生成随机性。通常与 top_p 二选一调节
top_p	number	否	核采样比例 (0–1)，默认 1.0
max_tokens	integer	否	单次补全的最大输出 Token 限制

4.4 响应结构示例

非流式响应 (JSON)

{
  "id": "chatcmpl-9x7b2f8a",
  "object": "chat.completion",
  "created": 1723629400,
  "model": "deepseek-r1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "您好！我是接入 BitaHub 平台的大语言模型，很高兴为您服务。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 28,
    "total_tokens": 43
  }
}

流式响应 (SSE Chunk)

data: {"id":"chatcmpl-9x7b2f8a","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":"您"},"finish_reason":null}]}

data: {"id":"chatcmpl-9x7b2f8a","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"好！"},"finish_reason":null}]}

data: [DONE]

---

五、主流第三方客户端配置

所有支持 OpenAI 兼容格式的客户端工具均可无缝切换至 BitaHub 服务网关。

Cherry Studio

步骤 1：打开 Cherry Studio，进入 【设置】 → 【模型服务】。

步骤 2：服务商选择 OpenAI 或添加自定义服务商。

步骤 3：API 地址 填写：https://api.bitahub.com/v1。

步骤 4：API Key 填写在 BitaHub 创建的 API Key。

步骤 5：模型设置：添加并勾选在平台复制的模型名称（如 deepseek-r1）。

步骤 6：发送一条测试消息，确认可正常收到流式回复。

Open WebUI

方式一：Docker 启动时配置环境变量

docker run -d -p 8080:8080 \
  -e OPENAI_API_BASE_URL="https://api.bitahub.com/v1" \
  -e OPENAI_API_KEY="<YOUR_BITAHUB_API_KEY>" \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

方式二：Web 界面管理后台配置

步骤 1：登录管理员账号，点击头像进入 【管理面板】 → 【设置】 → 【连接】。

步骤 2：在 OpenAI API 连接项中，填入 Base URL https://api.bitahub.com/v1 与 API Key。

步骤 3：点击验证保存，系统将自动拉取平台可用模型列表。

Cursor / Continue / NextChat

在 Cursor、Continue 插件或 NextChat 等工具中，只需统一替换以下三项参数配置：

Base URL / API 地址：https://api.bitahub.com/v1

API Key：您的 BitaHub API Key

Model Name：BitaHub 平台展示的准确模型标识（如 deepseek-r1）

---

六、用量统计、账单明细与充值

6.1 调用统计与日志查询

主账号进入 【模型 API】 → 【调用管理】，可查看当前账户的使用看板：

• 时间范围筛选：支持切换查看「最近 24 小时」、「最近 7 天」或「最近 30 天」；
• 核心数据看板：实时汇总请求次数、输入 Tokens、缓存读取 Tokens 及输出 Tokens；
• 明细调用日志：按时间倒序展示每笔调用的请求时间、令牌标识、调用模型、响应耗时（含首字耗时与流式状态）、输入/输出 Token 数及本次扣费金额。

6.2 账单结算机制

• 统一账本：模型 API 复用 BitaHub 平台通用账户余额，无需单独向 API 划转额度；
• 计费口径：消费明细中的消费资源标为 api，计费方式为按量扣费；
• 账户充值：通过控制台右上角头像下拉菜单点击 【充值与计费】，支持支付宝扫码或对公转账充值，充值成功后余额实时同步至 API 网关。

---

七、标准推荐接入流程

为确保接入顺畅，建议按照以下步骤依次操作：

1

步骤一：浏览模型广场并复制模型 ID

打开 模型 API 市场，对比各模型单价，复制目标模型 ID（如 deepseek-r1）。

2

步骤二：创建并妥善保存 API Key

在 API Key 管理面板创建密钥，并将生成的明文 Key 安全写入服务端系统环境变量（如 BITAHUB_API_KEY）。

3

步骤三：核实账户可用余额

进入「充值与计费」确认账户余额充足，避免因余额为零触发 insufficient_balance 网关拦截。

4

步骤四：发送单次验证请求

通过 cURL 命令或客户端发起单次对话测试，确认服务端返回 HTTP 200 及预期的补全结果。

5

步骤五：核验调用管理数据流水

进入「调用管理」列表，确认日志中已产生该笔调用记录，验证完成。

此页面对您有帮助吗？