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

API مجیج · تولید ویدیو

API تولید ویدیو با هوش مصنوعی، از روی متن یا تصویر

متن به ویدیو، تصویر به ویدیو، فریم اول و آخر و مرجع به ویدیو با ۱۲ مدل، با پرچمدار Mage یعنی Cherry 2 Pro، و صدا در بسیاری از کلیپ‌ها.

دریافت کلید APIمطالعه مستندات API
POST https://api.mage.space/v1/{model}/generate

در یک نگاه

API تولید ویدیوی Mage یک REST API در https://api.mage.space/v1 است که ۱۲ مدل متن به ویدیو و تصویر به ویدیو از جمله Cherry 2 Pro، Lemon، Plum، Melon، MiniMax-H3، Grok Video و Wan را اجرا می‌کند. یک پرامپت و در صورت نیاز فریم یا مرجع بفرستید، درخواست را پیگیری (poll) کنید و یک فایل MP4 دانلود کنید. هزینهٔ هر کلیپ بر اساس مدل، رزولوشن و مدت با Gem پرداخت می‌شود.

  • 12مدل ویدیو
  • $0.02ارزان‌ترین گزینهٔ پیش‌فرض، هر کلیپ
  • 20تولید هم‌زمان
  • $0هزینه ماهانه

مدل‌ها

همهٔ مدل‌های ویدیو در API مجیج

قیمت‌ها به‌ازای هر تولید و بر حسب Gem است. ۱,۰۰۰ Gem در بستهٔ استاندارد ۱ دلار است و بسته‌های بزرگ‌تر Gem جایزه دارند. قیمت به مدل، رزولوشن و مدت‌زمان بستگی دارد؛ قیمت با تنظیمات پیش‌فرض نمایش داده شده و هر پاسخ مبلغ دقیق را در billing.gems_charged اعلام می‌کند. تولیدی که ناموفق شود بازپرداخت می‌شود؛ تولیدی که سیاست محتوایی Mage مسدودش کند، بازپرداخت نمی‌شود.

مدلمناسب برایمقادیر model_idقیمت پیش‌فرض
Berryویدیویی که به مرجع‌هایتان وفادار می‌ماندberry, berry-2189 Gems ($0.189)
Blueberryفریم اول و آخر را ثابت کنیدblueberry, blueberry-v2360 Gems ($0.36)
Cherryخانوادهٔ پرچمدار ویدیوی ماcherry-mini, cherry, cherry-pro, cherry-2-pro618 Gems ($0.618)
Grok VideoGrok Imagine در حرکتgrok-imagine-video375 Gems ($0.375)
Kiwiویدیوی روزمره، بدون هیچ راه‌اندازیkiwi270 Gems ($0.27)
Lemonهمهٔ امکانات ویدیو با قیمتی مناسب‌ترlemon245 Gems ($0.245)
LTX Videoویدیوی سریع با وزن‌های باز برای آزمون‌وخطاltx-video-096-distilled, ltx-video-096-dev20 Gems ($0.02)
Melonانیمهٔ متحرک، با صدای اختیاریmelon, melon-pro147 Gems ($0.147)
MiniMax-H3ویدیوی باز و سریع با صدای استریوminimax-h3-turbo, minimax-h330 Gems ($0.03)
Plumصدا روی هر کلیپ، تا 2Kplum, plum-max338 Gems ($0.338)
Raspberryشخصیت‌هایی که از یک فریم اول جان می‌گیرندraspberry360 Gems ($0.36)
Wan Video v2.2ویدیوی با وزن‌های باز و نسخهٔ Lightningwan22-video, wan22-video-lightning40 Gems ($0.04)

شروع سریع

ساخت ویدیو با Berry 2

MAGE_API_KEY را تنظیم کنید، درخواست را بفرستید و تا پایان کار پیگیری (poll) کنید. berry را در URL با هر مدل بالا جایگزین کنید.

