Sandbox-API
Die Sandbox-API stellt Ihrem Code oder KI-Agenten bei Bedarf eine isolierte Linux-Maschine in der Cloud bereit. Erstellen Sie eine Sandbox, führen Sie Shell-Befehle aus, lesen und schreiben Sie Dateien und halten Sie die Sandbox anschließend an oder löschen Sie sie. Alles läuft über REST mit demselben x-api-key und Guthaben, das Sie für die Generierung von Bildern, Videos und Audio verwenden.
Nicht dasselbe wie Sandbox-(Test-)Schlüssel. API-Schlüssel, die mit
is_test: trueerstellt wurden, heißen „Sandbox-Schlüssel“ und liefern bei Generierungsendpunkten Mock-Ergebnisse (siehe API-Referenz). Die hier beschriebene Sandbox-API erstellt echte Cloud-Maschinen. Ein Testschlüssel kann die Endpunkte der Sandbox-API aufrufen, liefert aber ein Mock-Ergebnis und erstellt keine Maschine.
Größen und Preise
Übergeben Sie beim Erstellen einer Sandbox profile. Solange die Sandbox läuft, wird sekundengenau abgerechnet. Die Kosten werden von Ihrem Guthaben abgezogen.
| Profil | Ressourcen | Preis |
|---|---|---|
small | 2 vCPU, 4 GB RAM | $0.036 / Stunde |
default | 4 vCPU, 8 GB RAM | $0.072 / Stunde |
large | 8 vCPU, 16 GB RAM | $0.144 / Stunde |
- Der Stundensatz wird beim Erstellen der Sandbox festgelegt.
- Angehaltene Sandboxes sind kostenlos. Dateien bleiben während des Anhaltens erhalten.
- Zum Erstellen oder Fortsetzen einer Sandbox benötigen Sie ein Guthaben von mindestens $1.
Schnellstart
export MUAPI_KEY="your-api-key"
# 1. Eine Sandbox erstellen
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. Einen Befehl ausführen
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. Eine Datei schreiben und lesen
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. Die Sandbox anhalten (Abrechnung pausiert)
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)
Endpunkte
| Methode | Pfad | Beschreibung |
|---|---|---|
POST | /api/v1/sandboxes | Eine Sandbox erstellen. Body: {"profile": "small" | "default" | "large"} |
GET | /api/v1/sandboxes | Ihre Sandboxes auflisten |
GET | /api/v1/sandboxes/{id} | Eine Sandbox abrufen |
POST | /api/v1/sandboxes/{id}/commands | Einen Shell-Befehl ausführen |
GET | /api/v1/sandboxes/{id}/commands/{process_id} | Status und Ausgabe eines abgekoppelten Befehls |
PUT | /api/v1/sandboxes/{id}/files | Eine Datei schreiben |
GET | /api/v1/sandboxes/{id}/files?path= | Eine Datei lesen |
POST | /api/v1/sandboxes/{id}/stop | Anhalten (Abrechnung pausiert) |
POST | /api/v1/sandboxes/{id}/resume | Eine angehaltene Sandbox fortsetzen |
DELETE | /api/v1/sandboxes/{id} | Eine Sandbox und ihre Dateien löschen |
Einen Befehl ausführen
POST /api/v1/sandboxes/{id}/commands
| Feld | Typ | Standard | Hinweise |
|---|---|---|---|
command | string | erforderlich | Shell-Befehl mit bis zu 20.000 Zeichen |
timeout_seconds | integer | 30 | 1 bis 600 |
detached | boolean | false | Im Hintergrund ausführen; mit der zurückgegebenen process_id abfragen |
cwd | string | . | Arbeitsverzeichnis. Es muss bereits vorhanden sein (führen Sie zum Beispiel zuerst mkdir -p /home/user/workspace aus) |
Setzen Sie bei langen Aufträgen detached: true und fragen Sie anschließend GET /api/v1/sandboxes/{id}/commands/{process_id} ab.
Dateien
PUT /files erwartet {"path": "...", "content": "..."} mit reinem Textinhalt (bis zu 2.000.000 Zeichen). GET /files?path=... gibt {"path": "...", "content": "..."} zurück.
Lebenszyklus und Abrechnung
- Eine neue Sandbox ist innerhalb weniger Sekunden im Status
running. Python 3 ist vorinstalliert. - Das Anhalten erfolgt nicht sofort. Die Abrechnung endet, sobald Sie den Vorgang anfordern. Wenn Sie die Sandbox direkt danach fortsetzen, kann es für einige Sekunden zu einem Konflikt kommen. Der Aufruf zum Anhalten wartet, bis die Sandbox vollständig archiviert wurde. Daher können Sie sie sicher anhalten und anschließend fortsetzen.
- Dateien bleiben beim Anhalten und Fortsetzen erhalten.
- Eine Sandbox wird automatisch angehalten, wenn Ihr Guthaben die Nutzungskosten nicht mehr deckt oder wenn 15 Minuten lang keine Aktivität stattgefunden hat.
- Eine angehaltene Sandbox wird nach 14 Tagen gelöscht. Laden Sie benötigte Dateien vorher herunter.
- Jedes Konto kann gleichzeitig bis zu 3 Sandboxes haben.
- Befehle und Dateizugriffe laufen als normaler Benutzer in einer isolierten Maschine. Sie sind dafür verantwortlich, was Sie darin ausführen.
Playground und aufgabenartige Endpunkte
Jeder Vorgang ist auch im Playground und als aufgabenartiger Endpunkt POST /api/v1/sandbox-<operation> verfügbar. <operation> kann create, get, run-command, command-status, write-file, read-file, stop, resume oder delete sein. Diese Endpunkte akzeptieren dieselben Felder wie die REST-Routen sowie, falls relevant, sandbox_id. Sie geben eine request_id zurück, die Sie wie bei jedem anderen Muapi-Modell über GET /api/v1/predictions/{request_id}/result abrufen können. Rechenleistung wird nur nach Laufzeit abgerechnet; diese Anfragen selbst kosten $0.
Fehler
Fehler haben das Format {"error": {"code": "...", "message": "..."}}.
| Status | Code | Bedeutung |
|---|---|---|
| 400 | INVALID_PROFILE | Unbekanntes profile |
| 402 | INSUFFICIENT_CREDITS | Guthaben liegt unter dem Mindestbetrag von $1 zum Erstellen oder Fortsetzen |
| 422 | INVALID_INPUT | Ein Feld fehlt oder liegt außerhalb des zulässigen Bereichs (aufgabenartige Endpunkte) |
| 502 | SANDBOX_UPSTREAM_ERROR | Vorübergehender Backend-Fehler; versuchen Sie es erneut |
Anwendungsfälle
- Coding-Agenten: Ein Repository klonen, Pakete installieren, Tests ausführen und Fehler auf einer echten Maschine beheben.
- Codeausführung: Generierten oder nicht vertrauenswürdigen Code außerhalb Ihrer eigenen Infrastruktur ausführen.
- Medien-Pipelines: ffmpeg oder benutzerdefinierte Skripte mit Ausgaben der Muapi-Modelle für Bilder, Videos und Audio ausführen.
- Gehostete Open-Source-Apps: Apps mit dem eigenen Muapi-Schlüssel des Benutzers in der Cloud ausführen.
Eine Übersicht finden Sie auf der Übersichtsseite zur Sandbox-API.