API Sandbox
La Sandbox API fornisce al tuo codice o agente IA una macchina Linux cloud isolata su richiesta. Crea una sandbox, esegui comandi shell, leggi e scrivi file, poi arrestala o eliminala: tutto tramite REST con la stessa x-api-key e lo stesso saldo di crediti che usi per generare immagini, video e audio.
Non è la stessa cosa delle chiavi Sandbox (test). Le chiavi API create con
is_test: truesono chiamate “chiavi sandbox” e restituiscono risultati simulati per gli endpoint di generazione (vedi Riferimento API). La Sandbox API descritta qui crea vere macchine cloud. Una chiave di test può chiamare gli endpoint della Sandbox API, ma restituisce un risultato simulato e non crea nulla.
Dimensioni e prezzi
Specifica profile quando crei una sandbox. L’addebito avviene al secondo mentre la sandbox è in esecuzione e viene scalato dai tuoi crediti.
| Profilo | Risorse | Prezzo |
|---|---|---|
small | 2 vCPU, 4 GB RAM | $0.036 / ora |
default | 4 vCPU, 8 GB RAM | $0.072 / ora |
large | 8 vCPU, 16 GB RAM | $0.144 / ora |
- La tariffa oraria viene fissata quando la sandbox viene creata.
- Le sandbox arrestate sono gratuite. I file vengono conservati mentre la sandbox è arrestata.
- Per creare o riavviare una sandbox, serve un saldo di almeno $1.
Avvio rapido
export MUAPI_KEY="your-api-key"
# 1. Crea una sandbox
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. Esegui un comando
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. Scrivi e leggi un file
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. Arrestala (la fatturazione si interrompe)
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)
Endpoint
| Metodo | Percorso | Descrizione |
|---|---|---|
POST | /api/v1/sandboxes | Crea una sandbox. Corpo: {"profile": "small" | "default" | "large"} |
GET | /api/v1/sandboxes | Elenca le tue sandbox |
GET | /api/v1/sandboxes/{id} | Recupera una sandbox |
POST | /api/v1/sandboxes/{id}/commands | Esegue un comando shell |
GET | /api/v1/sandboxes/{id}/commands/{process_id} | Stato e output di un comando in background |
PUT | /api/v1/sandboxes/{id}/files | Scrive un file |
GET | /api/v1/sandboxes/{id}/files?path= | Legge un file |
POST | /api/v1/sandboxes/{id}/stop | Arresta la sandbox (la fatturazione si interrompe) |
POST | /api/v1/sandboxes/{id}/resume | Riavvia una sandbox arrestata |
DELETE | /api/v1/sandboxes/{id} | Elimina una sandbox e i suoi file |
Eseguire un comando
POST /api/v1/sandboxes/{id}/commands
| Campo | Tipo | Predefinito | Note |
|---|---|---|---|
command | string | obbligatorio | Comando shell, fino a 20.000 caratteri |
timeout_seconds | integer | 30 | Da 1 a 600 |
detached | boolean | false | Esegue in background; controlla lo stato con il process_id restituito |
cwd | string | . | Directory di lavoro. Deve esistere già (ad esempio, esegui prima mkdir -p /home/user/workspace) |
Per le operazioni lunghe, imposta detached: true, poi controlla lo stato con GET /api/v1/sandboxes/{id}/commands/{process_id}.
File
PUT /files accetta {"path": "...", "content": "..."} con contenuto in testo semplice (fino a 2.000.000 di caratteri). GET /files?path=... restituisce {"path": "...", "content": "..."}.
Ciclo di vita e fatturazione
- Una nuova sandbox è
runningentro pochi secondi e include Python 3 preinstallato. - L’arresto non è istantaneo. La fatturazione si interrompe quando invii la richiesta, ma se la riavvii subito potresti ricevere un conflitto per alcuni secondi. La chiamata di arresto attende che la sandbox abbia terminato l’archiviazione prima di restituire una risposta, quindi puoi arrestarla e poi riavviarla in sicurezza.
- I file persistono quando arresti e riavvii la sandbox.
- Una sandbox viene arrestata automaticamente quando il saldo non è sufficiente a coprire l’utilizzo o dopo 15 minuti di inattività.
- Una sandbox arrestata viene eliminata dopo 14 giorni. Scarica prima tutto ciò che ti serve.
- Ogni account può avere fino a 3 sandbox contemporaneamente.
- I comandi e l’accesso ai file avvengono come utente normale all’interno di una macchina isolata. Sei responsabile di ciò che esegui al suo interno.
Playground ed endpoint in stile task
Ogni operazione è disponibile anche nel Playground e tramite un endpoint in stile task, POST /api/v1/sandbox-<operation>, dove <operation> può essere create, get, run-command, command-status, write-file, read-file, stop, resume, delete. Questi endpoint accettano gli stessi campi delle route REST, più sandbox_id quando pertinente, e restituiscono un request_id da leggere con GET /api/v1/predictions/{request_id}/result, come per qualsiasi altro modello Muapi. Il calcolo viene fatturato solo in base al tempo di esecuzione; queste richieste non hanno costi.
Errori
Gli errori usano {"error": {"code": "...", "message": "..."}}.
| Stato | Codice | Significato |
|---|---|---|
| 400 | INVALID_PROFILE | profile sconosciuto |
| 402 | INSUFFICIENT_CREDITS | Saldo inferiore al minimo di $1 per creare o riavviare la sandbox |
| 422 | INVALID_INPUT | Un campo è mancante o fuori intervallo (endpoint in stile task) |
| 502 | SANDBOX_UPSTREAM_ERROR | Errore temporaneo del backend, riprova |
Casi d’uso
- Agenti di programmazione: clonare un repository, installare pacchetti, eseguire test e correggere gli errori su una macchina reale.
- Esecuzione del codice: eseguire codice generato o non attendibile lontano dalla propria infrastruttura.
- Pipeline multimediali: eseguire ffmpeg o script personalizzati sui risultati dei modelli Muapi per immagini, video e audio.
- App open source ospitate: eseguire app nel cloud con la chiave Muapi dell’utente.
Consulta la pagina introduttiva della Sandbox API per una panoramica.