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: true ile 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.

ProfilKaynaklarFiyat
small2 vCPU, 4 GB RAM$0.036 / saat
default4 vCPU, 8 GB RAM$0.072 / saat
large8 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öntemYolAçıklama
POST/api/v1/sandboxesBir sandbox oluşturur. Gövde: {"profile": "small" | "default" | "large"}
GET/api/v1/sandboxesSandbox’larınızı listeler
GET/api/v1/sandboxes/{id}Bir sandbox’ın bilgilerini getirir
POST/api/v1/sandboxes/{id}/commandsBir 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}/filesBir dosyaya yazar
GET/api/v1/sandboxes/{id}/files?path=Bir dosyayı okur
POST/api/v1/sandboxes/{id}/stopDurdurur (faturalandırma duraklar)
POST/api/v1/sandboxes/{id}/resumeDurdurulmuş 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

AlanTürVarsayılanNotlar
commandstringzorunlu20.000 karaktere kadar kabuk komutu
timeout_secondsinteger301 ile 600 arasında
detachedbooleanfalseArka planda çalıştırır; döndürülen process_id ile durumunu sorgulayın
cwdstring.Ç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 running durumuna 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.

DurumKodAnlamı
400INVALID_PROFILEBilinmeyen profile
402INSUFFICIENT_CREDITSBakiye, oluşturma veya yeniden başlatma için gereken $1 minimum tutarın altında
422INVALID_INPUTBir alan eksik veya izin verilen aralığın dışında (görev tarzı uç noktalar)
502SANDBOX_UPSTREAM_ERRORGeç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.