沙箱服务 API 调用指南

本文档介绍如何通过 RESTful API 或 Python SDK 接入沙箱服务，包括沙箱的创建、连接、执行命令、生命周期管理，以及模板（沙箱运行环境）的创建与构建。

占位符约定

文档中出现的以下占位符需要替换成你自己的实际值：

这四个值可以在控制台的「沙箱服务－沙箱接入」页面中，选择 API Key、模板后统一获取，示例代码可以直接复制使用。

认证方式

所有接口统一使用 X-API-Key 请求头传递 API Key：

X-API-Key: {{API_KEY}}

通用响应格式

• 成功响应：HTTP 状态码 2xx，响应体是对应接口的数据结构（见各接口的「响应结构」）；部分接口（如暂停、销毁）成功后只返回状态码，没有响应体。
• 错误响应：HTTP 状态码 4xx/5xx，响应体统一为：

{
  "code": 400,
  "message": "具体错误描述"
}

常见状态码含义：

一、沙箱生命周期管理接口

1.1 创建沙箱

[POST] /sandboxes

基于指定模板创建一个新的沙箱实例。

• 请求 Body：

📌 关于「不传字段回退到模板默认值」：envVars / network / volumeMounts / idlePolicy 这几个字段，只有请求体里完全不出现这个字段（或显式传 null）才会触发「套用模板默认配置」；如果传了一个空对象/空数组（如 "envVars": {}），会被当作「我就是要传空值」，不会去看模板配置了什么。

network 对象：

volumeMounts 数组，每项对象：

idlePolicy 对象：

• 请求示例

curl -X POST "https://{{DOMAIN}}/sandboxes" \
  -H "X-API-Key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "templateID": "{{TEMPLATE_ID}}",
    "timeout": 300,
    "envVars": {"MY_VAR": "hello"},
    "metadata": {"app": "demo"}
  }'

• 响应示例（201 Created）

{
  "sandboxID": "ix0it63ws9rx20wbwp56c",
  "templateID": "glsf46v0atv98q90g3or",
  "clientID": "6532622b",
  "alias": "my-template",
  "envdVersion": "0.2.0",
  "envdAccessToken": null,
  "domain": "kwai-sandbox-proxy-commercial.corp.kuaishou.com",
  "envVars": {"MY_VAR": "hello"},
  "volumeMounts": [],
  "network": {
    "allowPublicTraffic": true
  }
}

• 响应结构

• 状态码

1.2 查询沙箱详情

[GET] /sandboxes/{sandboxID}

• Path 参数

无请求体、无 query 参数。

• 请求示例

curl "https://{{DOMAIN}}/sandboxes/{sandboxID}" \
  -H "X-API-Key: {{API_KEY}}"

• 响应示例（200 OK）

{
  "sandboxID": "ix0it63ws9rx20wbwp56c",
  "templateID": "glsf46v0atv98q90g3or",
  "clientID": "6532622b",
  "alias": "my-template",
  "startedAt": "2026-09-14T10:00:00Z",
  "endAt": "2026-09-14T10:05:00Z",
  "envdVersion": "0.2.0",
  "domain": "kwai-sandbox-proxy-commercial.corp.kuaishou.com",
  "cpuCount": 2,
  "memoryMB": 1024,
  "diskSizeMB": 1024,
  "metadata": {"app": "demo"},
  "state": "running",
  "envVars": {"MY_VAR": "hello"},
  "volumeMounts": [],
  "network": {"allowPublicTraffic": true}
}

• 响应结构

• 状态码

1.3 查询沙箱状态（就绪轮询）

[GET] /sandboxes/{sandboxID}/status

沙箱创建/恢复后，内部服务需要一定时间完成初始化；建议在执行命令前先轮询这个接口到 ready，避免过早发起请求失败。

• 请求示例

curl "https://{{DOMAIN}}/sandboxes/{sandboxID}/status" \
  -H "X-API-Key: {{API_KEY}}"

