رفتن به محتوا
محیط آزمایشمستنداتدریافت کلید API

Mage SDK · TypeScript

SDK ‏TypeScript برای Mage

از Node.js تصویر، ویدیو و صدا تولید کنید، با پیکربندی تایپ‌دار برای تک‌تک مدل‌های Mage. یک فراخوانی ارسال می‌کند، منتظر می‌ماند و نتیجه را برمی‌گرداند.

دریافت کلید APIراهنمای TypeScript را بخوانیدسورس در GitHub
npm install @mage-space/sdk

در یک نگاه

SDK ‏TypeScript برای Mage کلاینت رسمی و متن‌باز API ‏Mage است که با نام @mage-space/sdk منتشر شده. آن را با "npm install @mage-space/sdk" نصب کنید، MAGE_API_KEY را تنظیم کنید و mage.run را با شناسه‌ی مدل و یک پیکربندی صدا بزنید تا از هر یک از ۲۸ مدل، تصویر، ویدیو یا صدای نهایی بگیرید. روی Node.js نسخه‌ی 20.19 یا بالاتر، یا هر محیط اجرای سروری که fetch دارد، کار می‌کند و هزینه‌ی هر تولید با Gems پرداخت می‌شود.

  • 20.19+Node.js
  • 0وابستگی‌های زمان اجرا
  • 28مدل‌های تایپ‌دار
  • MITمتن‌باز

راه‌اندازی

SDK ‏TypeScript را نصب کنید و یک مدل اجرا کنید

  1. نصب بسته

    @mage-space/sdk را به پروژه‌تان اضافه کنید.

    npm install @mage-space/sdk

  2. کلید API را تنظیم کنید

    در mage.space از بخش API ← API Keys یک کلید بسازید و آن را export کنید. کلاینت، 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-v3',
});

console.log(request.result.url);

نمونه‌ها

SDK ‏TypeScript در عمل

هر نمونه از کلاینتی شروع می‌شود که 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],
});
استفاده از Character ذخیره‌شده
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 تولید را ارسال می‌کند، با backoff پیشنهادی API پولینگ می‌کند و در نهایت درخواست تکمیل‌شده را همراه با result.url برمی‌گرداند.

  • تلاش مجدد بدون پرداخت دوباره

    هر درخواست یک کلید idempotency دارد. خطاهای شبکه و سرور با backoff دوباره امتحان می‌شوند و برای درخواست تکراری هرگز دوباره هزینه کسر نمی‌شود.

  • آپلود با یک فراخوانی

    فایل‌هایی که برای data URL بزرگ‌اند با آپلود امضاشده ارسال می‌شوند و بلیت، PUT و بررسی اندازه را خود SDK انجام می‌دهد.

  • خطاهای روشن

    رد شدن درخواست‌ها در API همراه با وضعیت HTTP، کد خطا و شناسه درخواست می‌آید؛ تولیدهای ناموفق یا لغوشده و تایم‌اوت‌ها نوع خطای خودشان را دارند.

  • تایپ‌دار برای هر مدل

    MangoConfig، CherryConfig و بقیه از روی مستندات API تولید می‌شوند، پس ویرایشگر شما فیلدها را تکمیل می‌کند و گزینه‌های نامعتبر را نشان می‌دهد.

  • بدون وابستگی

    ESM بدون هیچ وابستگی زمان اجرا. از fetch داخلی Node.js استفاده می‌کند و هر فراخوانی یک AbortSignal می‌گیرد.

مرجع

SDK ‏TypeScript در یک نگاه

همان متدها همه‌ی مدل‌ها را پوشش می‌دهند؛ مدل، اولین آرگومان است.

متدکاربرد
mage.run(model, config)یک تولید را ارسال می‌کند، منتظرش می‌ماند و درخواست تکمیل‌شده را برمی‌گرداند.
mage.generate(model, config)یک تولید را ارسال می‌کند و بلافاصله درخواست را برمی‌گرداند.
mage.requests.get / cancel / waitیک درخواست را با شناسه بخوانید، متوقف کنید یا منتظرش بمانید.
mage.uploads.upload(data)فایلی تا ۱۰۰ MB آپلود می‌کند و نشانی آن را برمی‌گرداند.
mage.characters / mage.referencesفهرست، ساخت و حذف Characters و References ذخیره‌شده.
mage.account.get()موجودی Gems شما.
mage.architectures.list()فهرست زنده‌ی مدل‌ها با گزینه‌ها و قیمت‌ها.

مدل‌ها

با این مدل‌ها شروع کنید

  • تصویر · از ۳۷ Gem

    Guava API

    واقع‌گرایی‌ای که شبیه عکس واقعی است

  • تصویر · از ۱۳۵ Gem

    Mango API

    خانواده‌ی پرچم‌دار ما برای تصویر

  • تصویر · از ۵۱ Gem

    Nano Banana 2 API

    متن شفاف و خوانا، تا 4K

  • ویدیو · از ۶۱۸ Gem

    Cherry API

    خانواده‌ی پرچم‌دار ما برای ویدیو

  • ویدیو · از ۲۴۵ Gem

    Lemon API

    همه‌ی قابلیت‌های ویدیو با قیمتی مناسب‌تر

  • صدا · از ۱۹ Gem

    Seed Audio API

    صدا، موسیقی و افکت‌های صوتی از یک پرامپت

