创建 Sandbox 实例

创建一个连接真实供应商、会产生费用的 Sandbox。获取报价不会创建资源；只有调用本接口后， 服务才会预留费用并开始供应实例。

选择创建方式

selection 中必须且只能提供以下一种方式：

maxEstimatedHourlyUsd 只适用于 requirements 方式。需要 Shell、文件、端口或 GPU 时， 应显式声明相应 capability/资源，不要假设所有 offering 都支持。

幂等重试

每次业务创建生成一个稳定且唯一的 idempotencyKey（最长 160 个字符），并在请求超时、 连接中断或未收到响应时复用同一个值。这样可以取回同一次创建，而不是误建第二个计费实例。

• 同一个业务创建重试：复用原 key，并保持 selection、policy 等创建参数不变。
• 新建另一个实例：使用新的 key。
• 使用 quoteId 时，同一 key 的重试可复用该报价；不同 key 复用同一报价会返回 409。
• 同一 key 搭配不兼容的选择或策略：返回 409 Conflict。

202 Accepted 之后

202 仅表示服务已受理创建请求。响应会立即返回实例 id，此时 observedState 通常是 PROVISIONING，还不能执行命令或读写文件。

1. 立即保存响应中的 id，它也是后续查询、操作和清理实例的唯一标识。
2. 轮询 GET /v1/sandboxes/{id}，例如每 2 秒一次，并设置客户端总超时（建议不超过 5 分钟）。
3. RUNNING 表示实例已就绪；只有此时才能调用 exec、files 或 ports 接口。
4. FAILED 或 TERMINATED 是终态，不能继续等待 RUNNING；应查看操作与事件审计定位原因。
5. 客户端等待超时不代表实例没有创建。先按 id 查询并清理，不要换新 key 盲目重试。

计费与清理

创建前服务会检查账户余额并预留初始运行费用及关机费用，余额不足返回 402。 供应中或运行中的实例都可能产生费用；响应中的初始 totalCost 为 0 不代表后续免费。

将 POST /v1/sandboxes/{id}/terminate 放在 finally 中，并继续轮询实例，直到 observedState 为 TERMINATED 或 FAILED。最后读取 totalCost、operations、events、 usage segments 和 billing periods，确认没有开放账期或遗留活动实例。

常见失败

• 400：选择方式不合法、requirements 无效、quote 无效/过期，或 offering 不支持 resumeOnAccess。
• 402：余额不足，无法完成初始费用预留。
• 404：offering 不可用，或 requirements 没有匹配的 offering。
• 409：报价对应的 offering 已变化、报价被另一业务创建使用、达到活动实例上限、幂等参数冲突，或供应商暂时不能创建。
• 429：请求过快；遵循响应中的重试提示，并继续复用原 idempotencyKey。