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

PerfilRecursosPrecio
small2 vCPU, 4 GB de RAM$0.036 / hora
default4 vCPU, 8 GB de RAM$0.072 / hora
large8 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étodoRutaDescripción
POST/api/v1/sandboxesCrear un sandbox. Cuerpo: {"profile": "small" | "default" | "large"}
GET/api/v1/sandboxesListar tus sandboxes
GET/api/v1/sandboxes/{id}Obtener un sandbox
POST/api/v1/sandboxes/{id}/commandsEjecutar 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}/filesEscribir un archivo
GET/api/v1/sandboxes/{id}/files?path=Leer un archivo
POST/api/v1/sandboxes/{id}/stopDetener (se pausa la facturación)
POST/api/v1/sandboxes/{id}/resumeReanudar un sandbox detenido
DELETE/api/v1/sandboxes/{id}Eliminar un sandbox y sus archivos

Ejecutar un comando

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

CampoTipoValor predeterminadoNotas
commandstringobligatorioComando de shell, de hasta 20,000 caracteres
timeout_secondsinteger30De 1 a 600
detachedbooleanfalseEjecutar en segundo plano; consultar el estado con el process_id devuelto
cwdstring.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 running en 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": "..."}}.

EstadoCódigoSignificado
400INVALID_PROFILEprofile desconocido
402INSUFFICIENT_CREDITSSaldo inferior al mínimo de $1 para crear o reanudar
422INVALID_INPUTFalta un campo o su valor está fuera de rango (endpoints de estilo tarea)
502SANDBOX_UPSTREAM_ERRORError 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.