算力云享
算力云享
算力 API

平台算力 API

API 商城托管模型请用 Base https://api.suanliyunxiang.com/platform/v1，不要写成 /v1 或实例 REST

最后更新：2026 年 9 月 17 日

1. 先选对路径（不要混用）

  • 租 GPU / 管实例：走 REST https://api.suanliyunxiang.com/api/v1（创建、停止、钱包）。这不是 OpenAI 兼容推理，不能拿来当 Chat Completions Base。文档见 /docs/api。
  • 调托管模型（API 商城 / 平台 API）：OpenAI 兼容 Base 只能是 https://api.suanliyunxiang.com/platform/v1 。文档见 /docs/platform-api。
  • 调 GPU 池公开模型（模型中心）：OpenAI 兼容 Base 是 https://api.suanliyunxiang.com/v1 ，随出租主机在线变化。文档见 /docs/model-hub。
  • 禁止把 /v1 当成平台 API，也禁止把 /platform/v1 当成租 GPU。SDK 的 base_url 必须与控制台当前产品页展示的 Base 完全一致。
  • 新建密钥必须选定「平台 API」或「模型中心」。绑定后只能打对应 Base；旧密钥未绑目录时两套都能打。
  • 调用 /platform/v1 与 /v1 推理接口时，请在请求头携带 X-Request-Id（也可用 X-Idempotency-Key）。同一笔调用超时重试必须用同一个号。未带头时网关仅对约 3 分钟内完全相同的请求体做短窗去重。详见 /docs/platform-api#request-id。
  • 旧路径 /api/platform-services/{slug}/v1/... 与控制台同源 /api/api-products/{slug}/v1/... 只给网页试玩用，脚本与 SDK 不要当作对外 Base。

2. SLA 与服务条款

  • 平台 API 与 GPU 实例是不同产品：实例三档 SLA 不适用于 /platform/v1。
  • 可用性、错误码、中断免扣费与账单异议规则见 /docs/sla#platform-api。
  • 具有法律约束力的约定见《用户服务条款》「平台 API 服务条款与 SLA」（/terms#platform-api）。

3. 认证方式

  • 在控制台「开发者」创建密钥时必须选定「平台 API」，并勾选「调用模型 API」（services:invoke）。该密钥只能打 /platform/v1，不能打模型中心 /v1。不含实例管理。
  • 请求头携带 Authorization: Bearer <api_key>（不要用 X-Api-Key）。
  • OpenAI SDK / 脚本的 base_url 必须是 https://api.suanliyunxiang.com/platform/v1 。
  • 选模型与复制示例请到控制台「平台 API」（/dashboard/platform-api）或 API 商城 /services，不要复制「模型中心」页的 /v1 Base。
  • Web 控制台 Cookie 不建议用于服务端脚本。试玩台请带 catalog=api。

4. 幂等请求号 X-Request-Id（计费必读）

  • 平台按请求号冻结和扣费。请求号来自请求头 X-Request-Id；若未带该头，也可使用 X-Idempotency-Key。两者都空时，网关会生成 req_ 开头的编号。
  • X-Request-Id 由调用方自己生成（推荐 UUID，最长 64 字符），不是从我们接口预先申请的。同一笔业务（含超时、断网、SDK 自动重试）必须始终使用同一个号；用户发起的新任务再换新号。
  • 成功和失败响应都会回写响应头 X-Request-Id；错误 JSON 的 error.request_id 与之一致。若第一次请求尚未返回任何头就超时，只有你本地保存的号才能在重试时对上原单。
  • OpenAI 官方 SDK 默认重试不会自动带同一 X-Request-Id。未带头时，网关会在约 3 分钟内对「同一用户 + 密钥 + 方法 + 路径 + 请求体」做短窗指纹去重，复用同一计费号，避免网络抖动被冻两次、扣两次。这是兜底，不能替代你自己带头。
  • 重试仍用同一号时：任务进行中返回 409 request_in_progress（不会再调上游）；已计费完成返回 409 duplicate_request（请换新号发新任务）。上一笔已取消计费后，未带头的相同请求体会换新号，允许真正重试。
  • curl 示例：先 REQUEST_ID=$(uuidgen)，再 -H "X-Request-Id: $REQUEST_ID"。OpenAI Python：extra_headers={"X-Request-Id": request_id}。OpenAI Node：第二个参数 { headers: { "X-Request-Id": requestId } }。控制台试玩会自动带号。