• 响应示例（200 OK）

{
  "state": "ready",
  "createElapsedMs": 850
}

• 响应结构

• 状态码

1.4 暂停沙箱

[POST] /sandboxes/{sandboxID}/pause

保存沙箱当前的文件系统和内存状态，之后可以通过「恢复沙箱」接口还原现场；暂停后的沙箱不会因为超时被自动销毁。

• Query 参数

• 请求示例

curl -X POST "https://{{DOMAIN}}/sandboxes/{sandboxID}/pause" \
  -H "X-API-Key: {{API_KEY}}"

• 响应

成功无响应体。

• 状态码

1.5 恢复沙箱（推荐）

[POST] /sandboxes/{sandboxID}/connect〔推荐〕

将一个已暂停的沙箱恢复运行；如果沙箱本来就在运行中，效果等同于续期。

• 请求 Body

• 请求示例

curl -X POST "https://{{DOMAIN}}/sandboxes/{sandboxID}/connect" \
  -H "X-API-Key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{"timeout": 300}'

• 响应示例

响应体结构同「创建沙箱」接口。

• 状态码

1.6 恢复沙箱（不推荐）

[POST] /sandboxes/{sandboxID}/resume〔不推荐〕

功能与第 5 节的 connect 相同，额外支持「钉」到指定节点恢复；connect 是当前推荐的恢复方式，这个接口仍可正常使用，但后续可能被移除。

• 请求 Body

• 请求示例

curl -X POST "https://{{DOMAIN}}/sandboxes/{sandboxID}/resume" \
  -H "X-API-Key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{"timeout": 300}'

• 状态码

同第 5 节 connect（201 表示恢复成功，不会返回 200）。

1.7 设置超时（覆盖式）

[POST] /sandboxes/{sandboxID}/timeout

以当前请求时刻为起点重新计时，不是在原有剩余时间上累加。

• 请求 Body

• 请求示例

curl -X POST "https://{{DOMAIN}}/sandboxes/{sandboxID}/timeout" \
  -H "X-API-Key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{"timeout": 7200}'

• 响应

成功无响应体。

• 状态码

1.8 续期保活

[POST] /sandboxes/{sandboxID}/refreshes

在沙箱当前剩余存活时间的基础上续期，语义上和「设置超时」接近，但字段名不同（duration），且请求体本身是可选的。

• 请求 Body

• 请求示例

curl -X POST "https://{{DOMAIN}}/sandboxes/{sandboxID}/refreshes" \
  -H "X-API-Key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{"duration": 300}'

• 响应

成功无响应体。

• 状态码

1.9 创建快照

[POST] /sandboxes/{sandboxID}/snapshots

对正在运行的沙箱做一次不中断运行的时间点快照，可以作为新的 templateID 用于创建沙箱（数据回滚点/分支/检查点）。这条接口不接受请求体。

• 请求示例

curl -X POST "https://{{DOMAIN}}/sandboxes/{sandboxID}/snapshots" \
  -H "X-API-Key: {{API_KEY}}"

• 响应示例（202 Accepted）

{
  "snapshotId": "sn1x2y3z4a5b6c7d8e9f0",
  "buildId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "createdAt": "2026-09-14T10:10:00Z",
  "envVars": {"MY_VAR": "hello"},
  "volumeMounts": [],
  "network": {"allowPublicTraffic": true}
}

• 响应结构

📌 注意：202 只表示本地状态捕获完成，数据持久化上传仍在后台异步进行（通常需要数十秒）。上传完成前，用这个 snapshotId 创建沙箱会失败。需要轮询第 15 节「查询构建状态」接口（把 templateID 换成这里的 snapshotId，buildID 换成这里的 buildId）直到状态变为 ready 才能使用。

• 状态码

1.10 销毁沙箱

[DELETE] /sandboxes/{sandboxID}

• 请求示例

curl -X DELETE "https://{{DOMAIN}}/sandboxes/{sandboxID}" \
  -H "X-API-Key: {{API_KEY}}"

