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: truesont 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.
| Profil | Ressources | Prix |
|---|---|---|
small | 2 vCPU, 4 Go de RAM | 0,036 $ / heure |
default | 4 vCPU, 8 Go de RAM | 0,072 $ / heure |
large | 8 vCPU, 16 Go de RAM | 0,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éthode | Chemin | Description |
|---|---|---|
POST | /api/v1/sandboxes | Créer un bac à sable. Corps : {"profile": "small" | "default" | "large"} |
GET | /api/v1/sandboxes | Lister vos bacs à sable |
GET | /api/v1/sandboxes/{id} | Récupérer un bac à sable |
POST | /api/v1/sandboxes/{id}/commands | Exé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}/stop | Arrêter le bac à sable (la facturation est suspendue) |
POST | /api/v1/sandboxes/{id}/resume | Reprendre 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
| Champ | Type | Valeur par défaut | Remarques |
|---|---|---|---|
command | string | obligatoire | Commande shell, jusqu’à 20 000 caractères |
timeout_seconds | integer | 30 | De 1 à 600 |
detached | boolean | false | Exécuter en arrière-plan ; interroger l’état avec le process_id renvoyé |
cwd | string | . | 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
runningen 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": "..."}}.
| Statut | Code | Signification |
|---|---|---|
| 400 | INVALID_PROFILE | profile inconnu |
| 402 | INSUFFICIENT_CREDITS | Solde inférieur au minimum de 1 $ requis pour créer ou reprendre un bac à sable |
| 422 | INVALID_INPUT | Un champ est manquant ou hors limites (points de terminaison de type tâche) |
| 502 | SANDBOX_UPSTREAM_ERROR | Erreur 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.