API piaskownicy

API piaskownicy udostępnia na żądanie izolowaną maszynę Linux w chmurze dla Twojego kodu lub agenta AI. Utwórz piaskownicę, uruchamiaj polecenia powłoki, odczytuj i zapisuj pliki, a następnie zatrzymaj ją lub usuń — wszystko przez REST, przy użyciu tego samego x-api-key i salda kredytów, których używasz do generowania obrazów, wideo i audio.

To nie to samo co klucze Sandbox (test). Klucze API utworzone z is_test: true nazywane są „kluczami sandboxowymi” i zwracają wyniki testowe dla endpointów generowania (zobacz Dokumentacja API). Opisane tutaj API piaskownicy tworzy prawdziwe maszyny w chmurze. Klucz testowy może wywoływać endpointy API piaskownicy, ale zwraca wynik testowy i niczego nie tworzy.

Rozmiary i ceny

Podczas tworzenia piaskownicy podaj profile. Opłaty są naliczane za każdą sekundę działania piaskownicy i pobierane z Twoich kredytów.

ProfilZasobyCena
small2 vCPU, 4 GB RAM$0.036 / godz.
default4 vCPU, 8 GB RAM$0.072 / godz.
large8 vCPU, 16 GB RAM$0.144 / godz.
  • Stawka godzinowa zostaje ustalona w chwili utworzenia piaskownicy.
  • Zatrzymane piaskownice są bezpłatne. Pliki są zachowywane podczas zatrzymania.
  • Aby utworzyć lub wznowić piaskownicę, potrzebujesz salda wynoszącego co najmniej $1.

Szybki start

export MUAPI_KEY="your-api-key"

# 1. Utwórz piaskownicę
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. Uruchom polecenie
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. Zapisz i odczytaj plik
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. Zatrzymaj ją (naliczanie opłat zostanie wstrzymane)
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)

Endpointy

MetodaŚcieżkaOpis
POST/api/v1/sandboxesUtwórz piaskownicę. Treść żądania: {"profile": "small" | "default" | "large"}
GET/api/v1/sandboxesWyświetl listę swoich piaskownic
GET/api/v1/sandboxes/{id}Pobierz informacje o jednej piaskownicy
POST/api/v1/sandboxes/{id}/commandsUruchom polecenie powłoki
GET/api/v1/sandboxes/{id}/commands/{process_id}Sprawdź status i wynik odłączonego polecenia
PUT/api/v1/sandboxes/{id}/filesZapisz plik
GET/api/v1/sandboxes/{id}/files?path=Odczytaj plik
POST/api/v1/sandboxes/{id}/stopZatrzymaj (naliczanie opłat zostanie wstrzymane)
POST/api/v1/sandboxes/{id}/resumeWznów zatrzymaną piaskownicę
DELETE/api/v1/sandboxes/{id}Usuń piaskownicę i jej pliki

Uruchamianie polecenia

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

PoleTypWartość domyślnaUwagi
commandstringwymaganePolecenie powłoki, do 20,000 znaków
timeout_secondsinteger30Od 1 do 600
detachedbooleanfalseUruchom w tle; sprawdzaj status za pomocą zwróconego process_id
cwdstring.Katalog roboczy. Musi już istnieć (na przykład najpierw uruchom mkdir -p /home/user/workspace)

W przypadku długich zadań ustaw detached: true, a następnie sprawdzaj status za pomocą GET /api/v1/sandboxes/{id}/commands/{process_id}.

Pliki

PUT /files przyjmuje {"path": "...", "content": "..."} z treścią w postaci zwykłego tekstu (do 2,000,000 znaków). GET /files?path=... zwraca {"path": "...", "content": "..."}.

Cykl życia i rozliczenia

  • Nowa piaskownica przechodzi w stan running w ciągu kilku sekund. Python 3 jest w niej zainstalowany.
  • Zatrzymanie nie następuje natychmiast. Naliczanie opłat ustaje w chwili wysłania żądania, ale wznowienie piaskownicy od razu może przez kilka sekund zwracać konflikt. Żądanie zatrzymania czeka na zakończenie archiwizacji piaskownicy, więc po zatrzymaniu można bezpiecznie ją wznowić.
  • Pliki są zachowywane po zatrzymaniu i wznowieniu piaskownicy.
  • Piaskownica jest automatycznie zatrzymywana, gdy saldo nie wystarcza na pokrycie dalszego użycia lub po 15 minutach bez aktywności.
  • Zatrzymana piaskownica jest usuwana po 14 dniach. Pobierz potrzebne pliki przed upływem tego czasu.
  • Każde konto może mieć jednocześnie maksymalnie 3 piaskownice.
  • Polecenia i dostęp do plików działają z uprawnieniami zwykłego użytkownika na izolowanej maszynie. Odpowiadasz za polecenia uruchamiane w tej maszynie.

Playground i endpointy w stylu zadań

Każda operacja jest dostępna w Playground oraz jako endpoint w stylu zadań: POST /api/v1/sandbox-<operation>, gdzie <operation> może mieć wartość create, get, run-command, command-status, write-file, read-file, stop, resume lub delete. Endpointy te przyjmują te same pola co trasy REST, a w odpowiednich przypadkach także sandbox_id. Zwracają request_id, który można odczytać przez GET /api/v1/predictions/{request_id}/result, tak jak w przypadku każdego innego modelu Muapi. Opłaty za obliczenia są naliczane wyłącznie za czas działania; same żądania kosztują $0.

Błędy

Błędy mają postać {"error": {"code": "...", "message": "..."}}.

StatusKodZnaczenie
400INVALID_PROFILENieznany profile
402INSUFFICIENT_CREDITSSaldo jest niższe niż wymagane minimum $1 do utworzenia lub wznowienia piaskownicy
422INVALID_INPUTBrakuje pola lub jego wartość jest poza dozwolonym zakresem (endpointy w stylu zadań)
502SANDBOX_UPSTREAM_ERRORTymczasowy błąd zaplecza; ponów próbę

Zastosowania

  • Agenci programistyczni: klonuj repozytorium, instaluj pakiety, uruchamiaj testy i naprawiaj błędy na prawdziwej maszynie.
  • Wykonywanie kodu: uruchamiaj wygenerowany lub niezaufany kod poza własną infrastrukturą.
  • Potoki przetwarzania multimediów: uruchamiaj ffmpeg lub własne skrypty na wynikach modeli Muapi do generowania obrazów, wideo i audio.
  • Aplikacje open source hostowane w chmurze: uruchamiaj aplikacje w chmurze przy użyciu własnego klucza Muapi.

Więcej informacji znajdziesz na stronie API piaskownicy.