• 响应

成功无响应体。

• 状态码

二、连接沙箱执行命令

在沙箱内执行命令（exec）走的不是上面这套接口，而是沙箱内部服务（{{SANDBOX_DOMAIN}}，与管理沙箱元数据用的 {{DOMAIN}} 是两个不同的域名，不能互相替代），协议也不是普通的 JSON REST，而是基于 HTTP 的流式协议（Connect 协议（https://connectrpc.com/），请求体和响应体都需要按固定格式包一层帧头，不能直接发送裸JSON。

生产环境建议直接使用 SDK（如 sandbox.commands.run(...)），SDK 内部已经处理好了这些细节，本节的 curl 示例仅用于临时调试或没有可用 SDK 的场景。

2.1 执行命令

[POST] /process.Process/Start

执行命令（Connect 协议，走 {{SANDBOX_DOMAIN}}）

• 路由方式

请求需要携带以下两个请求头，用于告知网关把请求转发给哪个沙箱：

如果沙箱是以 secure: true 创建的，还需要额外携带创建响应里返回的 envdAccessToken：

• 请求示例

# 1. 拼一个符合协议要求的请求体：5 字节头（1 字节 flag=0x00 + 4 字节大端长度）
#    加上 JSON 内容。真正要执行的命令放进 args 的 -c 参数里。
CMD="echo hello && whoami"
BODY=$(printf '{"process":{"cmd":"/bin/bash","args":["-l","-c","%s"]},"stdin":false}' "$CMD")
LEN=$(printf '%s' "$BODY" | wc -c | tr -d ' ')
{ printf '%02x%08x' 0 "$LEN" | xxd -r -p; printf '%s' "$BODY"; } > /tmp/start_req.bin
 
# 2. 发送请求。Content-Type 必须是 application/connect+json。
curl -sS --max-time 15 \
  -H "X-API-Key: {{API_KEY}}" \
  -H "E2b-Sandbox-Id: {sandboxID}" \
  -H "E2b-Sandbox-Port: 49983" \
  -H "Content-Type: application/connect+json" \
  -H "Connect-Protocol-Version: 1" \
  --data-binary @/tmp/start_req.bin \
  "https://{{SANDBOX_DOMAIN}}/process.Process/Start"

• 响应示例

响应同样是分帧格式的一串 JSON 事件（下面省略帧头只展示内容，实际收到的是二进制流，不建议直接打印到终端，建议先落盘再过滤不可打印字符查看）：

{"event":{"start":{"pid":413}}}
{"event":{"data":{"stdout":"aGVsbG8Kcm9vdAo="}}}
{"event":{"end":{"exited":true,"status":"exit status 0"}}}

• 响应结构

流正常结束时，末尾还会有一个空的结束标记帧，表示这次调用本身（不是命令本身）没有出错。

• 状态码

三、模板管理接口

模板（template）定义了沙箱的运行环境（基础镜像、预装依赖、启动命令等）。

3.1 列表模板

[GET] /templates

• Query 参数

• 请求示例

curl "https://{{DOMAIN}}/templates?keyword=my-python-tpl" \
  -H "X-API-Key: {{API_KEY}}"

• 响应示例（200 OK）

[
  {
    "templateID": "glsf46v0atv98q90g3or",
    "buildID": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "cpuCount": 2,
    "memoryMB": 1024,
    "diskSizeMB": 1024,
    "public": false,
    "name": "my-python-tpl",
    "sandboxCategory": "code",
    "type": "custom",
    "aliases": ["my-python-tpl"],
    "createdAt": "2026-09-01T00:00:00Z",
    "updatedAt": "2026-09-01T00:10:00Z",
    "lastSpawnedAt": null,
    "spawnCount": 0,
    "buildCount": 1,
    "envdVersion": "0.2.0",
    "buildStatus": "ready",
    "available": true,
    "sharedStorageCount": 0
  }
]

• 响应结构（数组，每项字段）

