API de Sandbox
La API de Sandbox proporciona a tu código o agente de IA una máquina Linux aislada en la nube cuando la necesitas. Crea un sandbox, ejecuta comandos de shell, lee y escribe archivos, y luego detenlo o elimínalo, todo mediante REST con la misma x-api-key y el mismo saldo de créditos que usas para generar imágenes, videos y audio.
No es lo mismo que las claves de Sandbox (prueba). Las claves de API creadas con
is_test: truese llaman «claves de sandbox» y devuelven resultados simulados para los endpoints de generación (consulta la Referencia de la API). La API de Sandbox que se describe aquí crea máquinas reales en la nube. Una clave de prueba puede llamar a los endpoints de la API de Sandbox, pero devuelve un resultado simulado y no crea nada.
Tamaños y precios
Indica profile al crear un sandbox. Se cobra por segundo mientras el sandbox está en ejecución, con cargo a tus créditos.
| Perfil | Recursos | Precio |
|---|---|---|
small | 2 vCPU, 4 GB de RAM | $0.036 / hora |
default | 4 vCPU, 8 GB de RAM | $0.072 / hora |
large | 8 vCPU, 16 GB de RAM | $0.144 / hora |
- La tarifa por hora queda fijada al crear el sandbox.
- Los sandboxes detenidos son gratis. Los archivos se conservan mientras están detenidos.
- Necesitas un saldo de al menos $1 para crear o reanudar un sandbox.
Inicio rápido
export MUAPI_KEY="your-api-key"
# 1. Crear un 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. Ejecutar 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. Escribir y leer un archivo
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. Detenerlo (se pausa la facturación)
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
| Método | Ruta | Descripción |
|---|---|---|
POST | /api/v1/sandboxes | Crear un sandbox. Cuerpo: {"profile": "small" | "default" | "large"} |
GET | /api/v1/sandboxes | Listar tus sandboxes |
GET | /api/v1/sandboxes/{id} | Obtener un sandbox |
POST | /api/v1/sandboxes/{id}/commands | Ejecutar un comando de shell |
GET | /api/v1/sandboxes/{id}/commands/{process_id} | Consultar el estado y la salida de un comando en segundo plano |
PUT | /api/v1/sandboxes/{id}/files | Escribir un archivo |
GET | /api/v1/sandboxes/{id}/files?path= | Leer un archivo |
POST | /api/v1/sandboxes/{id}/stop | Detener (se pausa la facturación) |
POST | /api/v1/sandboxes/{id}/resume | Reanudar un sandbox detenido |
DELETE | /api/v1/sandboxes/{id} | Eliminar un sandbox y sus archivos |
Ejecutar un comando
POST /api/v1/sandboxes/{id}/commands
| Campo | Tipo | Valor predeterminado | Notas |
|---|---|---|---|
command | string | obligatorio | Comando de shell, de hasta 20,000 caracteres |
timeout_seconds | integer | 30 | De 1 a 600 |
detached | boolean | false | Ejecutar en segundo plano; consultar el estado con el process_id devuelto |
cwd | string | . | Directorio de trabajo. Ya debe existir (por ejemplo, primero ejecuta mkdir -p /home/user/workspace) |
Para tareas largas, establece detached: true y luego consulta GET /api/v1/sandboxes/{id}/commands/{process_id}.
Archivos
PUT /files recibe {"path": "...", "content": "..."} con contenido de texto sin formato (de hasta 2,000,000 caracteres). GET /files?path=... devuelve {"path": "...", "content": "..."}.
Ciclo de vida y facturación
- Un sandbox nuevo pasa a estar
runningen un par de segundos y ya incluye Python 3. - La detención no es instantánea. La facturación se detiene en el momento en que lo solicitas, pero reanudarlo inmediatamente puede devolver un conflicto durante unos segundos. La llamada para detenerlo espera a que el sandbox termine de archivarse antes de responder, así que es seguro detenerlo y luego reanudarlo.
- Los archivos persisten al detener y reanudar el sandbox.
- Un sandbox se detiene automáticamente cuando tu saldo no alcanza para cubrir el uso o después de 15 minutos sin actividad.
- Un sandbox detenido se elimina después de 14 días. Descarga lo que necesites antes de que eso ocurra.
- Cada cuenta puede tener hasta 3 sandboxes a la vez.
- Los comandos y el acceso a archivos se ejecutan como un usuario normal dentro de una máquina aislada. Tú eres responsable de lo que ejecutes en ella.
Playground y endpoints de estilo tarea
Todas las operaciones también están disponibles en Playground y como endpoints de estilo tarea, POST /api/v1/sandbox-<operation>, donde <operation> puede ser create, get, run-command, command-status, write-file, read-file, stop, resume o delete. Reciben los mismos campos que las rutas REST, además de sandbox_id cuando corresponda, y devuelven un request_id que puedes consultar en GET /api/v1/predictions/{request_id}/result, como con cualquier otro modelo de Muapi. El cómputo se factura únicamente por el tiempo de ejecución; estas solicitudes no tienen costo.
Errores
Los errores usan {"error": {"code": "...", "message": "..."}}.
| Estado | Código | Significado |
|---|---|---|
| 400 | INVALID_PROFILE | profile desconocido |
| 402 | INSUFFICIENT_CREDITS | Saldo inferior al mínimo de $1 para crear o reanudar |
| 422 | INVALID_INPUT | Falta un campo o su valor está fuera de rango (endpoints de estilo tarea) |
| 502 | SANDBOX_UPSTREAM_ERROR | Error temporal del backend; vuelve a intentarlo |
Casos de uso
- Agentes de programación: clona un repositorio, instala paquetes, ejecuta pruebas y corrige errores en una máquina real.
- Ejecución de código: ejecuta código generado o no confiable fuera de tu propia infraestructura.
- Flujos de trabajo de medios: ejecuta ffmpeg o scripts personalizados con resultados de los modelos de imagen, video y audio de Muapi.
- Aplicaciones de código abierto alojadas: ejecuta aplicaciones en la nube con la propia clave de Muapi del usuario.
Consulta la página principal de la API de Sandbox para ver un resumen.