انتقل إلى المحتوى

Mage SDK · Python

حزمة Mage Python SDK

أنشئ الصور والفيديو والصوت من Python عبر عملاء sync وasyncio، مع إعدادات مُنمَّطة لكل نموذج من نماذج Mage.

pip install mage-space

لمحة سريعة

Mage Python SDK هي العميل الرسمي مفتوح المصدر لواجهة Mage API، وتُنشر باسم mage-space. ثبّتها بالأمر "pip install mage-space"، وعيّن MAGE_API_KEY، واستدعِ mage.run مع معرّف نموذج وإعدادات لتحصل على صور أو فيديو أو صوت جاهز من أي من 37 نموذجًا. تعمل على Python 3.10 أو أحدث، وتُدفع كل عملية توليد بعملة Gems.

  • 3.10+Python
  • httpxعميل HTTP
  • 37نماذج مضبوطة الأنواع
  • MITمفتوح المصدر

الإعداد

ثبّت Python SDK وشغّل نموذجًا

  1. ثبّت الحزمة

    أضف mage-space إلى مشروعك.

    pip install mage-space
  2. اضبط مفتاح API

    أنشئ مفتاحًا من API ← API Keys على mage.space ثم صدّره. يقرأ العميل المتغير MAGE_API_KEY.

    export MAGE_API_KEY="mage_sk_..."
  3. ابدأ التوليد

    استدعِ run مع معرّف النموذج وإعداداته. ينتظر النتيجة ويعيدها، وتجد المخرجات في result.url.

    from mage_space import Mage
    
    mage = Mage()  # reads MAGE_API_KEY
    
    request = mage.run("mango", {
        "prompt": "Editorial portrait in soft daylight, 35mm film look",
        "aspect_ratio": "4:5",
        "model_id": "mango-v4",
    })
    
    print(request["result"]["url"])

أمثلة

Python SDK عمليًا

يبدأ كل مثال من عميل يقرأ MAGE_API_KEY.

أرسل الآن وانتظر لاحقًا
from mage_space import Mage

mage = Mage()  # reads MAGE_API_KEY

submitted = mage.generate("cherry", {
    "prompt": "Waves rolling onto a black sand beach at sunset",
    "resolution": "720p",
    "duration": "5",
})

final = mage.requests.wait(
    submitted["request_id"],
    timeout=900,
    on_update=lambda request: print(request["status"]),
)
ارفع ملفًا
from mage_space import Mage

mage = Mage()  # reads MAGE_API_KEY

clip = mage.uploads.upload("clip.mp4")  # a path, bytes, or a binary file

mage.run("cherry", {
    "prompt": "Restyle this clip as a watercolor painting",
    "videos": [clip["url"]],
})
استخدم شخصية محفوظة
from mage_space import Mage

mage = Mage()  # reads MAGE_API_KEY

mage.characters.create(
    name="Ana",
    handle="ana",
    image="https://example.com/ana.png",
)

mage.run("mango", {"prompt": "@ana walking through a night market"})
معالجة الأخطاء
from mage_space import Mage, MageAPIError, MageGenerationError

mage = Mage()  # reads MAGE_API_KEY

try:
    mage.run("mango", {"prompt": "A lighthouse at night"})
except MageAPIError as error:
    if error.code == "insufficient_gems":
        print("Gems needed:", error.body["error"]["gems_required"])
    else:
        raise
except MageGenerationError as error:
    print("No output:", error.code)

لماذا SDK

ما الذي يتولاه SDK عنك

  • استدعاء واحد، ووسائط جاهزة

    يرسل run طلب التوليد، ويستعلم عن حالته بفترات التراجع التي توصي بها الواجهة، ثم يعيد الطلب المكتمل مع result.url.

  • إعادة محاولات بلا دفع مزدوج

    يحمل كل طلب مفتاح تكرار آمنًا (idempotency key). تُعاد المحاولة عند أخطاء الشبكة والخادم مع فترات تراجع، ولا يُحتسب الطلب المعاد مرة أخرى.

  • رفع الملفات باستدعاء واحد

    الملفات الأكبر من أن تُرسل كـ data URL تُرفع عبر رابط رفع موقّع، ونتولى عنك التذكرة وطلب PUT والتحقق من الحجم.

  • أخطاء واضحة

    تتضمن حالات رفض الواجهة رمز حالة HTTP ورمز الخطأ ومعرّف الطلب، وللتوليد الفاشل أو الملغى وانتهاء المهلة أنواع أخطاء خاصة بها.

  • sync وasyncio

    يشترك Mage وAsyncMage في جميع الدوال. ويناسب العميل غير المتزامن خوادم الويب والدفاتر وخطوط المعالجة التي تشغّل عدة عمليات إنشاء في وقت واحد.

  • إعدادات مُنمَّطة

    لكل نموذج TypedDict، مثل MangoConfig، يُولَّد من مرجع الـ API. أضف هذا النوع إلى إعداداتك ليتحقق مدقّق الأنواع من الحقول.

