サンドボックス API
Sandbox API を使うと、コードや AI エージェント向けに、分離されたクラウド Linux マシンを必要なときに利用できます。サンドボックスを作成し、シェルコマンドを実行し、ファイルを読み書きしたあと、停止または削除できます。画像、動画、音声の生成に使うものと同じ x-api-key とクレジット残高を使い、すべて REST 経由で操作できます。
Sandbox(テスト)キーとは異なります。
is_test: trueで作成された API キーは「サンドボックスキー」と呼ばれ、生成エンドポイントに対してモック結果を返します(API リファレンスを参照)。ここで説明する Sandbox API は、実際のクラウドマシンを作成します。テストキーでも Sandbox 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} | サンドボックスを1つ取得 |
POST | /api/v1/sandboxes/{id}/commands | シェルコマンドを実行 |
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 | 必須 | シェルコマンド。最大 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": "..."} を渡します(最大 2,000,000 文字)。GET /files?path=... は {"path": "...", "content": "..."} を返します。
ライフサイクルと課金
- 新しいサンドボックスは数秒以内に
running状態になり、Python 3 がプリインストールされています。 - 停止は即時ではありません。停止をリクエストした時点で課金は停止しますが、すぐに再開すると数秒間は競合エラーが返る場合があります。停止リクエストは、サンドボックスのアーカイブが完了してから返されるため、停止してから再開しても安全です。
- ファイルは停止後も再開後も保持されます。
- 残高で利用料金をまかなえなくなった場合、または 15 分間操作がない場合、サンドボックスは自動的に停止します。
- 停止中のサンドボックスは 14 日後に削除されます。必要なものはそれまでにダウンロードしてください。
- 1 アカウントにつき、同時に最大 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 を指定します。他の Muapi モデルと同様に、GET /api/v1/predictions/{request_id}/result で取得する request_id が返されます。コンピューティング料金は実行時間に応じて課金され、リクエスト自体は無料です。
エラー
エラーは {"error": {"code": "...", "message": "..."}} の形式です。
| ステータス | コード | 意味 |
|---|---|---|
| 400 | INVALID_PROFILE | 不明な profile |
| 402 | INSUFFICIENT_CREDITS | 作成または再開に必要な最低残高 $1 を下回っています |
| 422 | INVALID_INPUT | フィールドが不足しているか、許容範囲外です(タスク形式のエンドポイント) |
| 502 | SANDBOX_UPSTREAM_ERROR | 一時的なバックエンドエラーです。再試行してください |
使用例
- コーディングエージェント: リポジトリをクローンし、パッケージをインストールして、実際のマシンでテストを実行し、失敗を修正する。
- コード実行: 生成されたコードや信頼できないコードを、自分のインフラストラクチャから離れた場所で実行する。
- メディア処理パイプライン: Muapi の画像、動画、音声モデルの出力に対して、ffmpeg やカスタムスクリプトを実行する。
- ホスト型オープンソースアプリ: ユーザー自身の Muapi キーを使って、クラウド上でアプリを実行する。
概要はSandbox API のランディングページを参照してください。