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