设置了 pageSize 时，响应头会带上：

• 状态码

3.2 注册模板

[POST] /v3/templates

注册一个新模板（或复用已有别名）。这一步只是登记元数据、生成 templateID/buildID，还不会真正开始构建，需要接着调用第 14 节「触发构建」。如果 alias 已存在且属于你，会复用同一个 templateID，只产生一个新的 buildID（相当于给已有模板发起一次新的构建）。

• 请求 Body

• 请求示例

curl -X POST "https://{{DOMAIN}}/v3/templates" \
  -H "X-API-Key: {{API_KEY}}" -H "Content-Type: application/json" \
  -d '{"alias": "my-python-tpl", "cpuCount": 2, "memoryMB": 1024}'

• 响应示例（202 Accepted）

{
  "templateID": "5cdyt5whuantlxrnf2cf",
  "buildID": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "public": false,
  "aliases": ["my-python-tpl"],
  "envVars": {},
  "volumeMounts": [],
  "network": null
}

• 响应结构

• 状态码

3.3 上传构建上下文（可选）

[GET] /templates/{templateID}/files/{hash}

如果构建步骤中需要用到本地文件（比如 Dockerfile 风格构建里的 COPY 指令），需要先把打包好的 tar 文件上传。这一步是幂等的：先查询内容的哈希是否已经在缓存中，命中则跳过上传。

• Path 参数

• 请求示例

# 1. 计算 tar 包内容的 hash
HASH=$(sha256sum build-context.tar | awk '{print $1}')
 
# 2. 查询是否已在缓存中
curl "https://{{DOMAIN}}/templates/{templateID}/files/${HASH}" \
  -H "X-API-Key: {{API_KEY}}"

• 响应示例（201 Created）

{
  "present": false,
  "url": "https://storage.example.com/upload-signed-url..."
}

• 响应结构

present=false 时，用这个 url 直接 PUT 文件内容完成上传：

curl -X PUT "$UPLOAD_URL" --data-binary @build-context.tar

• 状态码

3.4 触发构建

[POST] /v2/templates/{templateID}/builds/{buildID}

正式开始构建。templateID/buildID 来自第 12 节「注册模板」的响应。

• Path 参数

• 请求 Body

steps 数组，每项对象：

各步骤类型的 args 含义：

• 请求示例

curl -X POST "https://{{DOMAIN}}/v2/templates/{templateID}/builds/{buildID}" \
  -H "X-API-Key: {{API_KEY}}" -H "Content-Type: application/json" \
  -d '{
    "fromImage": "registry.example.com/base-images/python:3.11",
    "steps": [{"type": "RUN", "args": ["pip install numpy pandas"]}],
    "startCmd": "",
    "readyCmd": ""
  }'

• 响应

成功无响应体，仅返回状态码。

• 状态码

3.5 查询构建状态

[GET] /templates/{templateID}/builds/{buildID}/status

轮询这个接口直到状态变为 ready 或 error，用于确认构建何时完成。

• Query 参数

• 请求示例

curl "https://{{DOMAIN}}/templates/{templateID}/builds/{buildID}/status" \
  -H "X-API-Key: {{API_KEY}}"

• 响应示例（200 OK）

{
  "templateID": "5cdyt5whuantlxrnf2cf",
  "buildID": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "status": "building",
  "logs": ["Step 1/3: RUN pip install numpy pandas"],
  "logEntries": [
    {"timestamp": "2026-09-14T10:00:01Z", "message": "Step 1/3: RUN pip install numpy pandas", "level": "info"}
  ]
}

• 响应结构

• 状态码

3.6 查询构建详情（完整日志）

[GET] /templates/{templateID}/builds/{buildID}

一次性返回某次构建的完整日志，不用于轮询进行中的构建（轮询请用第 15 节）。

• 请求示例

curl "https://{{DOMAIN}}/templates/{templateID}/builds/{buildID}" \
  -H "X-API-Key: {{API_KEY}}"

