心云 API 开发者文档

快速开始

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

接入地址

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

认证与令牌

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

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

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

调用示例

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

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": "你好，帮我写一句测试回复。" }
    ]
  }'

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);

视频模型 API

心云视频接口使用 OpenAI 风格的异步任务协议。先创建任务，再轮询任务状态，完成后通过内容接口流式下载 MP4。视频模型是否可用，以当前令牌实际返回的 GET /v1/models 为准。

接口总览

1. 查询可用视频模型

curl https://api.xinyunspace.com/v1/models \
  -H "Authorization: Bearer sk-你的心云令牌"

在返回结果中筛选 supported_endpoint_types 包含 openai-video 的条目。模型的 video_capabilities 用于校验时长、分辨率、画幅和参考素材数量；未知能力会保持为未公开，不要自行猜测。

2. 创建视频任务

curl https://api.xinyunspace.com/v1/videos \
  -X POST \
  -H "Authorization: Bearer sk-你的心云令牌" \
  -H "Idempotency-Key: video-demo-20260818-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sd-2.5-c1",
    "prompt": "一只小猫在窗边看雨，电影感光影，镜头缓慢推进",
    "duration": 10,
    "metadata": { "project": "demo" }
  }'

创建响应包含中转站任务 id / task_id、status、created_at 和价格快照。按秒计费模型会在最终成功视频的可计费秒数确定后结算；按次模型以成功创建一次上游任务为扣费边界；Token 模型按上游真实 usage 结算。

支持的请求字段

也可以使用 multipart/form-data 上传素材，字段名使用 image、images、videos、audios、first_image 或 last_image。Base64/Data URI 受请求大小限制，请勿把完整素材或 Authorization 写入日志。

3. 轮询任务状态

curl https://api.xinyunspace.com/v1/videos/{task_id} \
  -H "Authorization: Bearer sk-你的心云令牌"

建议默认每 7 秒查询一次，只对 GET 查询做有限重试。常见处理中状态包括 submitted、queued 和 in_progress；完成状态兼容 completed、succeeded、success；失败状态兼容 failed、cancelled、expired。

4. 下载成片

curl -L https://api.xinyunspace.com/v1/videos/{task_id}/content \
  -H "Authorization: Bearer sk-你的心云令牌" \
  -o output.mp4

只有任务完成后再调用内容接口。客户端应把响应直接流式写入文件，不要把整个 MP4 一次性读入内存；不要记录完整签名下载 URL。

当前视频模型参考

下面是当前目录中的常用能力摘要。价格和可用性不在文档中固定，实际以你的令牌调用 GET /v1/models 返回为准。

幂等、权限和安全

• POST 超时不要自动重新创建任务；保留并复用同一个 Idempotency-Key 查询原任务。
• 任务 ID 只能由创建该任务的令牌查询和下载，换 Key 访问会被拒绝。
• 素材 URL 使用 HTTPS，避免内网地址、非预期重定向和超大文件。
• 视频任务是异步的，余额不足、并发超限或模型无权限时会直接返回错误，不会创建上游任务。

客户端配置

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

模型与分组

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

常见错误排查

安全建议

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

FAQ

Base URL 到底填到哪里？

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

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

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

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

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