Mage API · حزم SDK

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

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

احصل على مفتاح APIاقرأ وثائق SDK

لمحة سريعة

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

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

حزم 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-v3',
});

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-v3",
})

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، لذا يمكن لأي حساب Mage يحتوي على Gems استخدامها.

هل يمكنني استخدام مخرجات API تجاريًا؟

نعم. يمكنك استخدام المحتوى الذي تنشئه باستخدام Mage، بما في ذلك عبر واجهة API وخادم MCP، لأغراض تجارية. نقدّر ذكر المصدر لكنه ليس إلزاميًا.

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

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

احصل على مفتاح APIاقرأ وثائق SDK

ذات صلة