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

Mage SDK · TypeScript

Mage TypeScript SDK

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

npm install @mage-space/sdk

لمحة سريعة

Mage TypeScript SDK هي العميل الرسمي مفتوح المصدر لواجهة Mage API، وتُنشر باسم @mage-space/sdk. ثبّتها بالأمر "npm install @mage-space/sdk"، وعيّن MAGE_API_KEY، واستدعِ mage.run مع معرّف نموذج وإعدادات لتحصل على صور أو فيديو أو صوت جاهز من أي من 37 نموذجًا. تعمل على Node.js 20.19 أو أحدث، أو على أي بيئة خادم تدعم fetch، وتُدفع كل عملية توليد بعملة Gems.

  • 20.19+Node.js
  • 0تبعيات وقت التشغيل
  • 37نماذج مضبوطة الأنواع
  • MITمفتوح المصدر

الإعداد

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

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

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

    npm install @mage-space/sdk
  2. اضبط مفتاح API

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

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

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

    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);

أمثلة

TypeScript SDK عمليًا

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

أرسل الآن وانتظر لاحقًا
import Mage from '@mage-space/sdk';

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

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

const final = await mage.requests.wait(submitted.request_id, {
  timeout: 15 * 60_000,
  onUpdate: (request) => console.log(request.status),
});
ارفع ملفًا
import { readFile } from 'node:fs/promises';
import Mage from '@mage-space/sdk';

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

const clip = await mage.uploads.upload(await readFile('clip.mp4'), {
  contentType: 'video/mp4',
});

await mage.run('cherry', {
  prompt: 'Restyle this clip as a watercolor painting',
  videos: [clip.url],
});
استخدم شخصية محفوظة
import Mage from '@mage-space/sdk';

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

await mage.characters.create({
  name: 'Ana',
  handle: 'ana',
  image: 'https://example.com/ana.png',
});

await mage.run('mango', { prompt: '@ana walking through a night market' });
معالجة الأخطاء
import Mage, { MageAPIError, MageGenerationError } from '@mage-space/sdk';

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

try {
  await mage.run('mango', { prompt: 'A lighthouse at night' });
} catch (error) {
  if (error instanceof MageAPIError && error.code === 'insufficient_gems') {
    // Top up Gems, then try again.
  } else if (error instanceof MageGenerationError) {
    console.log('No output:', error.code);
  } else {
    throw error;
  }
}

لماذا SDK

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

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

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

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

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

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

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

  • أخطاء واضحة

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

  • أنواع مخصصة لكل نموذج

    يتم توليد MangoConfig وCherryConfig وبقية الأنواع من مرجع API، فيُكمل محررك الحقول تلقائيًا وينبهك إلى الخيارات غير الصالحة.

  • بلا أي تبعيات

    ESM دون أي تبعيات وقت تشغيل. يستخدم fetch المدمجة في Node.js، ويقبل كل استدعاء AbortSignal.

المرجع

TypeScript 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()كتالوج النماذج المباشر مع الخيارات والأسعار.

النماذج

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

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

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

هل يمكنني استخدام Mage TypeScript SDK في المتصفح؟
لا. مفتاح API يستهلك رصيد Gems لديك، لذا أبقِه على خوادمك. لا ترسل API ترويسات CORS، ولذلك لا تستطيع المتصفحات استدعاءها مباشرة؛ استدعِ الواجهة الخلفية الخاصة بك ودعها تستخدم SDK.
هل يعمل TypeScript SDK مع CommonJS؟
الحزمة تدعم ESM فقط. ويمكن في Node.js 20.19 والإصدارات الأحدث استدعاؤها من CommonJS عبر require() أيضًا.
هل يعمل TypeScript SDK مع Next.js؟
نعم، في شيفرة الخادم مثل معالجات المسارات (route handlers) وإجراءات الخادم (server actions). بُني SDK على fetch وواجهات الويب القياسية مثل AbortSignal، لذا يُفترض أن تعمل بيئات الخادم الأخرى التي تدعم fetch أيضًا، مع أن اختبارات CI تجري على Node.js.
هل حزم 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المجتمع