文档 OpenAI-Compatible New API Relay

心云 API 开发者文档

心云 API 是一个面向个人项目、创作工具和小团队的统一 AI 模型服务入口。这里提供 Base URL、API Key、模型名、客户端配置和常见排错信息，方便你把支持 OpenAI 兼容协议的工具接入到自己的中转站。

创建 API Key 查看调用示例生成图片

Base URL https://api.xinyunspace.com/v1

鉴权方式 Authorization: Bearer sk-...

推荐模型 gpt-5.4 / gpt-5.5

快速开始

如果你的软件支持 OpenAI-compatible、OpenAI API、自定义 Base URL 或自定义模型服务，通常只需要填写三项信息：

创建令牌

进入令牌页面创建 API Key。建议每个项目单独创建一个令牌，方便之后停用、限额和排查。

填写 Base URL

在客户端的 Base URL 中填写 https://api.xinyunspace.com/v1，不要再追加 /chat/completions。

选择模型名

首次测试推荐使用 gpt-5.4。需要更高质量输出时，可以切换到 gpt-5.5。

接入检查：如果客户端已经自动拼接 /v1，请避免重复填写。最终请求地址应类似 https://api.xinyunspace.com/v1/chat/completions。

接入地址

项目	填写内容	说明
Base URL	`https://api.xinyunspace.com/v1`	用于 OpenAI 兼容客户端、脚本和 SDK。
Chat Completions	`POST /chat/completions`	客户端会基于 Base URL 自动拼出完整地址。
Models	`GET /models`	部分客户端会通过该接口读取模型列表。

绝大多数工具只要求填写 Base URL、API Key 和模型名。如果工具要求填写完整接口地址，请使用 https://api.xinyunspace.com/v1/chat/completions。

认证与令牌

所有请求都需要携带你的心云 API Key。不要把上游渠道 Key 写进客户端，也不要把心云 API Key 公开到网页前端、截图、仓库或聊天记录里。

HTTP Header

Authorization: Bearer sk-你的心云令牌
Content-Type: application/json

每个项目建议单独创建一个令牌，方便区分消耗来源。
测试环境和正式环境建议使用不同令牌。
如果令牌疑似泄露，请立即禁用旧令牌并重新创建。
调用失败时，优先检查令牌额度、分组权限和模型可用性。

调用示例

心云 API 使用 OpenAI 兼容协议。下面的示例可以用于命令行、服务端脚本或支持自定义 API 的工具。

curl

curl https://api.xinyunspace.com/v1/chat/completions \
  -H "Authorization: Bearer sk-你的心云令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      { "role": "user", "content": "你好，帮我写一句测试回复。" }
    ]
  }'

JavaScript fetch

const response = await fetch("https://api.xinyunspace.com/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk-你的心云令牌",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "gpt-5.4",
    messages: [
      { role: "user", content: "用一句话介绍心云 API。" }
    ]
  })
});

const data = await response.json();
console.log(data.choices?.[0]?.message?.content);

客户端配置

在 Cherry Studio、OpenAI-compatible 插件、个人脚本、Bot、自动化工具或其他 AI 客户端中，可以按下面的通用方式填写：

配置项	推荐填写	说明
Provider	OpenAI / OpenAI Compatible / Custom	不同客户端名称不同，选择支持自定义接口的一项即可。
Base URL	`https://api.xinyunspace.com/v1`	只填到 `/v1`，不要填完整接口路径。
API Key	`sk-你的心云令牌`	从心云 API 控制台的令牌页面创建。
Model	`gpt-5.4` 或 `gpt-5.5`	根据可用分组和预算选择。

模型与分组

模型可用性取决于你当前账户、令牌分组、余额和后台渠道配置。创建令牌时，请确认令牌有权限调用你准备使用的模型。

推荐模型：gpt-5.4

适合日常问答、写作、代码辅助和工具接入测试。

高质量模型：gpt-5.5

适合更复杂的推理、长文本、方案整理和高质量生成。

分组权限

如果同一个 Key 调用某个模型失败，优先检查令牌是否绑定了对应分组。

常见错误排查

现象	优先检查	处理方式
401 Unauthorized	API Key 是否正确、是否多复制空格	重新复制令牌，确认请求头为 `Authorization: Bearer sk-...`。
403 Forbidden	令牌分组、模型权限、账户状态	检查令牌绑定的服务分组，确认账户可用。
404 Not Found	Base URL 是否重复拼接	Base URL 填 `https://api.xinyunspace.com/v1`，不要把 `/v1` 写两次。
429 Too Many Requests	并发、限速、余额	降低请求频率，或检查令牌额度和账户余额。
模型不存在	模型名拼写、分组权限	确认模型名使用 `gpt-5.4` 或后台当前开放的模型 ID。

安全建议

不要在浏览器前端直连中转站令牌；生产项目建议由自己的服务端代理请求。
不要把 API Key 写入 GitHub、网盘公开分享、网页源码或截图。
为不同工具、项目、团队成员创建不同 Key，出现异常时可以单独停用。
定期查看用量日志和余额变化，发现异常消耗时先禁用相关令牌。

FAQ

Base URL 到底填到哪里？

大多数 OpenAI-compatible 客户端只需要填 https://api.xinyunspace.com/v1。客户端会自动拼接 /chat/completions、/models 等路径。

为什么同一个 Key 有些模型能用，有些不能用？

通常是令牌分组、模型权限或余额状态导致。请先确认令牌是否绑定了对应模型分组。

可以给每个项目单独发一个 Key 吗？

可以，也推荐这样做。独立 Key 更容易控制额度、停用泄露令牌，并按项目查看消耗。