سؤالات متداول

سؤالات متداول

آیا می‌توانم از Mage TypeScript SDK در مرورگر استفاده کنم؟
نه. کلید API از Gems شما خرج می‌کند، پس آن را روی سرورهای خودتان نگه دارید. API هدرهای CORS نمی‌فرستد، بنابراین مرورگرها نمی‌توانند مستقیم آن را صدا بزنند؛ به‌جایش بک‌اندِ خودتان را صدا بزنید و بگذارید آن از SDK استفاده کند.
آیا SDK ‏TypeScript با CommonJS کار می‌کند؟
این بسته فقط ESM است. Node.js نسخه‌ی 20.19 به بعد می‌تواند آن را از CommonJS هم با require() بارگذاری کند.
آیا SDK ‏TypeScript با Next.js کار می‌کند؟
بله، در کد سمت سرور مثل route handlerها و server actionها. SDK روی fetch و Web APIهای استاندارد مثل AbortSignal ساخته شده، پس محیط‌های اجرای سروری دیگری که fetch دارند هم باید کار کنند، هرچند CI آن را روی Node.js آزمایش می‌کند.
آیا SDKهای Mage رایگان و متن‌باز هستند؟
بله. SDKها و نودهای ComfyUI با مجوز MIT در GitHub منتشر شده‌اند و نصبشان رایگان است. شما فقط برای تولیدهایی که اجرا می‌کنید، با Gems و به قیمت اعلام‌شده‌ی هر مدل، پرداخت می‌کنید.
آیا مدل‌های جدید Mage با SDK قدیمی‌تر کار می‌کنند؟
بله. شناسه‌ی مدل جدید را به‌صورت رشته بدهید تا اجرا شود؛ SDK پیکربندی را با فیلدهای مشترک همه‌ی مدل‌ها بررسی می‌کند. هر بار که مستندات API تغییر کند، یک ربات تایپ‌ها را به‌روز می‌کند، پس مدل‌های جدید با تایپ‌های خودشان در انتشار بعدی می‌رسند.
SDKها چطور از پرداخت دوباره برای یک درخواست تکراری جلوگیری می‌کنند؟
هر ارسال یک Idempotency-Key دارد. SDK برای هر فراخوانی یک کلید تازه می‌سازد و وقتی خودش همان فراخوانی را دوباره امتحان می‌کند، از همان کلید استفاده می‌کند؛ بنابراین ارسال تکراری همان درخواست اولیه را برمی‌گرداند و هزینه‌ای کسر نمی‌شود.
آیا SDKها پایدار هستند؟
آن‌ها در نسخه‌ی بتا و در 0.x هستند، پس ممکن است در یک نسخه‌ی minor تغییر کنند. خود API جداگانه نسخه‌بندی می‌شود و در v1 پایدار می‌ماند.
هزینه‌ی Mage API چقدر است؟
اشتراک یا هزینه‌ی ماهانه‌ای وجود ندارد. هر تولید با Gem و به قیمت اعلام‌شده‌ی مدلش پرداخت می‌شود و در بسته‌ی استاندارد، ۱٬۰۰۰ Gem معادل ۱ دلار است. صفحه‌ی هر مدل قیمت با تنظیمات پیش‌فرض را نشان می‌دهد و هر پاسخ مبلغ دقیق کسرشده را اعلام می‌کند. اگر تولیدی ناموفق باشد، هزینه‌اش برمی‌گردد؛ اما اگر سیاست محتوایی Mage جلوی آن را بگیرد، برنمی‌گردد. درخواستی که موجودی‌تان برای آن کافی نباشد، پیش از کسر هر مبلغی رد می‌شود.
برای استفاده از API به عضویت Mage نیاز دارم؟
نه. API فقط با Gem کار می‌کند. طرح‌های عضویت و تولید نامحدود داخل برنامه شامل درخواست‌های API نمی‌شوند، پس هر حساب Mage که Gem داشته باشد می‌تواند از آن استفاده کند.
آیا می‌توانم از خروجی‌های API استفاده تجاری کنم؟
بله. محتوایی که با Mage می‌سازید، از جمله از طریق API و سرور MCP، قابل استفادهٔ تجاری است. ذکر منبع مایهٔ قدردانی است، اما الزامی نیست.

ساختن با Mage را شروع کن

یک حساب، یک موجودی Gems، همهٔ مدل‌ها. فقط برای چیزی که تولید می‌کنی هزینه بپرداز.

دریافت کلید APIراهنمای TypeScript را بخوانید