API de Sandbox
A API de Sandbox fornece ao seu código ou agente de IA uma máquina Linux isolada na nuvem sob demanda. Crie um sandbox, execute comandos shell, leia e grave arquivos e, depois, pare ou exclua a máquina — tudo via REST, usando a mesma x-api-key e o mesmo saldo de créditos que você usa para gerar imagens, vídeos e áudio.
Não é o mesmo que as chaves Sandbox (de teste). As chaves de API criadas com
is_test: truesão chamadas de “chaves sandbox” e retornam resultados simulados para endpoints de geração (consulte a Referência da API). A API de Sandbox descrita aqui cria máquinas reais na nuvem. Uma chave de teste pode chamar os endpoints da API de Sandbox, mas retorna um resultado simulado e não cria nada.
Tamanhos e preços
Informe profile ao criar um sandbox. A cobrança é feita por segundo enquanto o sandbox estiver em execução e descontada dos seus créditos.
| Perfil | Recursos | Preço |
|---|---|---|
small | 2 vCPU, 4 GB RAM | $0.036 / hora |
default | 4 vCPU, 8 GB RAM | $0.072 / hora |
large | 8 vCPU, 16 GB RAM | $0.144 / hora |
- A tarifa por hora é fixada quando o sandbox é criado.
- Sandboxes parados são gratuitos. Os arquivos são mantidos enquanto estiverem parados.
- Você precisa de pelo menos $1 de saldo para criar ou retomar um sandbox.
Início rápido
export MUAPI_KEY="your-api-key"
# 1. Crie um 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. Execute um 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. Grave e leia um arquivo
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. Pare o sandbox (a cobrança é pausada)
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 | Caminho | Descrição |
|---|---|---|
POST | /api/v1/sandboxes | Criar um sandbox. Corpo: {"profile": "small" | "default" | "large"} |
GET | /api/v1/sandboxes | Listar seus sandboxes |
GET | /api/v1/sandboxes/{id} | Obter um sandbox |
POST | /api/v1/sandboxes/{id}/commands | Executar um comando shell |
GET | /api/v1/sandboxes/{id}/commands/{process_id} | Estado e saída de um comando em segundo plano |
PUT | /api/v1/sandboxes/{id}/files | Gravar um arquivo |
GET | /api/v1/sandboxes/{id}/files?path= | Ler um arquivo |
POST | /api/v1/sandboxes/{id}/stop | Parar (a cobrança é pausada) |
POST | /api/v1/sandboxes/{id}/resume | Retomar um sandbox parado |
DELETE | /api/v1/sandboxes/{id} | Excluir um sandbox e seus arquivos |
Executar um comando
POST /api/v1/sandboxes/{id}/commands
| Campo | Tipo | Padrão | Observações |
|---|---|---|---|
command | string | obrigatório | Comando shell, com até 20.000 caracteres |
timeout_seconds | integer | 30 | De 1 a 600 |
detached | boolean | false | Executar em segundo plano; consultar usando o process_id retornado |
cwd | string | . | Diretório de trabalho. Ele já precisa existir (por exemplo, execute mkdir -p /home/user/workspace primeiro) |
Para tarefas longas, defina detached: true e, em seguida, consulte GET /api/v1/sandboxes/{id}/commands/{process_id}.
Arquivos
PUT /files recebe {"path": "...", "content": "..."} com conteúdo em texto simples (até 2.000.000 de caracteres). GET /files?path=... retorna {"path": "...", "content": "..."}.
Ciclo de vida e cobrança
- Um novo sandbox fica
runningem alguns segundos e já vem com Python 3 instalado. - Parar não é instantâneo. A cobrança é interrompida no momento em que você solicita a parada, mas tentar retomar imediatamente pode resultar em um conflito por alguns segundos. A chamada de parada aguarda o término do arquivamento do sandbox antes de retornar, então é seguro parar e depois retomar.
- Os arquivos persistem ao parar e retomar.
- Um sandbox é parado automaticamente quando seu saldo não cobre o uso ou após 15 minutos sem atividade.
- Um sandbox parado é excluído após 14 dias. Baixe tudo o que precisar antes disso.
- Cada conta pode ter até 3 sandboxes ao mesmo tempo.
- Os comandos e o acesso aos arquivos são executados como um usuário comum dentro de uma máquina isolada. Você é responsável pelo que executar nela.
Playground e endpoints no estilo de tarefas
Todas as operações também estão disponíveis no Playground e como endpoint no estilo de tarefa, POST /api/v1/sandbox-<operation>, em que <operation> pode ser create, get, run-command, command-status, write-file, read-file, stop, resume ou delete. Eles recebem os mesmos campos das rotas REST, além de sandbox_id quando aplicável, e retornam um request_id que você consulta em GET /api/v1/predictions/{request_id}/result, como faria com qualquer outro modelo Muapi. A computação é cobrada somente pelo tempo de execução; essas solicitações em si custam $0.
Erros
Os erros usam {"error": {"code": "...", "message": "..."}}.
| Status | Código | Significado |
|---|---|---|
| 400 | INVALID_PROFILE | profile desconhecido |
| 402 | INSUFFICIENT_CREDITS | Saldo abaixo do mínimo de $1 para criar ou retomar |
| 422 | INVALID_INPUT | Um campo está ausente ou fora dos limites permitidos (endpoints no estilo de tarefas) |
| 502 | SANDBOX_UPSTREAM_ERROR | Erro temporário no backend; tente novamente |
Casos de uso
- Agentes de programação: clonar um repositório, instalar pacotes, executar testes e corrigir falhas em uma máquina real.
- Execução de código: executar código gerado ou não confiável longe da sua própria infraestrutura.
- Pipelines de mídia: executar ffmpeg ou scripts personalizados com resultados dos modelos de imagem, vídeo e áudio da Muapi.
- Aplicativos de código aberto hospedados: executar aplicativos na nuvem usando a chave Muapi do próprio usuário.
Consulte a página inicial da API de Sandbox para ver uma visão geral.