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

Mage API · حزم SDK

حزم SDK الرسمية لواجهة Mage API

عملاء مضبوطو الأنواع للغتي TypeScript وPython، وعُقد Mage لـ ComfyUI. كل نماذج الصور والفيديو والصوت في بضعة أسطر من الكود.

لمحة سريعة

ينشر Mage حزم SDK مفتوحة المصدر لواجهته البرمجية: ‏@mage-space/sdk على npm للغتي TypeScript وJavaScript، وmage-space على PyPI للغة Python، وحزمة العقد comfyui-mage لـ ComfyUI. تغلّف كل منها واجهة REST API بإعدادات مكتوبة الأنواع لجميع النماذج الـ 37، مع استعلام تلقائي وإعادة محاولة آمنة ورفع للملفات.

  • 3حزم SDK والتكاملات
  • 37نماذج مضبوطة الأنواع
  • MITمفتوح المصدر
  • $0للتثبيت

اختر ما يناسبك

حزم SDK والتكاملات

  • npm install @mage-space/sdk

    TypeScript SDK

    ولّد الصور والفيديو والصوت من Node.js بإعدادات مضبوطة الأنواع لكل نموذج من نماذج Mage. استدعاء واحد يرسل الطلب وينتظر ويعيد النتيجة.

  • pip install mage-space

    Python SDK

    ولّد الصور والفيديو والصوت من Python بعملاء متزامنين وغير متزامنين (asyncio) وإعدادات مضبوطة الأنواع لكل نموذج من نماذج Mage.

  • comfy node install comfyui-mage

    Mage لـ ComfyUI

    Mango وCherry وSeed Audio وكل نماذج Mage الأخرى كعُقد في ComfyUI. بلا GPU وبلا تنزيل نماذج.

بداية سريعة

أول عملية توليد لك باستخدام SDK

ثبّت الحزمة، وصدّر MAGE_API_KEY، ثم شغّل أي نموذج.

TypeScript
// npm install @mage-space/sdk
import Mage from '@mage-space/sdk';

const mage = new Mage(); // reads MAGE_API_KEY

const request = await mage.run('mango', {
  prompt: 'Editorial portrait in soft daylight, 35mm film look',
  aspect_ratio: '4:5',
  model_id: 'mango-v4',
});

console.log(request.result.url);
Python
# pip install mage-space
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"])

مدمج

ما تتولاه كل حزمة SDK نيابةً عنك

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

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

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

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

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

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

  • أخطاء واضحة

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

الحزم

من أين تحصل عليها

SDKالحزمةالتثبيتالمصدر
TypeScript SDK@mage-space/sdknpm install @mage-space/sdkGitHub
Python SDKmage-spacepip install mage-spaceGitHub
Mage لـ ComfyUIcomfyui-magecomfy node install comfyui-mageGitHub

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

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

هل حزم 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المجتمع