开发者
API 接口文档
通过 API 程序化创建实例、查询状态与管理账户资源
最后更新：2026 年 6 月 1 日
1. 基础信息
- API 基址：https://api.suanliyunxiang.com/v1（生产环境以控制台公示为准）。
- 数据格式：请求与响应均为 JSON，字符编码 UTF-8。
- 时间字段：ISO 8601 格式（UTC 或带时区偏移，以字段文档为准）。
- 速率限制：默认每用户 120 次/分钟；超出返回 429，响应头含 Retry-After。
2. 认证方式
- 用户 API：在控制台「账户 → 安全 → API 密钥」创建 Access Key，请求头携带 Authorization: Bearer <token>。
- 主机 Agent：使用注册主机时颁发的 host_key，调用 /agent/* 系列接口上报心跳与任务状态。
- 会话 Cookie：Web 控制台使用 HttpOnly Cookie，不建议在服务端脚本中复用浏览器会话。
- 密钥泄露时应立即轮换；旧密钥在轮换后 5 分钟内失效。
3. 常用端点
- GET /api/instances — 列出当前用户的 GPU 实例，支持 status、gpu_model 筛选。
- POST /api/instances — 创建实例，body 含 template_id、gpu_model、sla_tier（standard|protected|critical）、planned_duration_seconds 等。
- POST /api/instances/{id}/stop — 停止实例；POST /api/instances/{id}/resume — 24 小时内恢复（需有效工作区）。
- GET /api/wallet — 查询余额；GET /api/wallet/transactions — 分页查询消费与充值记录。
- GET /api/recoverable — 列出可恢复实例（含 24 小时内已停止且保留工作区者）。
4. 错误码
- 400：参数错误或业务规则不满足（如余额不足、超过 24 小时无法恢复）。
- 401：未认证或令牌无效；403：无权限操作该资源。
- 404：资源不存在；409：状态冲突（如对运行中实例重复创建迁移）。
- 500/503：服务端或依赖暂时不可用，建议指数退避重试。
5. SDK 与示例
- 官方提供 Python 与 Go 示例仓库（见 GitHub 组织 suanli-cloud），涵盖创建实例、轮询状态、SSH 密钥注入。
- Webhook：企业版可配置实例状态变更回调，签名算法 HMAC-SHA256，密钥在组织设置中管理。
- OpenAPI 3.0 描述文件可在 /openapi.json 下载，用于导入 Postman 或生成客户端。
- 平台算力 API（Chat Completions、流式续传、中断计费）详见文档：/docs/platform-api。