Sandbox API 概览

SeaCloud Sandbox 提供隔离 Linux 运行时，适用于 Agent、代码执行、文件操作、模板化运行环境、公网预览和用量统计。

Base URL

https://sandbox-service.real-cloud.seaart.ai/api/v1/sandbox

Console 通过 SeaCloud Web 应用访问时，公开路径是：

https://cloud.seaart.ai/api/sandbox/v1

后端服务和 SDK 建议直接访问 Sandbox API Base URL。不要在浏览器代码中暴露 API Key 或 envdAccessToken。

鉴权

Sandbox API 请求使用 SeaCloud API Key：

X-API-Key: <SEACLOUD_API_KEY>

访问沙箱 envdUrl 的运行时接口时，使用创建、详情或 connect 响应里的 token：

X-Access-Token: <envdAccessToken>

GET {envdUrl}/health 等健康检查接口不需要运行时 token。

接口分组

分组	路由	用途
Sandboxes	`/sandboxes`	创建、列表、详情、重连、暂停、续期、超时和删除。
Runtime	`{envdUrl}`	执行命令、读写文件、读取运行时指标。
Templates	`/templates`	列出官方模板并解析模板引用。
Usage	`/sandboxes/usage/*`	查询用量汇总、运行时趋势、存储和费用。
Observability	`/observability/summary`、`/usage/limits`	Dashboard 支持和配额诊断。

响应约定

Sandbox 响应使用 camelCase 生命周期字段：

{
  "sandboxID": "sandbox_...",
  "templateID": "base",
  "status": "running",
  "state": "running",
  "startedAt": "2026-06-10T08:55:50Z",
  "activatedAt": "2026-06-10T08:55:50Z",
  "endAt": "2026-06-10T09:55:50Z",
  "envdUrl": "https://sandbox-router.example/9000-sandbox_...",
  "envdAccessToken": "<opaque-token>"
}

Usage 接口使用 snake_case 字段和 points 数组：

{
  "cycle_type": "minute",
  "current_value": 1.2619,
  "current_unit": "hours",
  "points": [
    { "timestamp": 1781081760000, "value": "0.0333" }
  ]
}

timeline 出现在沙箱生命周期/详情响应中。Usage 趋势接口不返回 timeline，图表数据来自 points。Usage 请求和响应时间戳均推荐使用 Unix 毫秒；请求侧兼容 Unix 秒。

错误结构

{
  "code": 400,
  "message": "timeoutMs is no longer supported in sandbox create requests; use timeout seconds",
  "requestID": "req_..."
}

遇到配额错误时，读取 details.usageEndpoint，并展示返回的 scope、resource、metric、used、limit 和 remaining。