算力云享
算力云享
算力 API

平台算力 API

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

最后更新：2026 年 11 月 5 日

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. Codex、Cursor 与 Claude Code

  • 三件工具使用的协议不同。Codex 走 Responses，Cursor 的 OpenAI 自定义地址走 Chat Completions，Claude Code 走 Anthropic Messages。
  • Codex 在配置里增加模型提供方，密钥放在环境变量里。base_url 只填到 /platform/v1，Codex 会自己请求 /responses。wire_api 省略即可。示例：model_provider = "suanli"，然后 [model_providers.suanli] 里 name = "算力云享"，base_url = "https://api.suanliyunxiang.com/platform/v1"，env_key = "SUANLI_API_KEY"。
  • Cursor：Settings → Models，填入平台 API 密钥并打开 OpenAI API Key。再打开 Override OpenAI Base URL，地址填 https://api.suanliyunxiang.com/platform/v1 。Cursor 请求的是 /chat/completions。模型名用 API 商城当前 SKU。Tab 补全不使用这把密钥。
  • Claude Code 请求 {ANTHROPIC_BASE_URL}/v1/messages。ANTHROPIC_BASE_URL 填 https://api.suanliyunxiang.com/platform 。密钥用 ANTHROPIC_AUTH_TOKEN（Bearer）或 ANTHROPIC_API_KEY（x-api-key），值都是平台 API 密钥。ANTHROPIC_MODEL 填 API 商城 SKU，例如 deepseek-lite，不要填 claude 模型名。网关把 Messages 转成对话再把结果转回。thinking、cache_control 会丢掉。不认识的工具类型返回 400，正文含 Input tag。模型中心 /v1/messages 仍是 501。没有 count_tokens，上下文计数是估算。

5. 幂等请求号 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，正文 message 为「视频正在生成」，status 为 in_progress。处理完成后再用同一个号提交，返回第一次的成功结果，不再扣费。上一笔已取消计费后，未带头的相同请求体会换新号，允许真正重试。响应超过 4MB 时无法保留原结果，完成后重试会返回 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 } }。控制台试玩会自动带号。

6. 对话 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 时，由模型上游使用自己的默认值；超过该模型公布的输出上限时返回 400。非流式返回 JSON；stream: true 返回 SSE。
  • GPU 池对话（如 qwen2.5-7b）请改用 /docs/model-hub，Base 是 /v1，不是本页。

7. Responses POST /platform/v1/responses

  • POST https://api.suanliyunxiang.com/platform/v1/responses
  • Codex 的 base_url 填 https://api.suanliyunxiang.com/platform/v1 。当前 Codex 只走 Responses，会请求这个路径；wire_api 省略时也是 responses。
  • 请求使用 input、instructions、tools。网关把它转成 Chat Completions 调用同一批上架模型，再把结果转回 Responses。max_output_tokens 与对话接口共用该模型的官方输出上限。
  • 平台不保存上一轮。每次 input 都要带上完整对话。只提交 previous_response_id、不带 input 时返回 400。
  • 自定义函数工具可以往返。web_search、file_search、code_interpreter、computer、local_shell 等托管工具返回 400。
  • OpenAI SDK 与 Cursor 的自定义 OpenAI Base URL 仍使用 POST /platform/v1/chat/completions，Base 同样是 https://api.suanliyunxiang.com/platform/v1 。三件工具的配置见「Codex、Cursor 与 Claude Code」。

8. 向量嵌入 Embeddings

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

9. 图片生成 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。

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

  • POST https://api.suanliyunxiang.com/platform/v1/videos/generations
  • 文生视频（如 wan2.6-t2v、cdance）只传 model 和 prompt。图生视频才需要 img_url。参数错误返回 400。
  • 提交后立即返回任务号 id，HTTP 202。用你自己的 X-Request-Id 作为这个任务号；连接断开后，仍用同一个号查询。
  • 查询：GET https://api.suanliyunxiang.com/platform/v1/videos/generations/{id} 。status 为 queued、in_progress、completed、failed、canceled。completed 时各模型的结果地址都在 output.video_url。failed 时 error.code 为 video_generation_failed。
  • 取消排队中的任务：POST https://api.suanliyunxiang.com/platform/v1/videos/generations/{id}/cancel 。上游已经开始生成后不能取消，请继续查询该任务号。
  • model、分辨率、时长以 API 商城当前视频 SKU 为准（控制台「平台 API」筛选「视频」）。
  • 试玩：/dashboard/video?catalog=api。不要对视频调用 /v1 或实例 REST。

11. 限流（429）

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

12. 流式 SSE

  • 设置 stream: true 后，响应为 Server-Sent Events（SSE）。
  • 每个 data: 行包含 JSON 片段；流结束以 data: [DONE] 或含 usage 的最终块标识。
  • 响应头 X-Suanli-Stream-Status：complete（正常完成）、interrupted（中断）。对话 /platform/v1/chat/completions 与文本补全 /platform/v1/completions 都返回该头。实时转发的流在正文结束后以 HTTP Trailer 带回，开始时会声明 Trailer: X-Suanli-Stream-Status；请读完整个流后再查看取值。
  • 客户端应处理断连与超时，再用下方账户侧续传接口恢复（续传不是 OpenAI Base 上的路径）。

13. 中断计费（免扣费）

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

14. 续传（账户 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 小时有效。

15. 查询续传会话

  • 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 等，用于确认会话是否仍有效。
返回文档中心

需要更多帮助？ 联系客服