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

Mage API · ساخته‌شده برای ایده بعدی شما

یک API. امکانات بی‌پایان.

بهترین‌های Mage را به محصول و دستیار هوش مصنوعی خود بیاورید. با یک کلید API یا یک اتصال MCP، تصویر، ویدیو و صدا تولید کنید.

دریافت کلید APIاتصال دستیار خودمطالعه مستندات API
https://api.mage.space/v1

در یک نگاه

Mage برای توسعه‌دهندگان یک REST API در https://api.mage.space/v1 و یک سرور MCP راه‌دور در https://mcp.mage.space/mcp ارائه می‌دهد. هر دو با یک حساب، همان ۲۸ مدل تصویر، ویدیو و صدا را اجرا می‌کنند، از جمله مدل‌های اختصاصی Mage یعنی Mango 3 و Cherry 2 Pro، و هزینه هر تولید بدون اشتراک با Gems پرداخت می‌شود.

  • 28مدل‌ها
  • 3نوع رسانه
  • 16ابزارهای MCP
  • $0هزینه ماهانه

راه‌های شروع

از کد، دستیار هوش مصنوعی یا ComfyUI فراخوانی کنید

  • REST API

    API Mage

    با یک کلید، تولیدها را از کد خودتان ارسال کنید. درخواست‌های ناهمگام، تلاش مجدد ایمن (idempotent)، آپلود تا ۱۰۰ MB و ۲۰ تولید هم‌زمان.

  • SDKها

    SDKهای TypeScript و Python

    کلاینت‌های رسمی و تایپ‌شده که با چند خط کد درخواست را ارسال می‌کنند، منتظر نتیجه می‌مانند، با اطمینان دوباره تلاش می‌کنند و فایل آپلود می‌کنند.

  • سرور MCP

    سرور MCP در Mage

    Claude، ChatGPT، Claude Code، Grok یا Cursor را با ورود به حساب وصل کنید و تصویر، ویدیو و صدا را به زبان ساده بخواهید.

  • ComfyUI

    Mage برای ComfyUI

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

بر اساس نوع رسانه

APIهای تولید

شروع سریع

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

در API → API Keys یک کلید بسازید، آن را با نام MAGE_API_KEY اکسپورت کنید و یکی از نمونه‌های زیر را اجرا کنید.

cURL
STATUS_URL=$(curl --request POST 'https://api.mage.space/v1/mango/generate' \
  --header "Authorization: Bearer $MAGE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "Editorial portrait in soft daylight, 35mm film look",
  "aspect_ratio": "4:5",
  "model_id": "mango-v3"
}' | jq -r '.status_url')

# Repeat until status is "completed"; result.url is the file
curl "$STATUS_URL" --header "Authorization: Bearer $MAGE_API_KEY"
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"])

نحوه کار

از کلید API تا رسانه آماده در سه فراخوانی

همه مدل‌ها یک روش احراز هویت، یک چرخه عمر درخواست ناهمگام و نام فیلدهای یکسان دارند.

  1. ساخت کلید API

    وارد Mage شوید، به API → API Keys بروید و یک کلید بسازید. کلید با mage_sk_ شروع می‌شود و فقط یک بار نمایش داده می‌شود. هر حساب می‌تواند ۱۰ کلید فعال داشته باشد.

  2. ارسال یک درخواست تولید

    یک بدنه JSON را با POST به https://api.mage.space/v1/{model}/generate بفرستید و هدر Authorization: Bearer را اضافه کنید. پاسخ بلافاصله همراه با request_id، status و status_url برمی‌گردد. هدر Idempotency-Key را هم بفرستید تا تلاش مجدد هرگز دو بار هزینه نداشته باشد.

  3. بررسی وضعیت و دانلود

    status_url را مرتب بررسی کنید تا status به completed، failed یا cancelled برسد. درخواست تکمیل‌شده شامل result.url با فایل تصویر، ویدیو یا صدا است که ۳۰ روز نگهداری می‌شود.

