API песочницы
API песочницы предоставляет вашему коду или ИИ-агенту изолированную облачную машину Linux по запросу. Создавайте песочницу, выполняйте команды оболочки, читайте и записывайте файлы, а затем останавливайте или удаляйте её — всё через REST с тем же x-api-key и балансом кредитов, которые вы используете для генерации изображений, видео и аудио.
Это не то же самое, что тестовые ключи Sandbox. Ключи API, созданные с
is_test: true, называются «ключами песочницы» и возвращают фиктивные результаты для конечных точек генерации (см. Справочник по API). Описанный здесь API песочницы создаёт настоящие облачные машины. Тестовый ключ может обращаться к конечным точкам API песочницы, но вернёт фиктивный результат и ничего не создаст.
Размеры и цены
При создании песочницы передайте параметр profile. Пока песочница работает, плата начисляется за секунду и списывается с ваших кредитов.
| Профиль | Ресурсы | Цена |
|---|---|---|
small | 2 vCPU, 4 ГБ ОЗУ | $0.036 / час |
default | 4 vCPU, 8 ГБ ОЗУ | $0.072 / час |
large | 8 vCPU, 16 ГБ ОЗУ | $0.144 / час |
- Почасовая ставка фиксируется при создании песочницы.
- Остановленные песочницы бесплатны. Файлы сохраняются, пока песочница остановлена.
- Для создания или возобновления песочницы на балансе должно быть не менее $1.
Быстрый старт
export MUAPI_KEY="your-api-key"
# 1. Создайте песочницу
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. Выполните команду
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. Запишите и прочитайте файл
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. Остановите песочницу (начисление платы приостанавливается)
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)
Конечные точки
| Метод | Путь | Описание |
|---|---|---|
POST | /api/v1/sandboxes | Создать песочницу. Тело запроса: {"profile": "small" | "default" | "large"} |
GET | /api/v1/sandboxes | Получить список ваших песочниц |
GET | /api/v1/sandboxes/{id} | Получить сведения об одной песочнице |
POST | /api/v1/sandboxes/{id}/commands | Выполнить команду оболочки |
GET | /api/v1/sandboxes/{id}/commands/{process_id} | Получить статус и вывод фоновой команды |
PUT | /api/v1/sandboxes/{id}/files | Записать файл |
GET | /api/v1/sandboxes/{id}/files?path= | Прочитать файл |
POST | /api/v1/sandboxes/{id}/stop | Остановить песочницу (начисление платы приостанавливается) |
POST | /api/v1/sandboxes/{id}/resume | Возобновить работу остановленной песочницы |
DELETE | /api/v1/sandboxes/{id} | Удалить песочницу и её файлы |
Выполнение команды
POST /api/v1/sandboxes/{id}/commands
| Поле | Тип | По умолчанию | Примечания |
|---|---|---|---|
command | string | обязательно | Команда оболочки, не более 20 000 символов |
timeout_seconds | integer | 30 | От 1 до 600 |
detached | boolean | false | Выполнить в фоновом режиме; проверяйте статус по возвращённому process_id |
cwd | string | . | Рабочая директория. Она должна уже существовать (например, сначала выполните mkdir -p /home/user/workspace) |
Для длительных задач задайте detached: true, а затем проверяйте статус через GET /api/v1/sandboxes/{id}/commands/{process_id}.
Файлы
Запрос PUT /files принимает {"path": "...", "content": "..."} с обычным текстом (до 2 000 000 символов). Запрос GET /files?path=... возвращает {"path": "...", "content": "..."}.
Жизненный цикл и оплата
- Новая песочница переходит в состояние
runningв течение нескольких секунд; в ней предустановлен Python 3. - Остановка происходит не мгновенно. Начисление платы прекращается в момент отправки запроса, но при немедленном возобновлении в течение нескольких секунд может вернуться конфликт. Запрос на остановку ожидает завершения архивирования песочницы, прежде чем вернуть ответ, поэтому после остановки её можно безопасно возобновить.
- Файлы сохраняются при остановке и возобновлении.
- Песочница останавливается автоматически, если баланса не хватает для оплаты использования или если 15 минут нет активности.
- Остановленная песочница удаляется через 14 дней. До этого срока скачайте всё необходимое.
- В каждом аккаунте одновременно может быть не более 3 песочниц.
- Команды и доступ к файлам выполняются от имени обычного пользователя внутри изолированной машины. Вы несёте ответственность за выполняемые в ней действия.
Конечные точки Playground и в стиле задач
Каждая операция также доступна в Playground и как конечная точка в стиле задач: POST /api/v1/sandbox-<operation>, где <operation> — одно из значений create, get, run-command, command-status, write-file, read-file, stop, resume, delete. Они принимают те же поля, что и маршруты REST, а также sandbox_id, если он требуется, и возвращают request_id. Результат можно получить через GET /api/v1/predictions/{request_id}/result, как и для любой другой модели Muapi. Вычисления оплачиваются только за время работы; сами запросы стоят $0.
Ошибки
Ошибки возвращаются в формате {"error": {"code": "...", "message": "..."}}.
| Статус | Код | Значение |
|---|---|---|
| 400 | INVALID_PROFILE | Неизвестный profile |
| 402 | INSUFFICIENT_CREDITS | Баланс ниже минимальных $1 для создания или возобновления песочницы |
| 422 | INVALID_INPUT | Поле отсутствует или его значение вне допустимого диапазона (конечные точки в стиле задач) |
| 502 | SANDBOX_UPSTREAM_ERROR | Временная ошибка серверной части; повторите запрос |
Примеры использования
- Агенты для программирования: клонируйте репозиторий, установите пакеты, запустите тесты и исправьте ошибки на настоящей машине.
- Выполнение кода: запускайте сгенерированный или недоверенный код отдельно от собственной инфраструктуры.
- Медиапроцессы: запускайте ffmpeg или пользовательские скрипты для обработки результатов моделей Muapi для генерации изображений, видео и аудио.
- Размещение приложений с открытым исходным кодом: запускайте приложения в облаке с собственным ключом Muapi пользователя.
Обзор см. на странице API песочницы.