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