Sandbox API
Sandbox API, kodunuza veya yapay zekâ ajanınıza isteğe bağlı olarak yalıtılmış bir bulut Linux makinesi sağlar. Bir sandbox oluşturun, kabuk komutları çalıştırın, dosyaları okuyup yazın, ardından makineyi durdurun veya silin. Tüm bunları, görsel, video ve ses üretiminde kullandığınız aynı x-api-key ve kredi bakiyesiyle REST üzerinden yapabilirsiniz.
Sandbox (test) anahtarlarıyla aynı değildir.
is_test: trueile oluşturulan API anahtarlarına “sandbox anahtarları” denir ve üretim uç noktalarında sahte sonuçlar döndürürler (API Referansı bölümüne bakın). Burada açıklanan Sandbox API, gerçek bulut makineleri oluşturur. Bir test anahtarı Sandbox API uç noktalarını çağırabilir; ancak sahte bir sonuç döndürür ve hiçbir şey oluşturmaz.
Boyutlar ve fiyatlandırma
Sandbox oluştururken profile değerini gönderin. Sandbox çalışırken saniye başına ücret alınır ve tutar kredilerinizden düşülür.
| Profil | Kaynaklar | Fiyat |
|---|---|---|
small | 2 vCPU, 4 GB RAM | $0.036 / saat |
default | 4 vCPU, 8 GB RAM | $0.072 / saat |
large | 8 vCPU, 16 GB RAM | $0.144 / saat |
- Saatlik ücret, sandbox oluşturulduğunda sabitlenir.
- Durdurulmuş sandbox’lar ücretsizdir. Dosyalar durdurulduğu sürece saklanır.
- Sandbox oluşturmak veya yeniden başlatmak için en az $1 bakiyeniz olmalıdır.
Hızlı başlangıç
export MUAPI_KEY="your-api-key"
# 1. Bir sandbox oluşturun
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. Bir komut çalıştırın
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. Bir dosyaya yazın ve dosyayı okuyun
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. Sandbox’ı durdurun (faturalandırma duraklar)
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)
Uç noktalar
| Yöntem | Yol | Açıklama |
|---|---|---|
POST | /api/v1/sandboxes | Bir sandbox oluşturur. Gövde: {"profile": "small" | "default" | "large"} |
GET | /api/v1/sandboxes | Sandbox’larınızı listeler |
GET | /api/v1/sandboxes/{id} | Bir sandbox’ın bilgilerini getirir |
POST | /api/v1/sandboxes/{id}/commands | Bir kabuk komutu çalıştırır |
GET | /api/v1/sandboxes/{id}/commands/{process_id} | Ayrılmış bir komutun durumunu ve çıktısını getirir |
PUT | /api/v1/sandboxes/{id}/files | Bir dosyaya yazar |
GET | /api/v1/sandboxes/{id}/files?path= | Bir dosyayı okur |
POST | /api/v1/sandboxes/{id}/stop | Durdurur (faturalandırma duraklar) |
POST | /api/v1/sandboxes/{id}/resume | Durdurulmuş bir sandbox’ı yeniden başlatır |
DELETE | /api/v1/sandboxes/{id} | Bir sandbox’ı ve dosyalarını siler |
Komut çalıştırma
POST /api/v1/sandboxes/{id}/commands
| Alan | Tür | Varsayılan | Notlar |
|---|---|---|---|
command | string | zorunlu | 20.000 karaktere kadar kabuk komutu |
timeout_seconds | integer | 30 | 1 ile 600 arasında |
detached | boolean | false | Arka planda çalıştırır; döndürülen process_id ile durumunu sorgulayın |
cwd | string | . | Çalışma dizini. Önceden mevcut olmalıdır (örneğin önce mkdir -p /home/user/workspace çalıştırın) |
Uzun süren işler için detached: true ayarlayın, ardından GET /api/v1/sandboxes/{id}/commands/{process_id} ile durumunu sorgulayın.
Dosyalar
PUT /files, düz metin içerikli {"path": "...", "content": "..."} alır (en fazla 2.000.000 karakter). GET /files?path=... ise {"path": "...", "content": "..."} döndürür.
Yaşam döngüsü ve faturalandırma
- Yeni bir sandbox birkaç saniye içinde
runningdurumuna geçer ve Python 3 önceden yüklenmiş olarak gelir. - Durdurma işlemi anlık değildir. İsteği gönderdiğiniz anda faturalandırma durur; ancak hemen yeniden başlatmaya çalışırsanız birkaç saniyeliğine çakışma hatası alabilirsiniz. Durdurma çağrısı, yanıt vermeden önce sandbox’ın arşivlenmesinin tamamlanmasını bekler; bu nedenle durdurup ardından yeniden başlatmak güvenlidir.
- Dosyalar durdurma ve yeniden başlatma işlemleri boyunca saklanır.
- Bakiyeniz kullanımı karşılamadığında veya 15 dakika boyunca etkinlik olmadığında sandbox otomatik olarak durdurulur.
- Durdurulmuş bir sandbox 14 gün sonra silinir. İhtiyacınız olan dosyaları bu süre dolmadan indirin.
- Her hesap aynı anda en fazla 3 sandbox’a sahip olabilir.
- Komutlar ve dosya erişimi, yalıtılmış makinede normal bir kullanıcı olarak çalışır. Makinede çalıştırdıklarınızdan siz sorumlusunuz.
Playground ve görev tarzı uç noktalar
Her işlem Playground’da ve POST /api/v1/sandbox-<operation> biçimindeki görev tarzı bir uç noktada da kullanılabilir. <operation> şu değerlerden biridir: create, get, run-command, command-status, write-file, read-file, stop, resume, delete. Bu uç noktalar, ilgili durumlarda sandbox_id ile birlikte REST rotalarıyla aynı alanları alır ve diğer Muapi modellerinde olduğu gibi GET /api/v1/predictions/{request_id}/result üzerinden okuyabileceğiniz bir request_id döndürür. Hesaplama yalnızca çalışma süresine göre ücretlendirilir; bu isteklerin kendisi $0 tutarındadır.
Hatalar
Hatalar {"error": {"code": "...", "message": "..."}} biçimindedir.
| Durum | Kod | Anlamı |
|---|---|---|
| 400 | INVALID_PROFILE | Bilinmeyen profile |
| 402 | INSUFFICIENT_CREDITS | Bakiye, oluşturma veya yeniden başlatma için gereken $1 minimum tutarın altında |
| 422 | INVALID_INPUT | Bir alan eksik veya izin verilen aralığın dışında (görev tarzı uç noktalar) |
| 502 | SANDBOX_UPSTREAM_ERROR | Geçici arka uç hatası; yeniden deneyin |
Kullanım alanları
- Kodlama ajanları: Bir depoyu klonlayın, paketleri yükleyin, gerçek bir makinede testleri çalıştırıp hataları düzeltin.
- Kod yürütme: Üretilen veya güvenilmeyen kodu kendi altyapınızdan uzakta çalıştırın.
- Medya işlem hatları: Muapi görsel, video ve ses modellerinin çıktılarında ffmpeg veya özel betikler çalıştırın.
- Barındırılan açık kaynak uygulamalar: Uygulamaları bulutta kullanıcının kendi Muapi anahtarıyla çalıştırın.
Genel bakış için Sandbox API tanıtım sayfasına bakın.