北洛 AI · 接入文档OpenAI / Claude / Gemini 兼容接口

北洛 AI 接入文档

按快速开始创建 API Key 并验证模型列表,再根据客户端选择接口协议。画布、图片能力和常见错误分别整理在后续章节。

最后更新:2026-10-20 · 推荐地址 beiluoxi.xyz · 备用地址 beiluoxi.top
先看这里画布页面地址和 API 地址不是一回事

画布地址用来打开工具;API 地址用来连接北洛 AI 模型服务。

无限画布页面beiluoxi.xyz/canvas/画布直连入口,不经过 .top
画布推荐 API 地址https://beiluoxi.xyz与画布同域,末尾不加 /v1
备用 API 地址https://beiluoxi.top推荐地址不通时再切换

无限画布选择 OpenAI 格式;Base URL 填上方任一北洛域名,末尾不要添加 /v1。普通 OpenAI 客户端则按下方卡片填写完整地址。

快速开始

01 · 聊天与编程工具OpenAI 兼容https://beiluoxi.xyz/v1备用:https://beiluoxi.top/v1
02 · Claude 客户端Claude / Anthropichttps://beiluoxi.xyz备用:https://beiluoxi.top · 不加 /v1
03 · Gemini 原生接口Gemini APIhttps://beiluoxi.xyz/v1beta备用:https://beiluoxi.top/v1beta

四步完成首次接入

  1. 创建本站 API Key在“API 密钥”页面创建;登录密码和卡密都不能代替 API Key。
  2. 选择协议并填写地址按客户端类型使用上方对应地址,留意是否需要 /v1 或 /v1beta。
  3. 获取并复制模型使用客户端的模型列表或下方命令,模型名称照返回结果填写。
  4. 先发普通文本先关闭工具调用等高级选项,确认基础请求成功后再逐项启用。
先确认 Key 能读取模型把 YOUR_API_KEY 替换成本站 API Key;从返回的 id 复制模型名称。
curl https://beiluoxi.xyz/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

先确认模型名和能力

模型名称请从 /v1/models 返回的 id 原样复制。图片生成请选择本站已开放且支持生图的模型;不要把图片模型当作视频模型使用。获取模型列表成功只代表地址、Key 和模型列表接口可访问,不代表每种生成能力都已开通。画布的详细配置见“无限画布与模型能力”。

快速排查

401 认证404 路径429 频率/额度502/503/504 服务端524 源站连接
现象 先做什么 不要做什么
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 已完成图片生成测试

基本用法:

  1. 先在设置中保存渠道,并使用“获取模型”检查 Key 和地址是否正确。
  2. 新建画布项目,在画布中添加图片生成节点或从工作台输入提示词。
  3. 选择图片模型、尺寸和数量,连接参考图后可进行图生图或图片编辑。
  4. 生成结果可以继续拖到画布上编排、对比和下载。
  5. 画布、素材、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 通常说明请求在进入模型前被拒绝,但也可能来自网关策略、分组设置或上游限制,不能只凭状态码判断责任方。

5xx:优先检查服务、上游与超时

推荐排查顺序

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 下载