واجهة API للبيئات المعزولة
تتيح واجهة API للبيئات المعزولة تشغيل تعليماتك البرمجية أو وكيل الذكاء الاصطناعي على آلة Linux سحابية معزولة عند الطلب. أنشئ بيئة معزولة، وشغّل أوامر shell، واقرأ الملفات واكتبها، ثم أوقف البيئة أو احذفها؛ كل ذلك عبر REST باستخدام x-api-key ورصيد الاعتمادات نفسه الذي تستخدمه لتوليد الصور والفيديو والصوت.
هذه ليست مفاتيح Sandbox (الاختبار). تُسمّى مفاتيح API التي أُنشئت مع
is_test: true«مفاتيح sandbox»، وتُرجع نتائج وهمية لنقاط نهاية التوليد (راجع مرجع API). أما واجهة API للبيئات المعزولة الموضّحة هنا فتنشئ آلات سحابية حقيقية. يمكن لمفتاح اختبار استدعاء نقاط نهاية واجهة API هذه، لكنه يُرجع نتيجة وهمية ولا ينشئ أي شيء.
الأحجام والأسعار
مرّر profile عند إنشاء بيئة معزولة. تُحتسب الفوترة بالثانية أثناء تشغيلها، وتُخصم من رصيد اعتماداتك.
| الملف التعريفي | الموارد | السعر |
|---|---|---|
small | 2 vCPU، و4 GB RAM | $0.036 / الساعة |
default | 4 vCPU، و8 GB RAM | $0.072 / الساعة |
large | 8 vCPU، و16 GB RAM | $0.144 / الساعة |
- يُثبّت سعر الساعة عند إنشاء البيئة المعزولة.
- البيئات المعزولة المتوقفة مجانية. تبقى الملفات محفوظة أثناء التوقف.
- تحتاج إلى رصيد لا يقل عن $1 لإنشاء بيئة معزولة أو استئنافها.
البدء السريع
export MUAPI_KEY="your-api-key"
# 1. أنشئ بيئة معزولة
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. شغّل أمرًا
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. اكتب ملفًا واقرأه
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. أوقفها (تتوقف الفوترة)
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)
نقاط النهاية
| الطريقة | المسار | الوصف |
|---|---|---|
POST | /api/v1/sandboxes | إنشاء بيئة معزولة. المحتوى: {"profile": "small" | "default" | "large"} |
GET | /api/v1/sandboxes | عرض قائمة البيئات المعزولة |
GET | /api/v1/sandboxes/{id} | جلب بيئة معزولة واحدة |
POST | /api/v1/sandboxes/{id}/commands | تشغيل أمر shell |
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 | string | مطلوب | أمر shell، حتى 20,000 حرف |
timeout_seconds | integer | 30 | من 1 إلى 600 |
detached | boolean | false | التشغيل في الخلفية؛ استعلم عن الحالة باستخدام process_id المُعاد |
cwd | string | . | دليل العمل. يجب أن يكون موجودًا مسبقًا (مثلًا شغّل mkdir -p /home/user/workspace أولًا) |
للمهام الطويلة، عيّن detached: true، ثم استعلم عن الحالة باستخدام GET /api/v1/sandboxes/{id}/commands/{process_id}.
الملفات
يستقبل PUT /files البيانات {"path": "...", "content": "..."}، ويكون المحتوى نصًا عاديًا (حتى 2,000,000 حرف). يُرجع GET /files?path=... البيانات {"path": "...", "content": "..."}.
دورة الحياة والفوترة
- تصبح البيئة المعزولة الجديدة في حالة
runningخلال ثوانٍ قليلة، وتكون Python 3 مثبّتة مسبقًا. - الإيقاف ليس فوريًا. تتوقف الفوترة عند لحظة طلب الإيقاف، لكن استئناف البيئة فورًا قد يُرجع تعارضًا لبضع ثوانٍ. ينتظر طلب الإيقاف حتى تنتهي أرشفة البيئة قبل أن يُرجع استجابة، لذا فإن الإيقاف ثم الاستئناف آمن.
- تستمر الملفات في البقاء بعد الإيقاف والاستئناف.
- تتوقف البيئة المعزولة تلقائيًا عندما لا يغطي رصيدك الاستخدام، أو بعد 15 دقيقة من دون نشاط.
- تُحذف البيئة المعزولة المتوقفة بعد 14 يومًا. نزّل ما تحتاج إليه قبل ذلك.
- يمكن لكل حساب تشغيل ما يصل إلى 3 بيئات معزولة في الوقت نفسه.
- تُشغّل الأوامر ويجري الوصول إلى الملفات بصلاحيات مستخدم عادي داخل آلة معزولة. أنت مسؤول عن كل ما تشغّله فيها.
واجهة التجربة ونقاط النهاية بأسلوب المهام
تتوفر كل عملية أيضًا في واجهة التجربة كنقطة نهاية بأسلوب المهام: POST /api/v1/sandbox-<operation>، حيث تكون <operation> إحدى القيم create, get, run-command, command-status, write-file, read-file, stop, resume, delete. تستقبل هذه النقاط الحقول نفسها التي تستقبلها مسارات 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 | حقل مفقود أو خارج النطاق (نقاط النهاية بأسلوب المهام) |
| 502 | SANDBOX_UPSTREAM_ERROR | خطأ مؤقت في الواجهة الخلفية؛ أعد المحاولة |
حالات الاستخدام
- وكلاء البرمجة: استنسخ مستودعًا، وثبّت الحزم، وشغّل الاختبارات وأصلح الإخفاقات على آلة حقيقية.
- تنفيذ التعليمات البرمجية: شغّل تعليمات برمجية مولّدة أو غير موثوق بها بعيدًا عن بنيتك التحتية.
- مسارات معالجة الوسائط: شغّل ffmpeg أو نصوصًا مخصّصة على مخرجات نماذج الصور والفيديو والصوت من Muapi.
- تطبيقات مفتوحة المصدر مستضافة: شغّل التطبيقات في السحابة باستخدام مفتاح Muapi الخاص بالمستخدم.
راجع الصفحة التعريفية لواجهة Sandbox API للاطلاع على نظرة عامة.