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: truenazywane 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.
| Profil | Zasoby | Cena |
|---|---|---|
small | 2 vCPU, 4 GB RAM | $0.036 / godz. |
default | 4 vCPU, 8 GB RAM | $0.072 / godz. |
large | 8 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żka | Opis |
|---|---|---|
POST | /api/v1/sandboxes | Utwórz piaskownicę. Treść żądania: {"profile": "small" | "default" | "large"} |
GET | /api/v1/sandboxes | Wyświetl listę swoich piaskownic |
GET | /api/v1/sandboxes/{id} | Pobierz informacje o jednej piaskownicy |
POST | /api/v1/sandboxes/{id}/commands | Uruchom polecenie powłoki |
GET | /api/v1/sandboxes/{id}/commands/{process_id} | Sprawdź status i wynik odłączonego polecenia |
PUT | /api/v1/sandboxes/{id}/files | Zapisz plik |
GET | /api/v1/sandboxes/{id}/files?path= | Odczytaj plik |
POST | /api/v1/sandboxes/{id}/stop | Zatrzymaj (naliczanie opłat zostanie wstrzymane) |
POST | /api/v1/sandboxes/{id}/resume | Wznów zatrzymaną piaskownicę |
DELETE | /api/v1/sandboxes/{id} | Usuń piaskownicę i jej pliki |
Uruchamianie polecenia
POST /api/v1/sandboxes/{id}/commands
| Pole | Typ | Wartość domyślna | Uwagi |
|---|---|---|---|
command | string | wymagane | Polecenie powłoki, do 20,000 znaków |
timeout_seconds | integer | 30 | Od 1 do 600 |
detached | boolean | false | Uruchom w tle; sprawdzaj status za pomocą zwróconego process_id |
cwd | string | . | 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
runningw 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": "..."}}.
| Status | Kod | Znaczenie |
|---|---|---|
| 400 | INVALID_PROFILE | Nieznany profile |
| 402 | INSUFFICIENT_CREDITS | Saldo jest niższe niż wymagane minimum $1 do utworzenia lub wznowienia piaskownicy |
| 422 | INVALID_INPUT | Brakuje pola lub jego wartość jest poza dozwolonym zakresem (endpointy w stylu zadań) |
| 502 | SANDBOX_UPSTREAM_ERROR | Tymczasowy 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.