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

API مجیک · SDKها

SDKهای رسمی برای API مجیک

کلاینت‌های تایپ‌دار برای TypeScript و Python، و نودهای Mage برای ComfyUI. همه مدل‌های تصویر، ویدیو و صدا در چند خط کد.

دریافت کلید APIمطالعه مستندات SDK

در یک نگاه

Mage برای API خود SDKهای متن‌باز منتشر می‌کند: ‏@mage-space/sdk در npm برای TypeScript و JavaScript، ‏mage-space در PyPI برای Python، و بسته نود comfyui-mage برای ComfyUI. هر کدام REST API را با پیکربندی تایپ‌دار برای هر ۲۸ مدل، پولینگ خودکار، تلاش مجدد idempotent و آپلود در بر می‌گیرند.

  • 3SDKها و یکپارچه‌سازی‌ها
  • 28مدل‌های تایپ‌دار
  • MITمتن‌باز
  • $0برای نصب

مال خودتان را انتخاب کنید

SDKها و یکپارچه‌سازی‌ها

  • npm install @mage-space/sdk

    SDK برای TypeScript

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

  • pip install mage-space

    SDK برای Python

    با کلاینت‌های sync و asyncio و پیکربندی تایپ‌دار برای هر مدل Mage، از Python تصویر، ویدیو و صدا بسازید.

  • comfy node install comfyui-mage

    Mage برای ComfyUI

    Mango، Cherry، Seed Audio و همه مدل‌های دیگر Mage به‌صورت نودهای ComfyUI. بدون GPU، بدون دانلود مدل.

شروع سریع

اولین تولید شما با SDK

بسته را نصب کنید، MAGE_API_KEY را export کنید و یک مدل را اجرا کنید.

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 تولید را ارسال می‌کند، با backoff پیشنهادی API پولینگ می‌کند و در نهایت درخواست تکمیل‌شده را همراه با result.url برمی‌گرداند.

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

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

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

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

  • خطاهای روشن

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

بسته‌ها

از کجا بگیریم

SDKبستهنصبمنبع
SDK برای TypeScript@mage-space/sdknpm install @mage-space/sdkGitHub
SDK برای Pythonmage-spacepip install mage-spaceGitHub
Mage برای ComfyUIcomfyui-magecomfy node install comfyui-mageGitHub

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

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

آیا 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مطالعه مستندات SDK