رابط API سندباکس
رابط API سندباکس در صورت نیاز، یک ماشین لینوکس ابری و ایزوله در اختیار کد یا عامل هوش مصنوعی شما قرار میدهد. یک سندباکس ایجاد کنید، فرمانهای شل اجرا کنید، فایلها را بخوانید و بنویسید و سپس آن را متوقف یا حذف کنید؛ همه این کارها از طریق REST و با همان x-api-key و موجودی اعتباری انجام میشود که برای تولید تصویر، ویدیو و صدا استفاده میکنید.
با کلیدهای Sandbox (آزمایشی) یکی نیست. به کلیدهای API که با
is_test: trueساخته میشوند «کلیدهای سندباکس» گفته میشود و این کلیدها برای endpointهای تولید، نتایج ساختگی برمیگردانند (به مرجع API مراجعه کنید). رابط API سندباکس که در اینجا توضیح داده شده، ماشینهای ابری واقعی ایجاد میکند. یک کلید آزمایشی میتواند endpointهای رابط API سندباکس را فراخوانی کند، اما نتیجهای ساختگی برمیگرداند و چیزی ایجاد نمیکند.
اندازهها و قیمتگذاری
هنگام ایجاد سندباکس، profile را ارسال کنید. هزینه در مدت اجرای سندباکس، بهازای هر ثانیه و از اعتبار شما کسر میشود.
| پروفایل | منابع | قیمت |
|---|---|---|
small | 2 vCPU، 4 GB RAM | $0.036 / hour |
default | 4 vCPU، 8 GB RAM | $0.072 / hour |
large | 8 vCPU، 16 GB RAM | $0.144 / hour |
- نرخ ساعتی هنگام ایجاد سندباکس ثابت میشود.
- سندباکسهای متوقفشده رایگان هستند. فایلها در زمان توقف نگه داشته میشوند.
- برای ایجاد یا ازسرگیری سندباکس، باید حداقل $1 موجودی داشته باشید.
شروع سریع
export MUAPI_KEY="your-api-key"
# ۱. ایجاد یک سندباکس
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>"
# ۲. اجرای یک فرمان
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}'
# ۳. نوشتن و خواندن یک فایل
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"
# ۴. توقف آن (صورتحساب متوقف میشود)
curl -X POST https://api.muapi.ai/api/v1/sandboxes/$ID/stop \
-H "x-api-key: $MUAPI_KEY"
پایتون
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)
Endpointها
| روش | مسیر | توضیحات |
|---|---|---|
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
| فیلد | نوع | پیشفرض | توضیحات |
|---|---|---|---|
command | رشته | الزامی | فرمان شل، حداکثر ۲۰٬۰۰۰ نویسه |
timeout_seconds | عدد صحیح | 30 | از ۱ تا ۶۰۰ |
detached | بولی | false | اجرا در پسزمینه؛ با process_id برگشتی وضعیت را بررسی کنید |
cwd | رشته | . | پوشه کاری. باید از قبل وجود داشته باشد (برای مثال، ابتدا mkdir -p /home/user/workspace را اجرا کنید) |
برای کارهای طولانی، detached: true را تنظیم کنید و سپس با GET /api/v1/sandboxes/{id}/commands/{process_id} وضعیت را بررسی کنید.
فایلها
درخواست PUT /files بدنهای با قالب {"path": "...", "content": "..."} و محتوای متنی ساده میگیرد (حداکثر ۲٬۰۰۰٬۰۰۰ نویسه). درخواست GET /files?path=... مقدار {"path": "...", "content": "..."} را برمیگرداند.
چرخه عمر و صورتحساب
- سندباکس جدید ظرف چند ثانیه به وضعیت
runningمیرسد و Python 3 از پیش روی آن نصب است. - توقف آنی نیست. صورتحساب از لحظه درخواست شما متوقف میشود، اما اگر بلافاصله ازسرگیری کنید، ممکن است تا چند ثانیه با خطای تداخل روبهرو شوید. فراخوانی توقف منتظر میماند تا بایگانی سندباکس کامل شود؛ بنابراین توقف و سپس ازسرگیری ایمن است.
- فایلها پس از توقف و ازسرگیری باقی میمانند.
- اگر موجودی شما برای پوشش هزینه کافی نباشد یا ۱۵ دقیقه فعالیتی انجام نشود، سندباکس بهطور خودکار متوقف میشود.
- سندباکس متوقفشده پس از ۱۴ روز حذف میشود. هرچه نیاز دارید پیش از آن دانلود کنید.
- هر حساب میتواند همزمان حداکثر ۳ سندباکس داشته باشد.
- فرمانها و دسترسی به فایلها در یک ماشین ایزوله و با مجوزهای یک کاربر عادی اجرا میشوند. مسئولیت فرمانهایی که اجرا میکنید بر عهده خودتان است.
Playground و endpointهای سبک وظیفه
هر عملیات از طریق Playground و همچنین بهصورت یک endpoint سبک وظیفه، یعنی POST /api/v1/sandbox-<operation>، در دسترس است. <operation> یکی از این موارد است: create، get، run-command، command-status، write-file، read-file، stop، resume، delete. این endpointها همان فیلدهای مسیرهای REST را بهعلاوه sandbox_id در صورت نیاز میگیرند و یک request_id برمیگردانند. نتیجه را با GET /api/v1/predictions/{request_id}/result دریافت میکنید، درست مانند هر مدل دیگری در Muapi. هزینه محاسبات فقط بر اساس مدت اجرا محاسبه میشود؛ خود این درخواستها $0 هزینه دارند.
خطاها
خطاها از قالب {"error": {"code": "...", "message": "..."}} استفاده میکنند.
| وضعیت | کد | معنی |
|---|---|---|
| 400 | INVALID_PROFILE | profile ناشناخته است |
| 402 | INSUFFICIENT_CREDITS | موجودی کمتر از حداقل $1 برای ایجاد یا ازسرگیری است |
| 422 | INVALID_INPUT | فیلدی وجود ندارد یا مقدار آن خارج از محدوده است (endpointهای سبک وظیفه) |
| 502 | SANDBOX_UPSTREAM_ERROR | خطای موقت backend؛ دوباره تلاش کنید |
موارد استفاده
- عاملهای برنامهنویسی: یک مخزن را clone کنید، بستهها را نصب کنید، آزمونها را اجرا کنید و خطاها را در یک ماشین واقعی برطرف کنید.
- اجرای کد: کد تولیدشده یا غیرقابلاعتماد را خارج از زیرساخت خودتان اجرا کنید.
- خطوط پردازش رسانه: ffmpeg یا اسکریپتهای سفارشی را روی خروجی مدلهای تصویر، ویدیو و صدای Muapi اجرا کنید.
- برنامههای متنباز میزبانیشده: برنامهها را در فضای ابری و با کلید Muapi خود کاربر اجرا کنید.
برای آشنایی کلی، به صفحه معرفی رابط API سندباکس مراجعه کنید.