沙箱 API
沙箱 API 可按需为你的代码或 AI 代理提供一台隔离的云端 Linux 机器。你可以通过 REST 创建沙箱、运行 Shell 命令、读写文件,然后停止或删除沙箱。整个过程使用与图像、视频和音频生成相同的 x-api-key 和积分余额。
这与 Sandbox(测试)密钥不同。 使用
is_test: true创建的 API 密钥称为“沙箱密钥”,调用生成端点时会返回模拟结果(参见API 参考)。此处介绍的沙箱 API 用于创建真实的云端机器。测试密钥可以调用沙箱 API 端点,但只会返回模拟结果,不会创建任何机器。
规格与价格
创建沙箱时传入 profile。沙箱运行期间按秒计费,从你的积分余额中扣除。
| 规格 | 资源 | 价格 |
|---|---|---|
small | 2 vCPU,4 GB RAM | $0.036 / 小时 |
default | 4 vCPU,8 GB RAM | $0.072 / 小时 |
large | 8 vCPU,16 GB RAM | $0.144 / 小时 |
- 沙箱创建时的每小时费率会锁定。
- 已停止的沙箱免费。 停止期间会保留文件。
- 创建或恢复沙箱时,余额至少需要 $1。
快速开始
export MUAPI_KEY="your-api-key"
# 1. 创建沙箱
curl -X POST https://api.muapi.ai/api/v1/sandboxes \
-H "x-api-key: $MUAPI_KEY" -H "Content-Type: application/json" \
-d '{"profile": "default"}'
# -> {"id": "…", "state": "running", "profile": "default", "vcpu": 4, "memory_gb": 8, "price_per_hour": 0.072, …}
export ID="<id from the response>"
# 2. 运行命令
curl -X POST https://api.muapi.ai/api/v1/sandboxes/$ID/commands \
-H "x-api-key: $MUAPI_KEY" -H "Content-Type: application/json" \
-d '{"command": "python3 --version", "timeout_seconds": 30}'
# 3. 写入并读取文件
curl -X PUT https://api.muapi.ai/api/v1/sandboxes/$ID/files \
-H "x-api-key: $MUAPI_KEY" -H "Content-Type: application/json" \
-d '{"path": "/home/user/hello.py", "content": "print(\"hi\")"}'
curl "https://api.muapi.ai/api/v1/sandboxes/$ID/files?path=/home/user/hello.py" \
-H "x-api-key: $MUAPI_KEY"
# 4. 停止沙箱(暂停计费)
curl -X POST https://api.muapi.ai/api/v1/sandboxes/$ID/stop \
-H "x-api-key: $MUAPI_KEY"
Python
import os, requests
BASE = "https://api.muapi.ai/api/v1/sandboxes"
H = {"x-api-key": os.environ["MUAPI_KEY"]}
sb = requests.post(BASE, headers=H, json={"profile": "small"}).json()
sid = sb["id"]
out = requests.post(f"{BASE}/{sid}/commands", headers=H,
json={"command": "echo hello && uname -a"}).json()
print(out)
requests.post(f"{BASE}/{sid}/stop", headers=H)
端点
| 方法 | 路径 | 说明 |
|---|---|---|
POST | /api/v1/sandboxes | 创建沙箱。请求体:{"profile": "small" | "default" | "large"} |
GET | /api/v1/sandboxes | 列出你的沙箱 |
GET | /api/v1/sandboxes/{id} | 获取单个沙箱 |
POST | /api/v1/sandboxes/{id}/commands | 运行 Shell 命令 |
GET | /api/v1/sandboxes/{id}/commands/{process_id} | 查看已分离命令的状态和输出 |
PUT | /api/v1/sandboxes/{id}/files | 写入文件 |
GET | /api/v1/sandboxes/{id}/files?path= | 读取文件 |
POST | /api/v1/sandboxes/{id}/stop | 停止沙箱(暂停计费) |
POST | /api/v1/sandboxes/{id}/resume | 恢复已停止的沙箱 |
DELETE | /api/v1/sandboxes/{id} | 删除沙箱及其文件 |
运行命令
POST /api/v1/sandboxes/{id}/commands
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
command | string | 必填 | Shell 命令,最多 20,000 个字符 |
timeout_seconds | integer | 30 | 1 到 600 |
detached | boolean | false | 在后台运行;使用返回的 process_id 轮询状态 |
cwd | string | . | 工作目录。该目录必须已存在(例如先运行 mkdir -p /home/user/workspace) |
对于耗时较长的任务,设置 detached: true,然后轮询 GET /api/v1/sandboxes/{id}/commands/{process_id}。
文件
PUT /files 接收 {"path": "...", "content": "..."},其中 content 为纯文本,最多 2,000,000 个字符。GET /files?path=... 返回 {"path": "...", "content": "..."}。
生命周期与计费
- 新沙箱会在几秒内进入
running状态,并预装 Python 3。 - 停止操作并非即时完成。 你发出停止请求时即停止计费,但如果立即恢复,几秒内可能会收到冲突错误。停止请求会等待沙箱完成归档后再返回,因此停止后再恢复是安全的。
- 文件会在停止和恢复期间保留。
- 余额不足以支付使用费用时,或 15 分钟没有活动后,沙箱会自动停止。
- 已停止的沙箱会在 14 天后删除。请在此之前下载所需内容。
- 每个账户最多可同时拥有 3 个沙箱。
- 命令和文件访问以普通用户身份在隔离机器中运行。你需要自行负责在其中运行的内容。
Playground 和任务式端点
每项操作也可在 Playground 中使用,并提供任务式端点 POST /api/v1/sandbox-<operation>,其中 <operation> 可以是 create、get、run-command、command-status、write-file、read-file、stop、resume、delete。这些端点接收与 REST 路由相同的字段,并在适用时接收 sandbox_id;它们会返回一个 request_id,你可以像使用其他 Muapi 模型一样,通过 GET /api/v1/predictions/{request_id}/result 获取结果。计算费用仅按运行时间计收;这些请求本身费用为 $0。
错误
错误格式为 {"error": {"code": "...", "message": "..."}}。
| 状态码 | 代码 | 含义 |
|---|---|---|
| 400 | INVALID_PROFILE | 未知的 profile |
| 402 | INSUFFICIENT_CREDITS | 余额低于创建或恢复沙箱所需的 $1 最低金额 |
| 422 | INVALID_INPUT | 字段缺失或超出范围(任务式端点) |
| 502 | SANDBOX_UPSTREAM_ERROR | 后端临时错误,请重试 |
使用场景
- 编码代理: 克隆代码库、安装软件包、在真实机器上运行测试并修复失败。
- 代码执行: 在自己的基础设施之外运行生成的代码或不受信任的代码。
- 媒体处理流程: 使用 ffmpeg 或自定义脚本处理 Muapi 图像、视频和音频模型的输出。
- 托管开源应用: 使用用户自己的 Muapi 密钥在云端运行应用。
查看 沙箱 API 介绍页了解概览。