5. 对话 POST /platform/v1/chat/completions

  • POST https://api.suanliyunxiang.com/platform/v1/chat/completions
  • model 以 API 商城当前上架 SKU 为准（控制台「平台 API」卡片上的 model=）。
  • 请求体兼容 OpenAI Chat Completions：model、messages、stream 等。未设置 max_tokens / max_completion_tokens 时，网关默认注入 4096；超过 8192 会被硬顶。非流式返回 JSON；stream: true 返回 SSE。
  • 按 Token 计费：入/出/缓存分段合计后四舍五入到分；成功调用不足 1 分按 1 分收取。未配置缓存命中价即不启用折扣，命中 Token 按输入价。控制台「API 调用记录」金额与上述公式一致。
  • GPU 池对话（如 qwen2.5-7b）请改用 /docs/model-hub，Base 是 /v1，不是本页。

6. 向量嵌入 Embeddings

  • 若 API 商城上架了向量 SKU：POST https://api.suanliyunxiang.com/platform/v1/embeddings ，model 以目录为准。
  • 请求需 Bearer 密钥。平台不托管业务侧向量索引。
  • 若该 SKU 只出现在模型中心，请改用 https://api.suanliyunxiang.com/v1/embeddings。

7. 图片生成 POST /platform/v1/images/generations

  • POST https://api.suanliyunxiang.com/platform/v1/images/generations
  • 图生图：POST https://api.suanliyunxiang.com/platform/v1/images/edits（JSON：prompt + image，可选 strength）。
  • model、size、计费以 API 商城该 SKU 为准；控制台预览 /dashboard/image?catalog=api。
  • GPU 池出图（如 kolors 图像池）请用 /docs/model-hub#images-generations，Base 是 /v1。

8. 视频生成 POST /platform/v1/videos/generations

  • POST https://api.suanliyunxiang.com/platform/v1/videos/generations
  • model、分辨率、时长以 API 商城当前视频 SKU 为准（控制台「平台 API」筛选「视频」）。
  • 试玩：/dashboard/video?catalog=api。不要对视频调用 /v1 或实例 REST。

9. 限流（429）

  • 公开入口默认每 IP 约 120 次/分钟；密钥与 SKU 还可单独配置 RPM/TPM，超限返回 429 rate_limit_exceeded。
  • 当前生产为单 API 进程时，密钥/SKU 限额按本机计数，数值准确。
  • 若水平扩展为多个 API 副本且未配置共享 REDIS_URL，各副本各自计数，实际可达到约「副本数 × 限额」。扩容前必须接入 Redis，并把 REDIS_REQUIRED=true。探活 /health 的 rate_limit_backend 为 redis 或 memory。

10. 流式 SSE

  • 设置 stream: true 后，响应为 Server-Sent Events（SSE）。
  • 每个 data: 行包含 JSON 片段；流结束以 data: [DONE] 或含 usage 的最终块标识。
  • 响应头 X-Suanli-Stream-Status：complete（正常完成）、interrupted（中断）。
  • 客户端应处理断连与超时，再用下方账户侧续传接口恢复（续传不是 OpenAI Base 上的路径）。

11. 中断计费（免扣费）

  • 流式响应未正常完成（无 [DONE]、连接中断、上游 5xx）时，billing_status=interrupted。
  • 中断记录 amount_cents=0，不产生钱包扣费流水。
  • 可在「账户 → API 调用记录」查看计费状态；中断行可能含 resume_token。

12. 续传（账户 REST，不是 OpenAI Base）

  • POST https://api.suanliyunxiang.com/api/v1/platform-services/{slug}/continue
  • 这是账户 REST，不要写成 /platform/v1/continue 或 /v1/continue。
  • 请求体：{ "resume_token": "<token>" }，token 来自中断响应头 X-Suanli-Resume-Token 或调用记录。
  • 续传成功后按最终 usage 计费。会话默认 24 小时有效。

13. 查询续传会话

  • GET https://api.suanliyunxiang.com/api/v1/platform-services/resume-sessions/{token}
  • 同样属于 /api/v1 账户 REST，不是 /platform/v1。
  • 返回 resume_token、status、partial_assistant_text、expires_at 等，用于确认会话是否仍有效。
返回文档中心

需要更多帮助？ 联系客服