算力 API
平台算力 API
API 商城托管模型请用 Base https://api.suanliyunxiang.com/platform/v1，不要写成 /v1 或实例 REST
最后更新：2026 年 9 月 10 日
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/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」（services:invoke）。新建密钥默认只含此项，不含实例管理。
- 请求头携带 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. 对话 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 等。非流式返回 JSON；stream: true 返回 SSE。
- GPU 池对话（如 qwen2.5-7b）请改用 /docs/model-hub，Base 是 /v1，不是本页。
5. 向量嵌入 Embeddings
- 若 API 商城上架了向量 SKU：POST https://api.suanliyunxiang.com/platform/v1/embeddings ，model 以目录为准。
- 请求需 Bearer 密钥。平台不托管业务侧向量索引。
- 若该 SKU 只出现在模型中心，请改用 https://api.suanliyunxiang.com/v1/embeddings。
6. 图片生成 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。
7. 视频生成 POST /platform/v1/videos/generations
- POST https://api.suanliyunxiang.com/platform/v1/videos/generations
- model、分辨率、时长以 API 商城当前视频 SKU 为准（控制台「平台 API」筛选「视频」）。
- 试玩：/dashboard/video?catalog=api。不要对视频调用 /v1 或实例 REST。
8. 限流（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。
9. 流式 SSE
- 设置 stream: true 后，响应为 Server-Sent Events（SSE）。
- 每个 data: 行包含 JSON 片段；流结束以 data: [DONE] 或含 usage 的最终块标识。
- 响应头 X-Suanli-Stream-Status：complete（正常完成）、interrupted（中断）。
- 客户端应处理断连与超时，再用下方账户侧续传接口恢复（续传不是 OpenAI Base 上的路径）。
10. 中断计费（免扣费）
- 流式响应未正常完成（无 [DONE]、连接中断、上游 5xx）时，billing_status=interrupted。
- 中断记录 amount_cents=0，不产生钱包扣费流水。
- 可在「账户 → API 调用记录」查看计费状态；中断行可能含 resume_token。
11. 续传（账户 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 小时有效。
12. 查询续传会话
- 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 等，用于确认会话是否仍有效。