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: true sã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.

PerfilRecursosPreço
small2 vCPU, 4 GB RAM$0.036 / hora
default4 vCPU, 8 GB RAM$0.072 / hora
large8 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étodoCaminhoDescrição
POST/api/v1/sandboxesCriar um sandbox. Corpo: {"profile": "small" | "default" | "large"}
GET/api/v1/sandboxesListar seus sandboxes
GET/api/v1/sandboxes/{id}Obter um sandbox
POST/api/v1/sandboxes/{id}/commandsExecutar 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}/filesGravar um arquivo
GET/api/v1/sandboxes/{id}/files?path=Ler um arquivo
POST/api/v1/sandboxes/{id}/stopParar (a cobrança é pausada)
POST/api/v1/sandboxes/{id}/resumeRetomar um sandbox parado
DELETE/api/v1/sandboxes/{id}Excluir um sandbox e seus arquivos

Executar um comando

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

CampoTipoPadrãoObservações
commandstringobrigatórioComando shell, com até 20.000 caracteres
timeout_secondsinteger30De 1 a 600
detachedbooleanfalseExecutar em segundo plano; consultar usando o process_id retornado
cwdstring.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 running em 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": "..."}}.

StatusCódigoSignificado
400INVALID_PROFILEprofile desconhecido
402INSUFFICIENT_CREDITSSaldo abaixo do mínimo de $1 para criar ou retomar
422INVALID_INPUTUm campo está ausente ou fora dos limites permitidos (endpoints no estilo de tarefas)
502SANDBOX_UPSTREAM_ERRORErro 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.