• 响应示例（200 OK）

{
  "buildID": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "status": "ready",
  "createdAt": "2026-09-14T10:00:00Z",
  "updatedAt": "2026-09-14T10:02:30Z",
  "finishedAt": "2026-09-14T10:02:30Z",
  "cpuCount": 2,
  "memoryMB": 1024,
  "diskSizeMB": 1024,
  "envdVersion": "0.2.0",
  "logs": ["..."],
  "logEntries": [{"timestamp": "2026-09-14T10:00:01Z", "message": "...", "level": "info"}]
}

• 响应结构

• 状态码

3.7 查询模板详情（含构建历史）

[GET] /templates/{templateID}

• Query 参数

• 请求示例

curl "https://{{DOMAIN}}/templates/{templateID}" \
  -H "X-API-Key: {{API_KEY}}"

• 响应示例（200 OK）

{
  "templateID": "5cdyt5whuantlxrnf2cf",
  "public": false,
  "name": "my-python-tpl",
  "sandboxCategory": "custom",
  "type": "custom",
  "aliases": ["my-python-tpl"],
  "createdAt": "2026-09-14T10:00:00Z",
  "updatedAt": "2026-09-14T10:02:30Z",
  "lastSpawnedAt": null,
  "spawnCount": 0,
  "sharedStorageCount": 0,
  "builds": [
    {
      "buildID": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "status": "ready",
      "createdAt": "2026-09-14T10:00:00Z",
      "updatedAt": "2026-09-14T10:02:30Z",
      "finishedAt": "2026-09-14T10:02:30Z",
      "cpuCount": 2,
      "memoryMB": 1024
    }
  ]
}

• 响应结构

模板本身的字段同第 11 节「列表模板」响应，额外增加：

• 状态码

3.8 删除模板

[DELETE]/templates/{templateID}

• 请求示例

curl -X DELETE "https://{{DOMAIN}}/templates/{templateID}" \
  -H "X-API-Key: {{API_KEY}}"

• 响应

成功无响应体。

• 状态码

四、Python SDK 完整示例

以下示例完全使用开源 e2b SDK（pip install e2b，2.10+ 版本写法），覆盖创建 / 查详情 / 查状态 / 连接执行命令（含常用的 exec / 文件读写）/ 暂停 / 恢复（推荐用 connect）/ 设置超时 / 续期保活 / 创建快照 / 销毁沙箱，以及模板管理（注册 / 构建 / 查询 / 删除）全部操作。

e2b 官方 SDK 目前未覆盖的几个接口（查询就绪状态、续期保活、创建快照、模板管理）通过 httpx 直接调用上面介绍的 RESTful 接口，复用同一套 domain / api_key。

"""
KwaiSandbox 完整接入示例（完全使用开源 e2b SDK，pip install e2b，2.10+ 版本
写法；不依赖 kwaisandbox 包）。覆盖 create/查详情/查状态/连接执行命令
（含最常用的 exec/文件读写）/pause/connect（推荐恢复）/set_timeout/
keepAlive/snapshot/kill 全部操作，以及模板管理（注册/构建/查询/删除）。
 
e2b 官方 SDK 目前没有覆盖的几个接口（查 envd 就绪状态 /status、续期
keepAlive /refreshes、创建快照 /snapshots、模板管理 /templates*）是这个
平台在 e2b 协议基础上加的扩展，SDK 没有对应方法，直接用 httpx 发原始
请求，复用同一套 domain/api_key，不是另起一个 client。
"""
import hashlib
import os
import time
 
import httpx
from e2b import Sandbox
from e2b.connection_config import ConnectionConfig
from e2b.exceptions import SandboxException
 
DOMAIN = "{{DOMAIN}}"
SANDBOX_DOMAIN = "{{SANDBOX_DOMAIN}}"
API_KEY = "{{API_KEY}}"
 
