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: true heten ‘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.

ProfielBronnenPrijs
small2 vCPU, 4 GB RAM$0.036 / uur
default4 vCPU, 8 GB RAM$0.072 / uur
large8 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

MethodePadBeschrijving
POST/api/v1/sandboxesMaak een sandbox aan. Body: {"profile": "small" | "default" | "large"}
GET/api/v1/sandboxesGeef een lijst van je sandboxes weer
GET/api/v1/sandboxes/{id}Haal één sandbox op
POST/api/v1/sandboxes/{id}/commandsVoer een shellopdracht uit
GET/api/v1/sandboxes/{id}/commands/{process_id}Status en uitvoer van een losgekoppelde opdracht
PUT/api/v1/sandboxes/{id}/filesSchrijf een bestand
GET/api/v1/sandboxes/{id}/files?path=Lees een bestand
POST/api/v1/sandboxes/{id}/stopStop de sandbox (de kosten lopen niet verder op)
POST/api/v1/sandboxes/{id}/resumeHervat een gestopte sandbox
DELETE/api/v1/sandboxes/{id}Verwijder een sandbox en de bestanden ervan

Een opdracht uitvoeren

POST /api/v1/sandboxes/{id}/commands

VeldTypeStandaardwaardeOpmerkingen
commandstringvereistShellopdracht, maximaal 20.000 tekens
timeout_secondsinteger301 tot 600
detachedbooleanfalseVoer op de achtergrond uit; controleer de status met de teruggegeven process_id
cwdstring.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 running en 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": "..."}}.

StatusCodeBetekenis
400INVALID_PROFILEOnbekende profile
402INSUFFICIENT_CREDITSSaldo lager dan het minimum van $1 om een sandbox aan te maken of te hervatten
422INVALID_INPUTEen veld ontbreekt of valt buiten het toegestane bereik (endpoints in taakstijl)
502SANDBOX_UPSTREAM_ERRORTijdelijke 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.