MCP

Mage در دستیار هوش مصنوعی شما

  • Mage در Claude

    در Claude روی وب، اپ دسکتاپ، اپ‌های موبایل و Cowork تصویر، ویدیو و صدا تولید کنید.

  • Mage در ChatGPT

    در ChatGPT به‌عنوان یک اپ MCP شخصی، تصویر، ویدیو و صدا تولید کنید.

  • Mage در Claude Code

    در Claude Code، هم در ترمینال و هم در ویرایشگر، تصویر، ویدیو و صدا بسازید.

  • Mage در Grok

    با یک کانکتور سفارشی در Grok تصویر، ویدیو و صدا بسازید.

  • Mage در Cursor

    در حالت Agent در Cursor تصویر، ویدیو و صدا بسازید.

مدل‌ها

مدل‌های منتخب

  • تصویر · از ۴۰ Gem

    Flux 2 API

    پرامپت‌های بلند و ویرایش با چند رفرنس

  • تصویر · از ۹ Gem

    GPT Image 2 API

    پرامپت‌های دقیق و متن خوانا

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

    Guava API

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

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

    Mango API

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

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

    Nano Banana 2 API

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

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

    Cherry API

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

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

    Lemon API

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

  • ویدیو · از ۳۳۸ Gem

    Plum API

    صدا برای هر کلیپ، تا 2K

  • صدا · از ۱۹ Gem

    Seed Audio API

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

ساخته‌شده برای محیط عملیاتی

هر درخواست Mage API چه امکاناتی دارد

  • یک کلید، همه‌ی مدل‌ها

    ۲۸ مدل تصویر، ویدیو و صدا پشت یک REST API و یک موجودی Gem. فقط با تغییر مسیر URL مدل را عوض کنید.

  • پرداخت به‌ازای هر تولید

    بدون اشتراک و بدون حداقل هزینه. شما Gem می‌خرید و برای هر درخواست قیمت اعلام‌شده کسر می‌شود. اگر تولیدی ناموفق باشد، هزینه‌اش برمی‌گردد، مگر اینکه سیاست محتوایی Mage جلوی آن را گرفته باشد.

  • تلاش مجدد ایمن

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

  • شخصیت‌های یکدست

    یک بار شخصیت یا رفرنس را ذخیره کنید، بعد در هر پرامپت @handle را بنویسید تا با هر مدلی که از آن پشتیبانی می‌کند استفاده شود.

  • ورودی‌های حجیم

    ورودی‌های تصویر، ویدیو و صدا را به‌صورت URL یا data URL بفرستید، یا فایل‌هایی تا ۱۰۰ مگابایت را با آپلود امضاشده بارگذاری کنید.

  • ۲۰ تولید هم‌زمان

    هر حساب می‌تواند هم‌زمان ۲۰ تولید را اجرا کند و این سقف را می‌شود متناسب با نیاز شما افزایش داد. برای درخواست‌های ردشده هیچ هزینه‌ای کسر نمی‌شود.

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

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

