北洛 AI 接入文档
按快速开始创建 API Key 并验证模型列表,再根据客户端选择接口协议。画布、图片能力和常见错误分别整理在后续章节。
画布地址用来打开工具;API 地址用来连接北洛 AI 模型服务。
https://beiluoxi.xyz与画布同域,末尾不加 /v1https://beiluoxi.top推荐地址不通时再切换无限画布选择 OpenAI 格式;Base URL 填上方任一北洛域名,末尾不要添加 /v1。普通 OpenAI 客户端则按下方卡片填写完整地址。
快速开始
https://beiluoxi.xyz/v1备用:https://beiluoxi.top/v1https://beiluoxi.xyz备用:https://beiluoxi.top · 不加 /v1https://beiluoxi.xyz/v1beta备用:https://beiluoxi.top/v1beta四步完成首次接入
- 创建本站 API Key在“API 密钥”页面创建;登录密码和卡密都不能代替 API Key。
- 选择协议并填写地址按客户端类型使用上方对应地址,留意是否需要 /v1 或 /v1beta。
- 获取并复制模型使用客户端的模型列表或下方命令,模型名称照返回结果填写。
- 先发普通文本先关闭工具调用等高级选项,确认基础请求成功后再逐项启用。
YOUR_API_KEY 替换成本站 API Key;从返回的 id 复制模型名称。curl https://beiluoxi.xyz/v1/models \
-H "Authorization: Bearer YOUR_API_KEY"
先确认模型名和能力
模型名称请从 /v1/models 返回的 id 原样复制。图片生成请选择本站已开放且支持生图的模型;不要把图片模型当作视频模型使用。获取模型列表成功只代表地址、Key 和模型列表接口可访问,不代表每种生成能力都已开通。画布的详细配置见“无限画布与模型能力”。
快速排查
| 现象 | 先做什么 | 不要做什么 |
|---|---|---|
| 401 | 重新复制 Key,核对认证头 | 不要把卡密或登录密码当 Key |
| 404 | 看最终 URL;OpenAI 到 /v1,Claude 不加 /v1 | 不要同时改协议、路径和模型 |
| 429 | 降低并发,查余额,等待后有限重试 | 不要连续刷新、无限重试 |
| 502/503/504 | 等 10–30 秒后重试,必要时换模型 | 不要重复创建 Key |
| 524 | 等待片刻后有限重试;也可切换另一个本站域名排除本地线路问题 | 不要高频刷新或持续并发请求 |
| 模型列表为空 | 检查 Base URL、Key、分组和模型权限 | 不要将画布页面地址填入 API Base URL |
| 页面空白 | Ctrl + F5,直接打开 /help | 不要把 /help 当 API 地址 |
API 接入
账户与 API Key
| 功能 | 位置 | 操作要点 |
|---|---|---|
| 购买卡密/订阅 | 站内“充值/订阅” | 付款后保存订单号 |
| 兑换卡密 | 登录后“兑换” | 去掉前后空格,确认一次即可 |
| 查看到账 | 余额/订阅/用量 | 刷新后核对额度 |
| 创建 Key | “API 密钥” → 创建 | 每个软件单独一个 Key |
| 泄露处理 | API 密钥列表 | 立即停用并新建 |
安全底线: Key 不要放网页前端、截图、群聊、公开仓库或共享配置。
协议怎么选
| 客户端选项 | 请选择 | 地址 | 适用 |
|---|---|---|---|
| OpenAI / OpenAI Compatible / Custom OpenAI | OpenAI Compatible | https://beiluoxi.xyz/v1 | 大多数聊天、编程、知识库工具 |
| Anthropic / Claude / Claude Code | Anthropic | https://beiluoxi.xyz | Claude Code、Anthropic SDK |
| Google / Gemini API / Vertex | 仅在有 Custom Endpoint 时使用 | https://beiluoxi.xyz/v1beta | Gemini 原生 REST/SDK |
| 常见误填 | 正确值 |
|---|---|
| Claude 填到 /v1 | 只填主域名 |
| OpenAI 只填主域名 | 填到 /v1 |
| 自动拼接出现 /v1/v1 | 删除重复的一段 |
| 使用服务器 IP 或 http:// | 使用 HTTPS 域名 |
| 使用猜测模型 | 从模型列表复制 |
工具配置总表
“支持自定义地址”以软件当前版本为准;没有自定义字段时,改用 OpenCode、CC Switch 或其他兼容客户端。
| 工具 | 官方入口 | 协议 | 地址支持 | 配置入口 |
|---|---|---|---|---|
| Cherry Studio | 官网 | OpenAI | 支持 | 设置 → 模型服务 → 添加 |
| Chatbox | 官网 | OpenAI/Custom | 支持 | 设置 → 模型提供商 |
| Cursor | 官网 | OpenAI Compatible | 支持 | Settings → Models → Override Base URL |
| Cline | GitHub | OpenAI Compatible | 支持 | Provider → OpenAI Compatible |
| Roo Code | GitHub | OpenAI Compatible | 支持 | API Configuration |
| OpenCode | 官网 | OpenAI/Anthropic/Gemini | 支持 | opencode.json 或 /connect |
| Windsurf | 官网 | OpenAI Compatible | 视版本 | Settings → Models / Provider |
| Zed | 官网 | OpenAI Compatible | 支持 | Settings → Language Models |
| Open WebUI | 官网 | OpenAI Compatible | 支持 | Admin → Connections → OpenAI |
| LobeChat | 官网 | OpenAI Compatible | 支持 | 设置 → 语言模型 → OpenAI |
| NextChat | GitHub | OpenAI Compatible | 支持 | 设置 → API |
| SillyTavern | GitHub | OpenAI Compatible | 支持 | API Connections → Custom/OpenAI |
| Dify | 官网 | OpenAI Compatible | 支持 | 模型供应商 → OpenAI-API-compatible |
| Continue | 官网 | OpenAI Compatible | 支持 | config.yaml / config.json |
| Apifox | 官网 | HTTP | 支持 | 新建 POST 请求 |
| Postman | 官网 | HTTP | 支持 | New Request |
| Codex CLI | GitHub | Responses | 支持 | ~/.codex/config.toml |
| Claude Code | 官方文档 | Anthropic | 支持 | 环境变量 / settings.json |
| Gemini CLI | GitHub | Gemini 原生 | 视版本 | 需要 Custom Endpoint |
| Grok CLI | xAI 文档 | Responses | 支持 | ~/.grok/config.toml |
| OpenClaw | GitHub | OpenAI Compatible | 视版本 | Provider / URL / Key / Model |
| Claude Desktop | 官方下载 | Anthropic | 通常不提供 | 官方登录页不能直接填本站地址 |
国产工具:统一填写
| 字段 | 填写 |
|---|---|
| Provider / 类型 | OpenAI 或 OpenAI Compatible |
| Base URL | https://beiluoxi.xyz/v1 |
| API Key | 本站“API 密钥”创建的 Key |
| Model / Model ID | /v1/models 返回的完整 id |
| API Type | Chat Completions(如果有) |
| Stream | 首次关闭,文本成功后再开启 |
| 软件 | 操作路径 | 第一次测试 |
|---|---|---|
| Cherry Studio | 设置 → 模型服务 → 添加 → OpenAI | 新建对话发“你好” |
| Chatbox | 设置 → 模型提供商 → Custom/OpenAI | 发送短消息 |
| Cursor | Settings → Models → Override Base URL | 先关闭自动 Agent |
| Cline / Roo Code | Provider / API Configuration | 先做只读小任务 |
| Apifox / Postman | URL + Bearer + JSON | 看状态码和响应正文 |
海外工具:OpenAI 兼容
| 工具 | 必填字段 | 最短配置 |
|---|---|---|
| OpenCode | baseURL、Key、Model | ~/.config/opencode/opencode.json |
| Windsurf / Zed | URL、Key、Model | 只有 Custom/Override 才能填写 |
| Open WebUI | URL、Key | URL 填到 /v1 |
| LobeChat / NextChat | API URL、Key、Model | 检查是否自动拼路径 |
| Dify | API Base、Key、Model | 先创建文本模型 |
| Continue | provider、apiBase、Key、Model | 见示例 |
| OpenClaw | Provider、URL、Key、Model | 版本需支持自定义 provider |
Continue 示例
models:
- name: Beiluo
provider: openai
model: YOUR_MODEL
apiBase: https://beiluoxi.xyz/v1
apiKey: YOUR_API_KEY
OpenCode 示例
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"beiluo": {
"npm": "@ai-sdk/openai-compatible",
"name": "Beiluo OpenAI Compatible",
"options": { "baseURL": "https://beiluoxi.xyz/v1", "apiKey": "YOUR_API_KEY" },
"models": { "YOUR_MODEL": { "name": "YOUR_MODEL" } }
}
}
}
Claude Code / Anthropic
| 项目 | 填写 |
|---|---|
| Base URL | https://beiluoxi.xyz(不要加 /v1;备用 https://beiluoxi.top) |
| Key 字段 | ANTHROPIC_AUTH_TOKEN 或 Auth Token |
| 请求路径 | 客户端自动调用 /v1/messages |
| Model | 账户已开放的 Claude 模型 |
macOS/Linux:
export ANTHROPIC_BASE_URL="https://beiluoxi.xyz"
export ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY"
claude
Windows PowerShell:
$env:ANTHROPIC_BASE_URL = "https://beiluoxi.xyz"
$env:ANTHROPIC_AUTH_TOKEN = "YOUR_API_KEY"
claude
官方 Claude Desktop 通常不提供任意 Base URL;需要本站时优先使用 Claude Code、Anthropic SDK、CCS 或支持自定义地址的客户端。
Gemini 原生与 Antigravity
| 项目 | Gemini 原生 | Antigravity 专用分组 |
|---|---|---|
| Base URL | https://beiluoxi.xyz/v1beta |
Claude:https://beiluoxi.xyz/antigravity/v1;Gemini:https://beiluoxi.xyz/antigravity/v1beta |
| 认证 | x-goog-api-key: YOUR_API_KEY | 按对应协议认证 |
| 模型列表 | GET /v1beta/models | GET /antigravity/v1beta/models |
| 生成 | POST /v1beta/models/MODEL:generateContent | 按上列专用路径 |
curl "https://beiluoxi.xyz/v1beta/models/MODEL:generateContent" \
-H "x-goog-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"contents":[{"parts":[{"text":"你好"}]}]}'
Gemini CLI 若只有 Google 登录、GEMINI_API_KEY 或 Vertex 配置而没有 Custom Endpoint,不能直接套用本站地址。普通 Claude 分组与 Antigravity 分组不要混用。
CC Switch(CCS)
官网: ccswitch.io GitHub: farion1231/cc-switch 下载: Releases
| CCS 字段 | OpenAI / Codex | Claude Code |
|---|---|---|
| Provider | OpenAI / OpenAI Compatible | Anthropic / Claude |
| Base URL | https://beiluoxi.xyz/v1 | https://beiluoxi.xyz |
| API Key | 本站 API Key | API Key / Auth Token |
| Model | /v1/models 的名称 | 账户已开放的 Claude 模型 |
| 顺序 | 操作 |
|---|---|
| 1 | Add Provider,建立“北洛”配置 |
| 2 | 选择配置 → Enable |
| 3 | 完全重开终端/工具 |
| 4 | 回官方时选择 Official Login |
CCS 只负责切换配置,不负责购买、兑换或创建本站 Key;只从官网或官方 GitHub 下载。
无限画布与模型能力
接口与高级能力
| 能力 | 方法 | 路径 | 前置条件 |
|---|---|---|---|
| 模型列表 | GET | /v1/models | 有效 Key |
| Chat | POST | /v1/chat/completions | OpenAI 兼容分组 |
| Responses | POST | /v1/responses | 客户端支持 Responses |
| Anthropic Messages | POST | /v1/messages | Anthropic 分组 |
| 用量 | GET | /v1/usage | 账户权限开放 |
| Embeddings | POST | /v1/embeddings | 分组已开放 |
| 图片 | POST | /v1/images/generations、/v1/images/edits | 图像模型/额度 |
| 异步图片 | POST/GET | /v1/images/generations/async、/v1/images/tasks/:task_id | 支持轮询 |
| 视频 | 视服务开放情况 | 视服务开放情况 | 无限画布视频暂不开放;本次不配置、不测试 |
| Gemini | GET/POST | /v1beta/models、/v1beta/models/:model:generateContent | Gemini 认证头 |
| Web/X Search | POST | /v1/web_search、/v1/x_search | Grok 分组/权限 |
| 语音 | POST | /v1/tts、/v1/stt | Grok 分组/权限 |
| 功能 | 建议开启顺序 | 出错先关闭 |
|---|---|---|
| 流式 SSE | 非流式文本成功后再开 | stream |
| 图片/附件 | 小文件、短提示开始 | 图片参数 |
| 工具/Agent | 普通文本成功后逐个开 | tools / Agent |
| 长上下文 | 分段增加历史 | 附件、旧消息 |
| 视频 | 暂不纳入当前接入流程 | 暂不提交生成任务 |
| WebSocket | HTTP/SSE 正常后再开 | WS 优先连接 |
无限画布:地址与配置
登录控制台后,从左侧菜单进入 无限画布。也可以直接打开 https://beiluoxi.xyz/canvas/。首次使用请点击画布右上角的设置按钮,新增或修改 OpenAI 格式渠道:
画布页面地址与 API 地址不同。
画布页面使用https://beiluoxi.xyz/canvas/;在画布设置中,推荐 API 地址填https://beiluoxi.xyz,备用可使用https://beiluoxi.top。两个 API 地址都不要在末尾添加/v1,也不要添加/canvas。
| 配置项 | 填写内容 |
|---|---|
| 供应商类型 | OpenAI 兼容接口 |
| API 地址 / Base URL | 推荐 https://beiluoxi.xyz,备用 https://beiluoxi.top,末尾不要添加 /v1 |
| API Key | 从本站“API 密钥”页面创建的 Key |
| 图片模型 | 选择当前分组开放并标记为“生图”的模型;以模型列表实际显示为准 |
| API 格式 | OpenAI |
| 请求超时 | 建议 600 秒;图片生成较慢时不要设置得过短 |
| 当前验证 | 两个 API 域名均已允许画布来源;2026-09-30 已完成图片生成测试 |
基本用法:
- 先在设置中保存渠道,并使用“获取模型”检查 Key 和地址是否正确。
- 新建画布项目,在画布中添加图片生成节点或从工作台输入提示词。
- 选择图片模型、尺寸和数量,连接参考图后可进行图生图或图片编辑。
- 生成结果可以继续拖到画布上编排、对比和下载。
- 画布、素材、API Key 和生成记录默认保存在当前浏览器;更换浏览器、无痕模式或清理站点数据后需要重新配置。
安全提醒: 不要把完整 API Key 放进截图、提示词、分享链接或群聊。该画图页面由开源第三方项目提供,提示词、参考图和 Key 会由浏览器页面用于请求本站 API;不要上传身份证件、客户资料、未公开设计稿等敏感内容。需要离开内嵌页面时,可点击右上角“新窗口打开”。
| 现象 | 处理 |
|---|---|
| 401 / 未授权 | 重新复制本站 Key,确认没有多余空格,必要时新建独立 Key |
| 403 / 模型不可用 | 确认 Key 绑定的分组支持图片模型,并从模型列表复制正确模型名 |
| 请求失败或跨域错误 | 检查所填域名的 /v1/models 预检是否返回 204,且允许来源为画布域名;跨域配置未生效时联系站点管理员 |
404 或地址出现 /v1/v1 |
Base URL 推荐填 https://beiluoxi.xyz,也可切换 https://beiluoxi.top;末尾不要添加 /v1 |
| 429 / 余额或并发不足 | 检查余额和分组额度,减少一次生成数量,稍后重试 |
| 内嵌页面空白 | 刷新页面;仍无法加载时直接打开 https://beiluoxi.xyz/canvas/ |
| 更换设备后没有历史记录 | 历史记录属于浏览器本地数据,不会自动同步到账号 |
无限画布:视频生成
当前暂不支持通过无限画布生成视频。 本次只更新帮助文档,不改动视频后端,也不提交可能产生费用的视频任务。即使模型列表中出现视频模型,也不要据此发起生成;相关能力完成单独接入和验证后再更新说明。
故障排查
4xx:优先检查请求、认证与权限
4xx 通常说明请求在进入模型前被拒绝,但也可能来自网关策略、分组设置或上游限制,不能只凭状态码判断责任方。
- 400 Bad Request: 检查 JSON、参数名、模型能力和请求参数。
- 401 Unauthorized: 检查 Key 是否完整、是否启用,以及认证头格式。
- 403 Forbidden: 检查 Key 分组、模型权限、来源限制和上游账号状态。
- 404 Not Found: 检查协议与路径,尤其是是否出现
/v1/v1;也可能是当前分组不支持该接口。 - 413 Payload Too Large: 减小图片、附件、上下文或一次生成数量。
- 429 Rate Limit: 降低并发并检查余额、配额和上游限流,等待后再有限重试。
5xx:优先检查服务、上游与超时
- 500 Internal Server Error: 服务端或上游处理异常;保留响应内容与请求时间。
- 502 Bad Gateway: 网关没有获得有效上游响应,稍后重试或切换可用模型。
- 503 Service Unavailable: 服务过载、维护或上游暂不可用。
- 504 Gateway Timeout: 请求处理超过网关等待时间;先降低请求复杂度并避免重复提交。
- 524 Origin Connect Timeout: Cloudflare 未能及时连接源站;等待后重试,并检查源站与网络状态。
推荐排查顺序
1. GET /v1/models 验证 Key、DNS 和网络
2. POST /v1/chat/completions stream=false 的普通文本
3. 用模型列表中的 id 重试
4. 再开 stream、图片、工具或 Agent
5. 最后切换备用域名或代理
Cloudflare、网络与反代
| 场景 | 检查 |
|---|---|
| 推荐地址 | OpenAI 使用 https://beiluoxi.xyz/v1;Claude 使用 https://beiluoxi.xyz;Gemini 使用 https://beiluoxi.xyz/v1beta |
| 备用地址 | OpenAI 使用 https://beiluoxi.top/v1;Claude 使用 https://beiluoxi.top;Gemini 使用 https://beiluoxi.top/v1beta |
| 地址切换 | 两个域名接入同一套北洛 AI 服务;切换时保持 Key、协议和模型不变,只替换域名 |
| 遇到 524 | 等待片刻后有限重试;可切换备用域名排除本地线路问题,持续失败时记录时间和请求路径 |
| DNS / Cloudflare | A 记录指向当前服务器;修改后等待缓存;API 使用 HTTPS |
| 橙云 SSL | Full 或 Full (strict),源站证书模式保持一致 |
| API 超时 | 同时检查 Cloudflare、反代读取超时和上游响应时间 |
| 本地代理 | 不改写 Host、Authorization、Content-Type、SSE 或请求体 |
| Nginx | 需要下划线请求头时在 http 块设置 underscores_in_headers on; |
| Caddy/Nginx SSE | 关闭缓冲;WebSocket 需要透传 Upgrade/Connection |
| 网页与 API | /help 是网页;/v1、/v1beta 才是接口 |
安全与验收
使用注意事项
| 事项 | 做法 |
|---|---|
| Key | 每个软件单独一个;泄露立即停用 |
| 卡密 | 只在兑换页使用,不是 API Key |
| 重试 | 只对 429/502/503/504/524 有限退避;400/401/403/404/413 先修请求、凭据或权限 |
| 浏览器 | 自建网页不要把 Key 写死在前端;无限画布请使用独立 Key,并避免在截图或分享中泄露 |
| 软件下载 | CCS 和客户端只从官网/官方仓库获取 |
| 隐私 | 上传图片、代码、提示词前确认组织权限和服务条款 |
| 客服信息 | 提供时间、版本、协议、路径、状态码;不要发密码/卡密/完整 Key |
接入完成检查
[ ] 卡密已兑换,余额/额度可见
[ ] Key 来自“API 密钥”页面且未泄露
[ ] OpenAI 使用 https://beiluoxi.xyz/v1
[ ] Claude 使用 https://beiluoxi.xyz(不加 /v1)
[ ] Gemini 使用 /v1beta + x-goog-api-key
[ ] Model 从模型列表复制
[ ] 普通文本 stream=false 成功
[ ] 高级功能逐项开启
[ ] 备用地址为 beiluoxi.top,切换时只替换域名
[ ] 无限画布页面与 API 地址没有填反,画布 Base URL 不加 /v1
[ ] CCS 只从官网或官方 GitHub 下载