المرجع

Python SDK في لمحة

الدوال نفسها تغطي كل النماذج؛ والنموذج هو المعامل الأول.

الدالةوظيفتها
mage.run(model, config)يرسل عملية توليد وينتظرها ثم يعيد الطلب المكتمل.
mage.generate(model, config)يرسل عملية توليد ويعيد الطلب فورًا.
mage.requests.get / cancel / waitيقرأ طلبًا أو يوقفه أو ينتظره باستخدام المعرّف.
mage.uploads.upload(data)ارفع مسارًا أو بايتات أو ملفًا بحجم يصل إلى 100 MB واحصل على رابطه.
mage.characters / mage.referencesيعرض الشخصيات والمراجع المحفوظة وينشئها ويحذفها.
mage.account.get()رصيدك من Gems.
mage.architectures.list()كتالوج النماذج المباشر مع الخيارات والأسعار.

النماذج

ابدأ بهذه النماذج

الأسئلة الشائعة

الأسئلة الشائعة

هل تدعم Python SDK مكتبة asyncio؟
نعم. يضم AsyncMage الدوال نفسها الموجودة في Mage لكن بانتظارها بـ await، ويعمل كمدير سياق غير متزامن.
ما إصدارات Python التي تدعمها الحزمة؟
Python 3.10 وما بعده. ولا تعتمد إلا على httpx وtyping-extensions.
هل يمكنني استخدام Python SDK في دفتر ملاحظات أو خط معالجة بيانات؟
نعم. استخدم Mage في السكربتات والدفاتر، أو AsyncMage مع asyncio لتشغيل عدة عمليات إنشاء في وقت واحد. يتيح الحساب تشغيل ما يصل إلى 20 عملية إنشاء متزامنة.
هل حزم Mage SDK مجانية ومفتوحة المصدر؟
نعم. حزم SDK وعُقد ComfyUI مرخّصة بترخيص MIT على GitHub، وتثبيتها مجاني. تدفع فقط مقابل عمليات التوليد التي تشغّلها، بعملة Gems وبالسعر المعروض لكل نموذج.
هل تعمل نماذج Mage الجديدة مع إصدار أقدم من SDK؟
نعم. مرّر معرّف النموذج الجديد كنص وسيعمل؛ إذ يتحقق SDK من إعداداته بناءً على الحقول التي تشترك فيها كل النماذج. يقوم بوت بتحديث الأنواع كلما تغيّر مرجع API، لذا تصل النماذج الجديدة مع أنواعها الخاصة في الإصدار التالي.
كيف تتجنب حزم SDK الدفع مرتين عند إعادة محاولة طلب؟
يحمل كل طلب إرسال مفتاح Idempotency-Key. ينشئ SDK مفتاحًا جديدًا لكل استدعاء ويعيد استخدامه عندما يعيد محاولة ذلك الاستدعاء بنفسه، فيُرجع الإرسال المُعاد الطلب الأصلي دون أي رسوم.
هل حزم SDK مستقرة؟
هي حاليًا في مرحلة تجريبية (beta) بالإصدار 0.x، لذا قد يغيّرها إصدار فرعي. أما API نفسها فيتم إصدارها بشكل منفصل وتبقى مستقرة ضمن v1.
كم تبلغ تكلفة Mage API؟
لا يوجد اشتراك ولا رسوم شهرية. تُدفع كل عملية إنشاء بـ Gems وفق السعر المعلن لنموذجها، وكل 1,000 Gems تكلّف 1$ في الباقة القياسية. تعرض صفحة كل نموذج سعره بالإعدادات الافتراضية، ويذكر كل رد المبلغ المحتسب بدقة. إذا فشلت عملية الإنشاء يُسترد المبلغ، أما إذا حظرتها سياسة المحتوى في Mage فلا يُسترد. أما الطلب الذي لا يغطيه رصيدك فيُرفض قبل خصم أي مبلغ.
هل أحتاج إلى عضوية في Mage لاستخدام API؟
لا. تعمل واجهة API بالـ Gems فقط. لا تنطبق خطط العضوية وميزة التوليد غير المحدود داخل التطبيق على طلبات API. يجب أن يُجرى للحساب أولًا دفع واحد ناجح، سواء لحزمة Gems أو لأي خطة. أما Gems الخاصة بمكافأة التسجيل فتعمل في تطبيق Mage فقط.
هل يمكنني استخدام مخرجات API تجاريًا؟
نعم. يمكنك استخدام المحتوى الذي تنشئه باستخدام Mage، بما في ذلك عبر واجهة API وخادم MCP، لأغراض تجارية. نقدّر ذكر المصدر لكنه ليس إلزاميًا.

ابدأ البناء مع Mage

حساب واحد، ورصيد Gems واحد، وكل النماذج. ادفع فقط مقابل ما تنشئه.

Charactersالمجتمع