01
OpenAI 兼容
开发者接入
通过 OpenAI 兼容格式接入云筑Hub，包含完整请求示例和常见错误排查。
固定接口地址
https://www.yunzhuhub.com/v1注意末尾必须包含 /v102
验证邮箱并完成注册
按页面提示完成人机验证；点击「发送验证码」，填写邮箱收到的验证码，勾选用户协议及隐私政策，再点击「创建账户」。注册成功后使用用户名或邮箱登录。人机验证的形式和显示位置以当前页面为准。
进入控制台03
04
兑换或充值额度
打开钱包，向下找到「有兑换码吗？」区域，输入兑换码并点击「兑换额度」。如需在线充值，按页面当前提供的金额、付款方式和提示操作。
05
进入 API 密钥管理
在控制台侧边栏进入「常规 → API 密钥」。新版支持「卡片视图」和「表格视图」，右上角可切换显示方式；两种视图管理的是同一组密钥。
打开 API 密钥06
创建并设置 API 密钥
点击「创建 API 密钥」，在右侧抽屉只填写便于识别的用途/令牌名称，例如 Workbuddy、Codex、Claude Code 或具体项目名，然后点击「保存更改」。
07
复制并妥善保存 API Key
保存后，在卡片视图点击密钥右侧的复制图标；在表格视图点击「API 密钥」列旁的复制图标。首次点击若提示密钥正在加载，等待完成后再点击一次即可，不要重复创建。点击 sk-*** 文本也可查看完整密钥。
API Key 示例
<YOUR_API_KEY>08
在模型广场取得准确模型 ID
打开模型广场，在搜索框输入需要的模型名称，向下查看匹配的模型卡片。点击卡片中的「复制模型名称」图标，取得准确模型 ID。截图中的模型仅为操作示例，实际模型列表、价格和限制以官网实时页面为准。
查看模型广场09
使用 OpenAI 兼容格式
云筑Hub 提供 OpenAI 兼容接口。通用请求头如下，业务请求使用 Authorization: Bearer 传递 Key。
HTTP Headers
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json10
用 Curl 发起最小请求
将 <MODEL_ID> 替换为模型广场中的真实模型 ID。
Shell
curl https://www.yunzhuhub.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-d '{
"model": "<MODEL_ID>",
"messages": [{"role": "user", "content": "hi"}]
}'11
用 Python OpenAI SDK 接入
安装并使用官方 OpenAI Python SDK，把 base_url 指向云筑Hub。
Shell
pip install openaiPython
from openai import OpenAI
client = OpenAI(
api_key="<YOUR_API_KEY>",
base_url="https://www.yunzhuhub.com/v1",
)
response = client.chat.completions.create(
model="<MODEL_ID>",
messages=[{"role": "user", "content": "hi"}],
)
print(response.choices[0].message.content)12
处理响应并记录请求信息
生产代码中应设置超时、有限重试和错误日志。日志只记录状态码、模型和请求 ID，不记录完整 Key 或敏感业务内容。
故障排查
没有成功时按顺序检查
401认证失败检查 Bearer 前缀、Key 是否完整、是否已禁用。
403权限不足检查 API 密钥权限、模型范围或账号状态。
model not found模型不存在从模型广场重新复制模型 ID，不要使用展示名。
insufficient quota额度不足进入钱包充值或兑换，并核对 API 密钥额度限制。