cURL
STATUS_URL=$(curl --request POST 'https://api.mage.space/v1/berry/generate' \
  --header "Authorization: Bearer $MAGE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "A slow push-in on a lighthouse at dusk, waves breaking below",
  "aspect_ratio": "16:9",
  "duration": "3",
  "model_id": "berry-2"
}' | 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('berry', {
  prompt: 'A slow push-in on a lighthouse at dusk, waves breaking below',
  aspect_ratio: '16:9',
  duration: '3',
  model_id: 'berry-2',
});

console.log(request.result.url);
Python
# pip install mage-space
from mage_space import Mage

mage = Mage()  # reads MAGE_API_KEY

request = mage.run("berry", {
    "prompt": "A slow push-in on a lighthouse at dusk, waves breaking below",
    "aspect_ratio": "16:9",
    "duration": "3",
    "model_id": "berry-2",
})

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 با فایل تصویر، ویدیو یا صدا است که ۳۰ روز نگهداری می‌شود.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

موارد استفاده

توسعه‌دهندگان با API ویدیو چه می‌سازند

  • ویدیوی کوتاه و شبکه‌های اجتماعی

    از روی یک پرامپت یا تصویر محصول، کلیپ‌های عمودی برای TikTok، Reels و Shorts بسازید.

  • متحرک‌سازی تصاویر ثابت

    با مدل‌های تصویر به ویدیو مثل Lemon و Kiwi، یک فریم اول یا فریم اول و آخر را به حرکت تبدیل کنید.

  • داستان‌های شخصیت‌محور

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

  • ویدیو با صدا

    Plum و چند مدل دیگر گفتار، افکت صوتی و صدای محیط را همراه تصویر تولید می‌کنند و برای صداها مرجع صوتی می‌پذیرند.

  • تبلیغات و دموی محصول

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

  • ویرایش کلیپ‌های موجود

    Berry، Plum و Grok Video ویدیوی مبدأ شما را ویرایش می‌کنند؛ Lemon و MiniMax-H3 ویدیوهای مرجع را هم می‌پذیرند.

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

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

بهترین API تولید ویدیو با هوش مصنوعی کدام است؟
در Mage، مدل Cherry 2 Pro گزینهٔ پیش‌فرض ویدیو است: از شخصیت‌ها، تصاویر مرجع متعدد، مرجع صوتی، خروجی 480p تا 1080p و کلیپ‌هایی تا ۳۰ ثانیه پشتیبانی می‌کند. Lemon برای کنترل فریم اول و آخر، Plum برای کلیپ‌هایی با صدای تولیدشده تا 2K، و Cherry Mini یا Wan برای پیش‌نویس‌های ارزان‌تر انتخاب خوبی هستند.
آیا API ویدیو از تصویر به ویدیو پشتیبانی می‌کند؟
بله. مدل‌های تصویر به ویدیو یک فریم اول می‌پذیرند و برخی فریم آخر یا تصاویر مرجع را هم به‌صورت URL، data URL یا آپلود دریافت می‌کنند. صفحهٔ هر مدل ورودی‌ها و اجباری‌بودن تصویر را مشخص کرده است.
ویدیوهای تولیدشده چقدر می‌توانند طولانی باشند؟
بسته به مدل و رزولوشن فرق می‌کند. بسیاری از مدل‌ها ۴ تا ۱۵ ثانیه تولید می‌کنند و Cherry 2 Pro به ۲۰، ۲۵ و ۳۰ ثانیه می‌رسد. صفحهٔ هر مدل مدت‌های پشتیبانی‌شده را فهرست کرده است.
تولید یک ویدیو چقدر طول می‌کشد؟
بسته به مدل، رزولوشن و مدت فرق می‌کند. API ناهمگام (asynchronous) است: درخواست را بفرستید، سپس status_url را با backoff پیگیری کنید، یا بگذارید کلاینت MCP شما با get_request منتظر بماند.
هزینه‌ی 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مطالعه مستندات API