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: true sono 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.

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

MetodoPercorsoDescrizione
POST/api/v1/sandboxesCrea una sandbox. Corpo: {"profile": "small" | "default" | "large"}
GET/api/v1/sandboxesElenca le tue sandbox
GET/api/v1/sandboxes/{id}Recupera una sandbox
POST/api/v1/sandboxes/{id}/commandsEsegue un comando shell
GET/api/v1/sandboxes/{id}/commands/{process_id}Stato e output di un comando in background
PUT/api/v1/sandboxes/{id}/filesScrive un file
GET/api/v1/sandboxes/{id}/files?path=Legge un file
POST/api/v1/sandboxes/{id}/stopArresta la sandbox (la fatturazione si interrompe)
POST/api/v1/sandboxes/{id}/resumeRiavvia una sandbox arrestata
DELETE/api/v1/sandboxes/{id}Elimina una sandbox e i suoi file

Eseguire un comando

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

CampoTipoPredefinitoNote
commandstringobbligatorioComando shell, fino a 20.000 caratteri
timeout_secondsinteger30Da 1 a 600
detachedbooleanfalseEsegue in background; controlla lo stato con il process_id restituito
cwdstring.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 è running entro 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": "..."}}.

StatoCodiceSignificato
400INVALID_PROFILEprofile sconosciuto
402INSUFFICIENT_CREDITSSaldo inferiore al minimo di $1 per creare o riavviare la sandbox
422INVALID_INPUTUn campo è mancante o fuori intervallo (endpoint in stile task)
502SANDBOX_UPSTREAM_ERRORErrore 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.