Sandbox-API
De Sandbox-API geeft je code of AI-agent op verzoek een geïsoleerde Linux-machine in de cloud. Maak een sandbox, voer shellopdrachten uit, lees en schrijf bestanden en stop of verwijder de sandbox. Dit kan allemaal via REST met dezelfde x-api-key en hetzelfde creditsaldo dat je gebruikt voor het genereren van afbeeldingen, video’s en audio.
Niet hetzelfde als Sandbox-testkeys. API-sleutels die zijn aangemaakt met
is_test: trueheten ‘sandboxkeys’ en geven mockresultaten voor generatie-endpoints (zie API-referentie). De Sandbox-API die hier wordt beschreven, maakt echte cloudmachines aan. Een testsleutel kan de endpoints van de Sandbox-API aanroepen, maar geeft een mockresultaat en maakt niets aan.
Grootte en prijzen
Geef profile mee wanneer je een sandbox aanmaakt. Zolang de sandbox actief is, wordt er per seconde afgerekend via je credits.
| Profiel | Bronnen | Prijs |
|---|---|---|
small | 2 vCPU, 4 GB RAM | $0.036 / uur |
default | 4 vCPU, 8 GB RAM | $0.072 / uur |
large | 8 vCPU, 16 GB RAM | $0.144 / uur |
- Het uurtarief wordt vastgelegd wanneer de sandbox wordt aangemaakt.
- Gestopte sandboxes zijn gratis. Bestanden blijven bewaard zolang de sandbox gestopt is.
- Je hebt minstens $1 saldo nodig om een sandbox aan te maken of te hervatten.
Snel aan de slag
export MUAPI_KEY="your-api-key"
# 1. Maak een sandbox aan
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. Voer een opdracht uit
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. Schrijf en lees een bestand
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. Stop de sandbox (de kosten lopen niet verder op)
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)
Endpoints
| Methode | Pad | Beschrijving |
|---|---|---|
POST | /api/v1/sandboxes | Maak een sandbox aan. Body: {"profile": "small" | "default" | "large"} |
GET | /api/v1/sandboxes | Geef een lijst van je sandboxes weer |
GET | /api/v1/sandboxes/{id} | Haal één sandbox op |
POST | /api/v1/sandboxes/{id}/commands | Voer een shellopdracht uit |
GET | /api/v1/sandboxes/{id}/commands/{process_id} | Status en uitvoer van een losgekoppelde opdracht |
PUT | /api/v1/sandboxes/{id}/files | Schrijf een bestand |
GET | /api/v1/sandboxes/{id}/files?path= | Lees een bestand |
POST | /api/v1/sandboxes/{id}/stop | Stop de sandbox (de kosten lopen niet verder op) |
POST | /api/v1/sandboxes/{id}/resume | Hervat een gestopte sandbox |
DELETE | /api/v1/sandboxes/{id} | Verwijder een sandbox en de bestanden ervan |
Een opdracht uitvoeren
POST /api/v1/sandboxes/{id}/commands
| Veld | Type | Standaardwaarde | Opmerkingen |
|---|---|---|---|
command | string | vereist | Shellopdracht, maximaal 20.000 tekens |
timeout_seconds | integer | 30 | 1 tot 600 |
detached | boolean | false | Voer op de achtergrond uit; controleer de status met de teruggegeven process_id |
cwd | string | . | Werkmap. Deze moet al bestaan (voer bijvoorbeeld eerst mkdir -p /home/user/workspace uit) |
Stel voor lange taken detached: true in en controleer daarna de status via GET /api/v1/sandboxes/{id}/commands/{process_id}.
Bestanden
PUT /files accepteert {"path": "...", "content": "..."} met platte tekst (maximaal 2.000.000 tekens). GET /files?path=... geeft {"path": "...", "content": "..."} terug.
Levenscyclus en kosten
- Een nieuwe sandbox is binnen enkele seconden
runningen heeft Python 3 vooraf geïnstalleerd. - Stoppen gebeurt niet direct. De kosten stoppen op het moment dat je het verzoek indient, maar als je de sandbox meteen hervat, kan dit enkele seconden lang een conflict opleveren. De stopaanroep wacht totdat de sandbox klaar is met archiveren. Daardoor kun je de sandbox veilig stoppen en daarna hervatten.
- Bestanden blijven bewaard wanneer je de sandbox stopt en hervat.
- Een sandbox wordt automatisch gestopt wanneer je saldo de kosten niet meer dekt, of na 15 minuten zonder activiteit.
- Een gestopte sandbox wordt na 14 dagen verwijderd. Download vooraf alles wat je nodig hebt.
- Elk account kan maximaal 3 sandboxes tegelijk hebben.
- Opdrachten en bestandstoegang worden uitgevoerd als een gewone gebruiker in een geïsoleerde machine. Je bent zelf verantwoordelijk voor wat je daarin uitvoert.
Playground en endpoints in taakstijl
Elke bewerking is ook beschikbaar in de Playground en als endpoint in taakstijl: POST /api/v1/sandbox-<operation>, waarbij <operation> een van de volgende waarden is: create, get, run-command, command-status, write-file, read-file, stop, resume, delete. Deze endpoints accepteren dezelfde velden als de REST-routes, plus waar relevant sandbox_id, en geven een request_id terug. Gebruik die voor GET /api/v1/predictions/{request_id}/result, net als bij elk ander Muapi-model. Alleen de rekentijd tijdens het uitvoeren wordt in rekening gebracht; deze verzoeken zelf kosten $0.
Fouten
Fouten gebruiken {"error": {"code": "...", "message": "..."}}.
| Status | Code | Betekenis |
|---|---|---|
| 400 | INVALID_PROFILE | Onbekende profile |
| 402 | INSUFFICIENT_CREDITS | Saldo lager dan het minimum van $1 om een sandbox aan te maken of te hervatten |
| 422 | INVALID_INPUT | Een veld ontbreekt of valt buiten het toegestane bereik (endpoints in taakstijl) |
| 502 | SANDBOX_UPSTREAM_ERROR | Tijdelijke backendfout; probeer het opnieuw |
Toepassingen
- Codeeragents: kloon een repo, installeer pakketten, voer tests uit en los fouten op een echte machine op.
- Code uitvoeren: voer gegenereerde of niet-vertrouwde code uit, buiten je eigen infrastructuur.
- Mediapijplijnen: voer ffmpeg of aangepaste scripts uit op uitvoer van Muapi-modellen voor afbeeldingen, video en audio.
- Open-source-apps hosten: voer apps in de cloud uit met de eigen Muapi-sleutel van de gebruiker.
Bekijk de overzichtspagina van de Sandbox-API voor een overzicht.