رابط API سندباکس

رابط API سندباکس در صورت نیاز، یک ماشین لینوکس ابری و ایزوله در اختیار کد یا عامل هوش مصنوعی شما قرار می‌دهد. یک سندباکس ایجاد کنید، فرمان‌های شل اجرا کنید، فایل‌ها را بخوانید و بنویسید و سپس آن را متوقف یا حذف کنید؛ همه این کارها از طریق REST و با همان x-api-key و موجودی اعتباری انجام می‌شود که برای تولید تصویر، ویدیو و صدا استفاده می‌کنید.

با کلیدهای Sandbox (آزمایشی) یکی نیست. به کلیدهای API که با is_test: true ساخته می‌شوند «کلیدهای سندباکس» گفته می‌شود و این کلیدها برای endpointهای تولید، نتایج ساختگی برمی‌گردانند (به مرجع API مراجعه کنید). رابط API سندباکس که در اینجا توضیح داده شده، ماشین‌های ابری واقعی ایجاد می‌کند. یک کلید آزمایشی می‌تواند endpointهای رابط API سندباکس را فراخوانی کند، اما نتیجه‌ای ساختگی برمی‌گرداند و چیزی ایجاد نمی‌کند.

اندازه‌ها و قیمت‌گذاری

هنگام ایجاد سندباکس، profile را ارسال کنید. هزینه در مدت اجرای سندباکس، به‌ازای هر ثانیه و از اعتبار شما کسر می‌شود.

پروفایلمنابعقیمت
small2 vCPU، 4 GB RAM$0.036 / hour
default4 vCPU، 8 GB RAM$0.072 / hour
large8 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": "..."}} استفاده می‌کنند.

وضعیتکدمعنی
400INVALID_PROFILEprofile ناشناخته است
402INSUFFICIENT_CREDITSموجودی کمتر از حداقل $1 برای ایجاد یا ازسرگیری است
422INVALID_INPUTفیلدی وجود ندارد یا مقدار آن خارج از محدوده است (endpointهای سبک وظیفه)
502SANDBOX_UPSTREAM_ERRORخطای موقت backend؛ دوباره تلاش کنید

موارد استفاده

  • عامل‌های برنامه‌نویسی: یک مخزن را clone کنید، بسته‌ها را نصب کنید، آزمون‌ها را اجرا کنید و خطاها را در یک ماشین واقعی برطرف کنید.
  • اجرای کد: کد تولیدشده یا غیرقابل‌اعتماد را خارج از زیرساخت خودتان اجرا کنید.
  • خطوط پردازش رسانه: ffmpeg یا اسکریپت‌های سفارشی را روی خروجی مدل‌های تصویر، ویدیو و صدای Muapi اجرا کنید.
  • برنامه‌های متن‌باز میزبانی‌شده: برنامه‌ها را در فضای ابری و با کلید Muapi خود کاربر اجرا کنید.

برای آشنایی کلی، به صفحه معرفی رابط API سندباکس مراجعه کنید.