API песочницы

API песочницы предоставляет вашему коду или ИИ-агенту изолированную облачную машину Linux по запросу. Создавайте песочницу, выполняйте команды оболочки, читайте и записывайте файлы, а затем останавливайте или удаляйте её — всё через REST с тем же x-api-key и балансом кредитов, которые вы используете для генерации изображений, видео и аудио.

Это не то же самое, что тестовые ключи Sandbox. Ключи API, созданные с is_test: true, называются «ключами песочницы» и возвращают фиктивные результаты для конечных точек генерации (см. Справочник по API). Описанный здесь API песочницы создаёт настоящие облачные машины. Тестовый ключ может обращаться к конечным точкам API песочницы, но вернёт фиктивный результат и ничего не создаст.

Размеры и цены

При создании песочницы передайте параметр profile. Пока песочница работает, плата начисляется за секунду и списывается с ваших кредитов.

ПрофильРесурсыЦена
small2 vCPU, 4 ГБ ОЗУ$0.036 / час
default4 vCPU, 8 ГБ ОЗУ$0.072 / час
large8 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

ПолеТипПо умолчаниюПримечания
commandstringобязательноКоманда оболочки, не более 20 000 символов
timeout_secondsinteger30От 1 до 600
detachedbooleanfalseВыполнить в фоновом режиме; проверяйте статус по возвращённому process_id
cwdstring.Рабочая директория. Она должна уже существовать (например, сначала выполните 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": "..."}}.

СтатусКодЗначение
400INVALID_PROFILEНеизвестный profile
402INSUFFICIENT_CREDITSБаланс ниже минимальных $1 для создания или возобновления песочницы
422INVALID_INPUTПоле отсутствует или его значение вне допустимого диапазона (конечные точки в стиле задач)
502SANDBOX_UPSTREAM_ERRORВременная ошибка серверной части; повторите запрос

Примеры использования

  • Агенты для программирования: клонируйте репозиторий, установите пакеты, запустите тесты и исправьте ошибки на настоящей машине.
  • Выполнение кода: запускайте сгенерированный или недоверенный код отдельно от собственной инфраструктуры.
  • Медиапроцессы: запускайте ffmpeg или пользовательские скрипты для обработки результатов моделей Muapi для генерации изображений, видео и аудио.
  • Размещение приложений с открытым исходным кодом: запускайте приложения в облаке с собственным ключом Muapi пользователя.

Обзор см. на странице API песочницы.