واجهة API للبيئات المعزولة

تتيح واجهة API للبيئات المعزولة تشغيل تعليماتك البرمجية أو وكيل الذكاء الاصطناعي على آلة Linux سحابية معزولة عند الطلب. أنشئ بيئة معزولة، وشغّل أوامر shell، واقرأ الملفات واكتبها، ثم أوقف البيئة أو احذفها؛ كل ذلك عبر REST باستخدام x-api-key ورصيد الاعتمادات نفسه الذي تستخدمه لتوليد الصور والفيديو والصوت.

هذه ليست مفاتيح Sandbox (الاختبار). تُسمّى مفاتيح API التي أُنشئت مع is_test: true «مفاتيح sandbox»، وتُرجع نتائج وهمية لنقاط نهاية التوليد (راجع مرجع API). أما واجهة API للبيئات المعزولة الموضّحة هنا فتنشئ آلات سحابية حقيقية. يمكن لمفتاح اختبار استدعاء نقاط نهاية واجهة API هذه، لكنه يُرجع نتيجة وهمية ولا ينشئ أي شيء.

الأحجام والأسعار

مرّر profile عند إنشاء بيئة معزولة. تُحتسب الفوترة بالثانية أثناء تشغيلها، وتُخصم من رصيد اعتماداتك.

الملف التعريفيالمواردالسعر
small2 vCPU، و4 GB RAM$0.036 / الساعة
default4 vCPU، و8 GB RAM$0.072 / الساعة
large8 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

الحقلالنوعالقيمة الافتراضيةملاحظات
commandstringمطلوبأمر shell، حتى 20,000 حرف
timeout_secondsinteger30من 1 إلى 600
detachedbooleanfalseالتشغيل في الخلفية؛ استعلم عن الحالة باستخدام process_id المُعاد
cwdstring.دليل العمل. يجب أن يكون موجودًا مسبقًا (مثلًا شغّل 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": "..."}}.

الحالةالرمزالمعنى
400INVALID_PROFILEقيمة profile غير معروفة
402INSUFFICIENT_CREDITSالرصيد أقل من الحد الأدنى البالغ $1 للإنشاء أو الاستئناف
422INVALID_INPUTحقل مفقود أو خارج النطاق (نقاط النهاية بأسلوب المهام)
502SANDBOX_UPSTREAM_ERRORخطأ مؤقت في الواجهة الخلفية؛ أعد المحاولة

حالات الاستخدام

  • وكلاء البرمجة: استنسخ مستودعًا، وثبّت الحزم، وشغّل الاختبارات وأصلح الإخفاقات على آلة حقيقية.
  • تنفيذ التعليمات البرمجية: شغّل تعليمات برمجية مولّدة أو غير موثوق بها بعيدًا عن بنيتك التحتية.
  • مسارات معالجة الوسائط: شغّل ffmpeg أو نصوصًا مخصّصة على مخرجات نماذج الصور والفيديو والصوت من Muapi.
  • تطبيقات مفتوحة المصدر مستضافة: شغّل التطبيقات في السحابة باستخدام مفتاح Muapi الخاص بالمستخدم.

راجع الصفحة التعريفية لواجهة Sandbox API للاطلاع على نظرة عامة.