Mage API چیست؟
Mage API یک REST API در نشانی https://api.mage.space/v1 است که با آن می‌توانید از داخل کد خودتان با ۲۸ مدل، تصویر، ویدیو و صدا بسازید. درخواست‌ها ناهمزمان هستند و پرداخت هر تولید با Gem انجام می‌شود.
سرور Mage MCP چیست؟
یک سرور راه‌دور Model Context Protocol در نشانی https://mcp.mage.space/mcp که به دستیارهای هوش مصنوعی اجازه می‌دهد در حساب Mage شما تصویر، ویدیو و صدا بسازند. این سرور ۱۶ ابزار در اختیار دستیار می‌گذارد تا مدل انتخاب کند، قیمت را اعلام کند، تولید کند، منتظر نتیجه بماند و از شخصیت‌ها، رفرنس‌ها و تاریخچه‌ی ذخیره‌شده‌ی شما استفاده کند.
برای استفاده از سرور MCP به کلید API نیاز دارم؟
نه. Claude، ChatGPT، Grok، Cursor و Claude Code با ورود به Mage از طریق OAuth متصل می‌شوند. کلید API اختیاری است و برای محیط‌های بدون رابط کاربری مثل CI به کار می‌رود.
هزینه‌ی Mage API چقدر است؟
اشتراک یا هزینه‌ی ماهانه‌ای وجود ندارد. هر تولید با Gem و به قیمت اعلام‌شده‌ی مدلش پرداخت می‌شود و در بسته‌ی استاندارد، ۱٬۰۰۰ Gem معادل ۱ دلار است. صفحه‌ی هر مدل قیمت با تنظیمات پیش‌فرض را نشان می‌دهد و هر پاسخ مبلغ دقیق کسرشده را اعلام می‌کند. اگر تولیدی ناموفق باشد، هزینه‌اش برمی‌گردد؛ اما اگر سیاست محتوایی Mage جلوی آن را بگیرد، برنمی‌گردد. درخواستی که موجودی‌تان برای آن کافی نباشد، پیش از کسر هر مبلغی رد می‌شود.
برای استفاده از API به عضویت Mage نیاز دارم؟
نه. API فقط با Gem کار می‌کند. طرح‌های عضویت و تولید نامحدود داخل برنامه شامل درخواست‌های API نمی‌شوند، پس هر حساب Mage که Gem داشته باشد می‌تواند از آن استفاده کند.
آیا می‌توانم از خروجی‌های API استفاده تجاری کنم؟
بله. محتوایی که با Mage می‌سازید، از جمله از طریق API و سرور MCP، قابل استفادهٔ تجاری است. ذکر منبع مایهٔ قدردانی است، اما الزامی نیست.
محدودیت نرخ درخواست چقدر است؟
هر حساب می‌تواند هم‌زمان ۲۰ تولید در صف یا در حال اجرا داشته باشد. ارسال بیش از این مقدار با خطای 429 رد می‌شود و هزینه‌ای ندارد. برای افزایش این سقف متناسب با نیازتان به [email protected] ایمیل بزنید.
آیا ایجنت هوش مصنوعی من می‌تواند از API مجموعهٔ Mage استفاده کند؟
بله. ایجنت‌ها می‌توانند با یک کلید، REST API را فراخوانی کنند یا به سرور MCP مجموعهٔ Mage وصل شوند که شانزده ابزار آماده برای Claude، ChatGPT، Claude Code، Grok و Cursor فراهم می‌کند تا مدل انتخاب کنند، قیمت را استعلام کنند، تولید کنند و نتیجه را دریافت کنند. جزئیات: سرور MCP.
آیا برای Mage API یک SDK وجود دارد؟
بله. بستهٔ رسمی @mage-space/sdk روی npm و mage-space روی PyPI متن‌باز هستند و برای همهٔ مدل‌ها تایپ‌شده‌اند. این بسته‌ها درخواست را ارسال می‌کنند، منتظر نتیجه می‌مانند، با اطمینان دوباره تلاش می‌کنند و فایل‌ها را برایتان آپلود می‌کنند. کاربران ComfyUI می‌توانند بستهٔ نودهای comfyui-mage را نصب کنند. جزئیات: SDKهای Mage.
من از قبل از API تولید دیگری استفاده می‌کنم. چه چیزی را باید تغییر بدهم؟
کلاینتتان را به https://api.mage.space/v1 وصل کنید، کلید Mage را به‌صورت Bearer token بفرستید و فیلدهایتان را با صفحهٔ مدل تطبیق دهید: prompt، aspect_ratio، resolution، duration و model_id در همهٔ مدل‌های Mage به یک شکل کار می‌کنند. درخواست‌ها ناهم‌گام‌اند؛ پس ابتدا ارسال کنید و سپس status_url را مرتب بررسی کنید.

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

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

دریافت کلید APIاتصال دستیار خود