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

Mage SDK · پایتون

SDK پایتون Mage

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

دریافت کلید APIخواندن راهنمای پایتونسورس در GitHub
pip install mage-space

در یک نگاه

SDK پایتون Mage کلاینت رسمی و متن‌باز Mage API است که با نام mage-space منتشر شده. آن را با «pip install mage-space» نصب کنید، MAGE_API_KEY را تنظیم کنید و mage.run را با شناسه مدل و یک پیکربندی صدا بزنید تا از هر یک از 28 مدل، تصویر، ویدیو یا صدای نهایی بگیرید. روی Python 3.10 یا جدیدتر اجرا می‌شود و هزینه هر تولید با Gem پرداخت می‌شود.

  • 3.10+پایتون
  • httpxکلاینت HTTP
  • 28مدل‌های تایپ‌دار
  • MITمتن‌باز

راه‌اندازی

SDK پایتون را نصب کنید و یک مدل را اجرا کنید

  1. نصب بسته

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

    pip install mage-space

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

    در mage.space از بخش API ← API Keys یک کلید بسازید و آن را export کنید. کلاینت، MAGE_API_KEY را می‌خواند.

    export MAGE_API_KEY="mage_sk_..."

  3. تولید

    run را با شناسه‌ی مدل و پیکربندی‌اش صدا بزنید. منتظر نتیجه می‌ماند و آن را برمی‌گرداند؛ خروجی در result.url است.

    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 پایتون در عمل

هر نمونه از کلاینتی شروع می‌شود که MAGE_API_KEY را می‌خواند.

حالا ارسال، بعداً انتظار
from mage_space import Mage

mage = Mage()  # reads MAGE_API_KEY

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

final = mage.requests.wait(
    submitted["request_id"],
    timeout=900,
    on_update=lambda request: print(request["status"]),
)
آپلود فایل
from mage_space import Mage

mage = Mage()  # reads MAGE_API_KEY

clip = mage.uploads.upload("clip.mp4")  # a path, bytes, or a binary file

mage.run("cherry", {
    "prompt": "Restyle this clip as a watercolor painting",
    "videos": [clip["url"]],
})
استفاده از Character ذخیره‌شده
from mage_space import Mage

mage = Mage()  # reads MAGE_API_KEY

mage.characters.create(
    name="Ana",
    handle="ana",
    image="https://example.com/ana.png",
)

mage.run("mango", {"prompt": "@ana walking through a night market"})
مدیریت خطاها
from mage_space import Mage, MageAPIError, MageGenerationError

mage = Mage()  # reads MAGE_API_KEY

try:
    mage.run("mango", {"prompt": "A lighthouse at night"})
except MageAPIError as error:
    if error.code == "insufficient_gems":
        print("Gems needed:", error.body["error"]["gems_required"])
    else:
        raise
except MageGenerationError as error:
    print("No output:", error.code)

چرا SDK

کارهایی که SDK برایتان انجام می‌دهد

  • یک فراخوانی، رسانه آماده

    run تولید را ارسال می‌کند، با backoff پیشنهادی API پولینگ می‌کند و در نهایت درخواست تکمیل‌شده را همراه با result.url برمی‌گرداند.

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

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

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

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

  • خطاهای روشن

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

  • Sync و asyncio

    Mage و AsyncMage همه متدها را مشترک دارند. کلاینت async برای وب‌سرورها، نوت‌بوک‌ها و پایپ‌لاین‌هایی که چند تولید را هم‌زمان اجرا می‌کنند مناسب است.

  • پیکربندی تایپ‌دار

    هر مدل یک TypedDict دارد، مثل MangoConfig، که از مرجع API تولید شده است. پیکربندی را با آن annotate کنید تا type checker فیلدها را بررسی کند.

مرجع

SDK پایتون در یک نگاه

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

متدکاربرد
mage.run(model, config)یک تولید را ارسال می‌کند، منتظرش می‌ماند و درخواست تکمیل‌شده را برمی‌گرداند.
mage.generate(model, config)یک تولید را ارسال می‌کند و بلافاصله درخواست را برمی‌گرداند.
mage.requests.get / cancel / waitیک درخواست را با شناسه بخوانید، متوقف کنید یا منتظرش بمانید.
mage.uploads.upload(data)یک مسیر، بایت یا فایل تا 100 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

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

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

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

آیا SDK پایتون از asyncio پشتیبانی می‌کند؟
بله. AsyncMage همان متدهای Mage را دارد، با await صدا زده می‌شوند، و به‌صورت async context manager هم کار می‌کند.
SDK از کدام نسخه‌های پایتون پشتیبانی می‌کند؟
Python 3.10 و جدیدتر. تنها وابستگی‌های آن httpx و typing-extensions هستند.
آیا می‌توانم SDK پایتون را در نوت‌بوک یا پایپ‌لاین داده استفاده کنم؟
بله. در اسکریپت‌ها و نوت‌بوک‌ها از Mage استفاده کنید، یا برای اجرای هم‌زمان چند تولید از AsyncMage با asyncio. هر حساب می‌تواند تا 20 تولید هم‌زمان در حال اجرا داشته باشد.
آیا 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خواندن راهنمای پایتون