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 وشغّل نموذجًا
ثبّت الحزمة
أضف mage-space إلى مشروعك.
pip install mage-spaceاضبط مفتاح API
أنشئ مفتاحًا من API ← API Keys على mage.space ثم صدّره. يقرأ العميل المتغير MAGE_API_KEY.
export MAGE_API_KEY="mage_sk_..."ابدأ التوليد
استدعِ 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() | كتالوج النماذج المباشر مع الخيارات والأسعار. |
النماذج
ابدأ بهذه النماذج
واجهة Guava API
واقعية فائقة تبدو كصورة فوتوغرافية
واجهة Mango API
عائلة الصور الرائدة لدينا
واجهة Nano Banana 2 API
نصوص واضحة ومقروءة حتى 4K
واجهة Cherry API
عائلة الفيديو الرائدة لدينا
واجهة Lemon API
كل ميزات الفيديو بسعر أنسب
واجهة Seed Audio API
أصوات وموسيقى ومؤثرات صوتية من أمر واحد
الأسئلة الشائعة
الأسئلة الشائعة
هل تدعم Python SDK مكتبة asyncio؟
ما إصدارات Python التي تدعمها الحزمة؟
هل يمكنني استخدام Python SDK في دفتر ملاحظات أو خط معالجة بيانات؟
هل حزم Mage SDK مجانية ومفتوحة المصدر؟
هل تعمل نماذج Mage الجديدة مع إصدار أقدم من SDK؟
كيف تتجنب حزم SDK الدفع مرتين عند إعادة محاولة طلب؟
هل حزم SDK مستقرة؟
كم تبلغ تكلفة Mage API؟
هل أحتاج إلى عضوية في Mage لاستخدام API؟
هل يمكنني استخدام مخرجات API تجاريًا؟
ابدأ البناء مع Mage
حساب واحد، ورصيد Gems واحد، وكل النماذج. ادفع فقط مقابل ما تنشئه.