API de bac à sable

L’API de bac à sable fournit à votre code ou à votre agent IA une machine Linux cloud isolée à la demande. Créez un bac à sable, exécutez des commandes shell, lisez et écrivez des fichiers, puis arrêtez-le ou supprimez-le : le tout via REST, avec la même clé x-api-key et le même solde de crédits que ceux utilisés pour générer des images, des vidéos et de l’audio.

À ne pas confondre avec les clés Sandbox (test). Les clés API créées avec is_test: true sont appelées « clés sandbox » et renvoient des résultats simulés pour les points de terminaison de génération (voir la référence de l’API). L’API de bac à sable décrite ici crée de vraies machines cloud. Une clé de test peut appeler les points de terminaison de l’API de bac à sable, mais elle renvoie un résultat simulé et ne crée rien.

Tailles et tarifs

Indiquez profile lors de la création d’un bac à sable. La facturation s’effectue à la seconde pendant que le bac à sable est en cours d’exécution et est déduite de vos crédits.

ProfilRessourcesPrix
small2 vCPU, 4 Go de RAM0,036 $ / heure
default4 vCPU, 8 Go de RAM0,072 $ / heure
large8 vCPU, 16 Go de RAM0,144 $ / heure
  • Le tarif horaire est fixé au moment de la création du bac à sable.
  • Les bacs à sable arrêtés sont gratuits. Les fichiers sont conservés pendant l’arrêt.
  • Votre solde doit être d’au moins 1 $ pour créer ou reprendre un bac à sable.

Démarrage rapide

export MUAPI_KEY="your-api-key"

# 1. Créer un bac à sable
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. Exécuter une commande
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. Écrire et lire un fichier
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. Arrêter le bac à sable (la facturation est suspendue)
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)

Points de terminaison

MéthodeCheminDescription
POST/api/v1/sandboxesCréer un bac à sable. Corps : {"profile": "small" | "default" | "large"}
GET/api/v1/sandboxesLister vos bacs à sable
GET/api/v1/sandboxes/{id}Récupérer un bac à sable
POST/api/v1/sandboxes/{id}/commandsExécuter une commande shell
GET/api/v1/sandboxes/{id}/commands/{process_id}État et sortie d’une commande détachée
PUT/api/v1/sandboxes/{id}/filesÉcrire un fichier
GET/api/v1/sandboxes/{id}/files?path=Lire un fichier
POST/api/v1/sandboxes/{id}/stopArrêter le bac à sable (la facturation est suspendue)
POST/api/v1/sandboxes/{id}/resumeReprendre un bac à sable arrêté
DELETE/api/v1/sandboxes/{id}Supprimer un bac à sable et ses fichiers

Exécuter une commande

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

ChampTypeValeur par défautRemarques
commandstringobligatoireCommande shell, jusqu’à 20 000 caractères
timeout_secondsinteger30De 1 à 600
detachedbooleanfalseExécuter en arrière-plan ; interroger l’état avec le process_id renvoyé
cwdstring.Répertoire de travail. Il doit déjà exister (par exemple, exécutez d’abord mkdir -p /home/user/workspace)

Pour les tâches longues, définissez detached: true, puis interrogez GET /api/v1/sandboxes/{id}/commands/{process_id}.

Fichiers

PUT /files accepte {"path": "...", "content": "..."} avec un contenu en texte brut (jusqu’à 2 000 000 de caractères). GET /files?path=... renvoie {"path": "...", "content": "..."}.

Cycle de vie et facturation

  • Un nouveau bac à sable passe à l’état running en quelques secondes et Python 3 y est préinstallé.
  • L’arrêt n’est pas instantané. La facturation cesse au moment où vous en faites la demande, mais une reprise immédiate peut renvoyer un conflit pendant quelques secondes. L’appel d’arrêt attend que le bac à sable ait terminé son archivage avant de renvoyer une réponse : vous pouvez donc l’arrêter puis le reprendre sans risque.
  • Les fichiers sont conservés après l’arrêt et la reprise.
  • Un bac à sable est arrêté automatiquement lorsque votre solde ne permet plus de couvrir son utilisation, ou après 15 minutes sans activité.
  • Un bac à sable arrêté est supprimé au bout de 14 jours. Téléchargez ce dont vous avez besoin avant cette échéance.
  • Chaque compte peut avoir jusqu’à 3 bacs à sable à la fois.
  • Les commandes et l’accès aux fichiers s’exécutent sous un utilisateur standard dans une machine isolée. Vous êtes responsable de ce que vous y exécutez.

Playground et points de terminaison de type tâche

Chaque opération est également disponible dans le Playground et sous forme de point de terminaison de type tâche, POST /api/v1/sandbox-<operation>, où <operation> peut être create, get, run-command, command-status, write-file, read-file, stop, resume ou delete. Ces points de terminaison acceptent les mêmes champs que les routes REST, auxquels s’ajoute sandbox_id le cas échéant, et renvoient un request_id que vous pouvez lire avec GET /api/v1/predictions/{request_id}/result, comme pour tout autre modèle Muapi. Le calcul est facturé uniquement en fonction de la durée d’exécution ; ces requêtes elles-mêmes ne coûtent rien.

Erreurs

Les erreurs utilisent {"error": {"code": "...", "message": "..."}}.

StatutCodeSignification
400INVALID_PROFILEprofile inconnu
402INSUFFICIENT_CREDITSSolde inférieur au minimum de 1 $ requis pour créer ou reprendre un bac à sable
422INVALID_INPUTUn champ est manquant ou hors limites (points de terminaison de type tâche)
502SANDBOX_UPSTREAM_ERRORErreur temporaire du serveur en amont ; réessayez

Cas d’usage

  • Agents de programmation : cloner un dépôt, installer des paquets, exécuter des tests et corriger les échecs sur une vraie machine.
  • Exécution de code : exécuter du code généré ou non fiable à l’écart de votre propre infrastructure.
  • Chaînes de traitement multimédia : exécuter ffmpeg ou des scripts personnalisés sur les résultats des modèles d’image, de vidéo et d’audio de Muapi.
  • Applications open source hébergées : exécuter des applications dans le cloud avec la propre clé Muapi de l’utilisateur.

Consultez la page de présentation de l’API de bac à sable pour en savoir plus.