os.environ["E2B_DOMAIN"] = DOMAIN
os.environ["E2B_API_URL"] = f"https://{DOMAIN}"
# envd（执行命令/文件系统，第 4/6 步要用）走独立的 proxy 域名，不能用上面
# 那个 control-plane 域名——本平台两者证书/AccessProxy 网关注册都是分开的，
# 混用会导致 envd 的 Connect RPC 请求被打到 API 服务，报
# "no matching operation was found"（API 的 OpenAPI 校验中间件在拒绝一个
# 不在 spec/openapi.yml 里的路径）。同时 e2b 默认的
# `{port}-{sandboxID}.{domain}` 泛子域名寻址也会被 AccessProxy 拒绝，所以
# 不能用默认 domain 拼子域名，只能整个换成这个独立注册的 proxy 域名。
os.environ["E2B_SANDBOX_URL"] = f"https://{SANDBOX_DOMAIN}"
os.environ["E2B_API_KEY"] = API_KEY
 
# 平台扩展接口（e2b SDK 未覆盖）统一走这个 httpx client，复用同一个 domain/api_key
api = httpx.Client(base_url=f"https://{DOMAIN}", headers={"X-API-Key": API_KEY}, timeout=30)
 
# 1. 创建沙箱
sandbox = Sandbox.create(template="{{TEMPLATE_ID}}", timeout=300)
print("created:", sandbox.sandbox_id)
 
# 2. 查询沙箱详情
info = sandbox.get_info()
print("state:", info.state)
 
# 3. 查询沙箱状态（envd 就绪轮询；GET /sandboxes/{id}/status 是平台扩展
#    接口，e2b SDK 没有对应方法，直接调 REST）
while api.get(f"/sandboxes/{sandbox.sandbox_id}/status").json()["state"] != "ready":
    time.sleep(2)
 
# 4. 连接沙箱后执行命令（最常用）：exec + 文件读写
#    刚 create() 出来的这个 sandbox 实例已经自动带好了 envd 需要的
#    E2b-Sandbox-Id/E2b-Sandbox-Port 请求头，可以直接用；如果是拿一个
#    已有 sandboxID 重新 Sandbox.connect() 连接（比如换了一个进程/脚本），
#    这两个 header 不会自动带上，要手动传，见下面"6. 恢复沙箱"的写法。
res = sandbox.commands.run("echo $HOME && whoami")
print("stdout:", res.stdout, "exit_code:", res.exit_code)
 
# 传环境变量 / 指定用户
res = sandbox.commands.run("env | grep MY_VAR", envs={"MY_VAR": "hello"}, user="user")
 
# 后台执行，拿 handle 自己控制生命周期
handle = sandbox.commands.run("sleep 30", background=True)
# ...干别的事...
handle.kill()
 
# 写文件 / 读文件 / 列目录
sandbox.files.write("/tmp/hello.txt", "hello from e2b sdk\n")
content = sandbox.files.read("/tmp/hello.txt")
print("file content:", content)
for entry in sandbox.files.list("/tmp"):
    print(entry.name, entry.type)
 
# 5. 暂停沙箱（beta 接口，2.10 版本 SDK 里 pause 挂在 beta_pause 下）
sandbox.beta_pause()
 
# 6. 恢复沙箱（推荐：connect）。重新连接一个不是当前进程刚建出来的已有
#    沙箱时，要手动补上 E2b-Sandbox-Id/E2b-Sandbox-Port 两个 header，
#    envd 的请求才能被正确路由到这台沙箱，见本文档第二章"连接沙箱执行
#    命令"一节。connect() 没有内置 409 退避重试（快照可能还在异步上传），
#    需要自己包一层重试。
for _ in range(10):
    try:
        sandbox = Sandbox.connect(
            sandbox.sandbox_id,
            timeout=300,
            headers={
                "E2b-Sandbox-Id": sandbox.sandbox_id,
                "E2b-Sandbox-Port": str(ConnectionConfig.envd_port),
            },
        )
        break
    except SandboxException as e:
        if "in progress" not in str(e):
            raise
        time.sleep(3)
 
