Sandbox

全部 REST API 与测试

17 个 Sandbox 接口集中在一个页面，默认使用 Production，也可切换 Test Gateway。

Test 与 Production Gateway 都会连接真实供应商并产生真实费用。执行创建接口前先获取报价 并设置预算上限；保存实例 ID，并始终在 finally 中调用终止接口。

发现与报价

3 个接口：规格、环境与报价。

实例生命周期

6 个接口：列表、创建、详情、暂停、恢复与终止。

执行与制品

6 个接口：Shell、文件、目录、端口与扩展。

审计与历史

2 个接口：实例历史与四类审计流。

每个组件都包含方法、地址、路径参数、查询参数、请求体和发送按钮。使用接口上方的 Production / Test 标签，可在 https://sandbox.xapi.to 与 https://sandbox.test.xapi.to 之间切换；默认选择 Production，任一接口切换后， 本页其他接口会同步到相同环境。 需要身份的接口在组件内填写与所选环境对应的 XAPI-Key，测试 Key 与生产 Key 不要混用。

Sandbox API 端到端测试流程

1

无费用连通性检查

展开 列出可用规格，点击 Try it → Send request。预期 HTTP 200，并确认目标 offering 的 capabilities.exec=true。这一步无需 Key，也不会创建资源。

2

获取报价

展开 获取 Sandbox 报价，在 API Explorer 中填写 XAPI-Key，将 requirements.capabilities 设为 exec, files，并设置 maxEstimatedHourlyUsd=0.20。预期 HTTP 201；复制响应中的 quoteId、 expiresAt 和 estimatedHourlyUsd。报价本身不创建实例。

3

创建并保存实例 ID

展开 创建 Sandbox 实例，把上一步的 quoteId 填入 selection.quoteId，并把 idempotencyKey 改成你本次测试唯一的值，例如 manual-browser-20260813-001。预期 HTTP 202；立即保存响应中的 id。 此时 observedState=PROVISIONING 仍不可执行任务。

4

等待 RUNNING 并执行 marker

用 查询实例详情 每 2 秒查询同一个 id，直到 observedState=RUNNING。随后在 执行 Shell 命令 中执行 printf 'MANUAL_TEST_OK=42\n'。HTTP 应为 201，且 响应同时满足 exitCode=0、stdout 包含 MANUAL_TEST_OK=42。

5

无论成功失败都终止

在 销毁实例 中填写相同实例 id 和新的动作幂等键。提交后继续查询详情，直到 observedState=TERMINATED 或终态 FAILED。关闭网页不能代替终止实例。

6

检查审计、费用和残留

查询四类审计流：operations 中 CREATE/EXEC/TERMINATE 应成功，events 应覆盖 RUNNING 与终态，usageSegments 不应有开放段，billingPeriods 应全部结算。 最后以 state=ACTIVE 查询历史，确认没有本次活动实例。账户实例快照会保留 TERMINATED / FAILED 终态记录，不能用“列表非空”判断仍有资源运行。

API Explorer 里的 Key 只填在凭证输入框，不要写入请求 body、metadata、截图或文档源码。 发请求前再次核对 URL：页面默认使用 https://sandbox.xapi.to；只有明确执行测试验收时， 才切换到 https://sandbox.test.xapi.to。两个环境都会申请真实供应商资源并产生实际费用。

本地新版 CLI 一键验收

如果只想最快确认真实链路，当前未发布的新版 CLI 可从本地源码运行。它会自动执行 quote → create → wait → exec → terminate → cost：

cd /Users/daxiongya/Desktop/Projects/web3/x402/bsc/xapi-workspace/xapi-cli
npm run build
node dist/index.js sandbox run \
  --host sandbox.xapi.to \
  --capabilities exec,files \
  --max-hourly-usd 0.20 \
  --command 'printf "MANUAL_TEST_OK=42\n"' \
  --format pretty

通过时重点看：readyState=RUNNING、result.exitCode=0、marker 出现在 stdout、 cleanup.state=TERMINATED、finalState=TERMINATED，并记录服务端返回的 totalCost。

发现与报价

列出可用规格

无副作用、无需鉴权。用于查看当前资源、能力、生命周期和价格。

列出预置环境

无副作用、无需鉴权。返回当前可售 Offering 明确声明的运行时预置，用于选择 requirements.environmentId。返回 [] 表示当前没有服务商发布稳定的环境预置， 不是接口故障；此时省略 environmentId，改用 capabilities、CPU、内存、GPU 与区域选型。

获取 Sandbox 报价

需要鉴权，但不会创建实例。先设置 maxEstimatedHourlyUsd，保存返回的 quoteId。

实例生命周期

从本组开始会读取或改变账户资源。创建后必须记录实例 ID，并在所有成功、失败和中断路径中终止。

列出账户实例快照

返回账户全部实例，包括终态记录。零残留检查请使用下方历史接口的 state=ACTIVE。

创建 Sandbox 实例

返回 202 只代表请求已接受。重试同一创建必须复用 idempotencyKey。

查询实例详情

轮询到 observedState=RUNNING 后再执行命令或文件操作。

暂停实例

仅在 offering 声明支持 suspension 时使用。

恢复实例

恢复后继续查询详情，直到实例重新进入 RUNNING。

终止实例

放入 finally，提交后继续等待 TERMINATED 或供应商终态 FAILED。

执行与制品

执行 Shell 命令

HTTP 成功并不等于命令成功；还必须检查 exitCode=0。

需要启动 Web 服务等长驻进程时，先确认 Offering 返回 capabilities.backgroundExec=true，再传 background=true。这会创建供应商托管的后台会话； 普通命令不要开启。后台响应只证明会话已接受，仍需轮询应用健康地址确认服务真正就绪。

写入文件

读取文件

列出文件

获取端口访问地址

实例内服务必须使用 background=true 启动并监听 0.0.0.0，且 Offering 同时声明 backgroundExec 与 ports。取得 URL 后仍要带返回的 headers（如有）从外部请求 marker， 不能把“拿到 URL”当成应用就绪。

调用供应商扩展

只调用 offering 明确声明的扩展，例如 runpod.connection_info。

审计与历史

查询实例历史

按状态、实例 ID、provider 和时间范围检索，用于清理门禁与费用核对。

查询实例审计流

分别选择 operations、events、usageSegments 或 billingPeriods。

完成标准

1

业务结果通过

HTTP 状态正确；Shell 同时满足 exitCode=0；文件和公开 URL 包含预期制品。

2

实例进入终态

终止后继续查询，直到 observedState=TERMINATED 或供应商终态 FAILED。

3

审计和费用完整

操作、事件、用量段和账期均可查询，费用使用服务端 totalCost。

4

没有资源遗留

ACTIVE 历史中没有本次测试仍在计费的实例；账户实例快照仍保留终态记录属于正常现象。

需要生成语言代码和查看完整响应 Schema 时，可使用侧栏的 逐接口 API Reference；日常浏览和试调直接留在本页即可。