沙箱 API

沙箱 API 可按需为你的代码或 AI 代理提供一台隔离的云端 Linux 机器。你可以通过 REST 创建沙箱、运行 Shell 命令、读写文件,然后停止或删除沙箱。整个过程使用与图像、视频和音频生成相同的 x-api-key 和积分余额。

这与 Sandbox(测试)密钥不同。 使用 is_test: true 创建的 API 密钥称为“沙箱密钥”,调用生成端点时会返回模拟结果(参见API 参考)。此处介绍的沙箱 API 用于创建真实的云端机器。测试密钥可以调用沙箱 API 端点,但只会返回模拟结果,不会创建任何机器。

规格与价格

创建沙箱时传入 profile。沙箱运行期间按秒计费,从你的积分余额中扣除。

规格资源价格
small2 vCPU,4 GB RAM$0.036 / 小时
default4 vCPU,8 GB RAM$0.072 / 小时
large8 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

字段类型默认值说明
commandstring必填Shell 命令,最多 20,000 个字符
timeout_secondsinteger301 到 600
detachedbooleanfalse在后台运行;使用返回的 process_id 轮询状态
cwdstring.工作目录。该目录必须已存在(例如先运行 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": "..."}}。

状态码代码含义
400INVALID_PROFILE未知的 profile
402INSUFFICIENT_CREDITS余额低于创建或恢复沙箱所需的 $1 最低金额
422INVALID_INPUT字段缺失或超出范围(任务式端点)
502SANDBOX_UPSTREAM_ERROR后端临时错误,请重试

使用场景

  • 编码代理: 克隆代码库、安装软件包、在真实机器上运行测试并修复失败。
  • 代码执行: 在自己的基础设施之外运行生成的代码或不受信任的代码。
  • 媒体处理流程: 使用 ffmpeg 或自定义脚本处理 Muapi 图像、视频和音频模型的输出。
  • 托管开源应用: 使用用户自己的 Muapi 密钥在云端运行应用。

查看 沙箱 API 介绍页了解概览。