开发者
实例 REST API
通过 REST 创建实例、查询状态与管理账户；调模型请另见平台 API / 模型中心文档
最后更新：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」或「模型中心」。绑定后只能打对应 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. 基础信息
- 本页只讲实例与钱包 REST：路径前缀 /api/v1（同时兼容 /api）。对话、生图请分别看 /docs/platform-api 与 /docs/model-hub。
- 数据格式：请求与响应均为 JSON，字符编码 UTF-8。
- 时间字段：ISO 8601 格式（UTC 或带时区偏移，以字段文档为准）。
- 公开请求默认受每客户端 120 次/分钟的保护性限流，认证、代理与推理端点还可有更严格的独立限制；超限时返回 429。
3. 认证方式
- 用户 API：在控制台「开发者」创建 Access Key，请求头携带 Authorization: Bearer <token>。
- 新建密钥必须选定「平台 API」或「模型中心」，默认带 services:invoke，只能打对应 Base。管理 GPU 实例须额外勾选 instances:read / instances:write，不要把调模型的密钥同时用来下单停机。
- 主机 Agent：使用注册主机时颁发的 host_key，调用 /agent/* 系列接口上报心跳与任务状态。
- 会话 Cookie：Web 控制台使用 HttpOnly Cookie，不建议在服务端脚本中复用浏览器会话。钱包接口仅登录会话可用，API 密钥不能访问。
- 密钥泄露时应立即在开发者页吊销该密钥并创建新密钥；不要依赖额外的宽限期。
4. 常用端点
- GET /api/v1/instances — 列出当前用户的 GPU 实例（须 instances:read）。
- POST /api/v1/instances — 创建实例（须 instances:write）；body 含 template_id、gpu_model 或 gpu_id、sla_tier、duration_seconds 等。
- POST /api/v1/instances/{id}/stop — 停止实例；POST /api/v1/instances/{id}/resume — 24 小时内尝试恢复（须 instances:write）。
- GET /api/v1/wallet — 查询余额（仅登录会话，API 密钥返回 403）。
- GET /api/v1/instances/recoverable — 列出当前账户在 24 小时窗口内且具备工作区或检查点的可恢复实例。
5. 错误码
- 400：参数错误或业务规则不满足（如余额不足、超过 24 小时无法恢复）。
- 401：未认证或令牌无效；403：无权限操作该资源。
- 404：资源不存在；409：状态冲突（如对运行中实例重复创建迁移）。
- 500/503：服务端或依赖暂时不可用，建议指数退避重试。
6. 调用建议
- 创建自动化脚本前，请先在控制台验证同一流程，并为 API 密钥配置最小必要权限。
- 为 429、500 和 503 使用有上限的指数退避；创建、停止与恢复等写操作要避免无限重试。
- 本页尚未对外提供可下载的官方 SDK 或 OpenAPI 描述文件；请以已发布端点和实际响应字段为准。
- 实例、钱包 REST 见本页；不要把 /api/v1/instances 当成 Chat Completions。
- 托管模型 API 见 /docs/platform-api（Base /platform/v1）。GPU 池模型见 /docs/model-hub（Base /v1）。