サンドボックス API

Sandbox API を使うと、コードや AI エージェント向けに、分離されたクラウド Linux マシンを必要なときに利用できます。サンドボックスを作成し、シェルコマンドを実行し、ファイルを読み書きしたあと、停止または削除できます。画像、動画、音声の生成に使うものと同じ x-api-key とクレジット残高を使い、すべて REST 経由で操作できます。

Sandbox(テスト)キーとは異なります。 is_test: true で作成された API キーは「サンドボックスキー」と呼ばれ、生成エンドポイントに対してモック結果を返します(API リファレンスを参照)。ここで説明する Sandbox API は、実際のクラウドマシンを作成します。テストキーでも Sandbox 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}サンドボックスを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

フィールド型デフォルト備考
commandstring必須シェルコマンド。最大 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": "..."} を渡します(最大 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": "..."}} の形式です。

ステータスコード意味
400INVALID_PROFILE不明な profile
402INSUFFICIENT_CREDITS作成または再開に必要な最低残高 $1 を下回っています
422INVALID_INPUTフィールドが不足しているか、許容範囲外です(タスク形式のエンドポイント)
502SANDBOX_UPSTREAM_ERROR一時的なバックエンドエラーです。再試行してください

使用例

  • コーディングエージェント: リポジトリをクローンし、パッケージをインストールして、実際のマシンでテストを実行し、失敗を修正する。
  • コード実行: 生成されたコードや信頼できないコードを、自分のインフラストラクチャから離れた場所で実行する。
  • メディア処理パイプライン: Muapi の画像、動画、音声モデルの出力に対して、ffmpeg やカスタムスクリプトを実行する。
  • ホスト型オープンソースアプリ: ユーザー自身の Muapi キーを使って、クラウド上でアプリを実行する。

概要はSandbox API のランディングページを参照してください。