# 备选：resume（已弃用，仅在需要钉节点恢复时用，e2b SDK 未覆盖，直接
#     调 REST：POST /sandboxes/{sandboxID}/resume -d '{"timeout":300,"nodeName":"node-7"}'）
 
# 7. 设置超时（覆盖式，从当前时刻起重新计时）
sandbox.set_timeout(7200)
 
# 8. 续期保活（平台扩展接口，e2b SDK 未覆盖）
api.post(f"/sandboxes/{sandbox.sandbox_id}/refreshes", json={"duration": 300})
 
# 9. 创建快照（平台扩展接口，e2b SDK 未覆盖）
snap = api.post(f"/sandboxes/{sandbox.sandbox_id}/snapshots").json()
print("snapshot:", snap["snapshotId"])
 
# 10. 销毁沙箱
sandbox.kill()
 
# ---- 模板管理（e2b SDK 未覆盖以下几步，统一用 httpx 直连 REST） ----
 
# 11. 列表模板（可选）
templates = api.get("/templates", params={"keyword": "my-python-tpl"}).json()
print("total:", len(templates))
 
# 12. 注册模板（v3，走 alias 复用：alias 已存在时复用同一个 templateID，只产生新 buildID）
resp = api.post("/v3/templates", json={"alias": "my-python-tpl", "cpuCount": 2, "memoryMB": 1024}).json()
new_template_id, build_id = resp["templateID"], resp["buildID"]
print("registered:", new_template_id, build_id)
 
# 13. 上传 build context：先查该内容 hash 是否已在缓存里，命中则跳过上传
with open("build-context.tar", "rb") as f:
    build_context = f.read()
file_hash = hashlib.sha256(build_context).hexdigest()
upload = api.get(f"/templates/{new_template_id}/files/{file_hash}").json()
# 防御性检查：这个查询本身也可能失败（比如后端 500，响应体是
# {"code":500,"message":"..."}，没有 present 字段）——不能假设"没有
# present 就是已经存在，可以跳过上传"，那样会把一次真正的查询失败悄悄
# 当成"缓存命中"放过，直接进入第 14 步触发构建，构建大概率会因为 layer
# 文件缺失而失败，且报错和这里完全对不上，排查成本更高。这里选择直接把
# 原始响应暴露出来，方便照着 upload 里的 code/message 去查后端，而不是
# 吞掉继续跑。
if "present" not in upload:
    raise RuntimeError(f"failed to check build context upload cache: {upload}")
if not upload["present"]:
    httpx.put(upload["url"], content=build_context)
 
# 14. 触发真正构建
api.post(
    f"/v2/templates/{new_template_id}/builds/{build_id}",
    json={
        "fromImage": "registry.example.com/base-images/python:3.11",
        "steps": [{"type": "RUN", "args": ["pip install numpy pandas"]}],
    },
)
 
# 15. 轮询构建状态，直到 ready（building/waiting/ready/error 四种取值）
while True:
    status = api.get(f"/templates/{new_template_id}/builds/{build_id}/status").json()
    if status["status"] == "ready":
        break
    if status["status"] == "error":
        raise RuntimeError("build failed")
    time.sleep(3)
print("build ready")
 
# 16. build 详情（legacy，与 status 分开：一次性返回完整日志，不用于轮询）
build_detail = api.get(f"/templates/{new_template_id}/builds/{build_id}").json()
 
# 17. 模板详情（含构建历史）
detail = api.get(f"/templates/{new_template_id}").json()
print("builds:", len(detail.get("builds", [])))
 
# 18. 用新模板创建沙箱，验证构建产物可用
new_sandbox = Sandbox.create(template=new_template_id)
print("created:", new_sandbox.sandbox_id)
new_sandbox.kill()
 
# 19. 删除模板（清理；若有其它模板的 fromTemplate 还指向它会 409，需先处理下游模板）
api.delete(f"/templates/{new_template_id}")