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

Mage API · تولید تصویر

API تولید تصویر با هوش مصنوعی برای همهٔ مدل‌ها

تبدیل متن به تصویر، ویرایش تصویر و کاراکترهای ثابت از ۱۵ مدل، از جمله Mango 3 مدل شاخص Mage، با یک کلید و یک موجودی.

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

در یک نگاه

API تولید تصویر Mage یک REST API در https://api.mage.space/v1 است که ۱۵ مدل تبدیل متن به تصویر و ویرایش تصویر را اجرا می‌کند، از جمله Mango 3، Guava 2 Pro، GPT Image 2.5، Nano Banana 2، Flux 2 و Krea 2. یک prompt را با POST به /{model}/generate می‌فرستید، درخواست را پیگیری می‌کنید و تصویر را دانلود می‌کنید. هزینهٔ هر تصویر با Gem پرداخت می‌شود، بدون اشتراک.

  • 15مدل تصویر
  • $0.009ارزان‌ترین قیمت پیش‌فرض، به‌ازای هر تصویر
  • 20تولید هم‌زمان
  • $0هزینه ماهانه

مدل‌ها

همهٔ مدل‌های تصویر در Mage API

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

مدلمناسب برایمقادیر model_idقیمت پیش‌فرض
Animaساخته‌شده مخصوص انیمهanima-v120 Gems ($0.02)
Chromaبا وزن‌های باز، بر پایهٔ Fluxchroma-v1-hd35 Gems ($0.035)
Flux 2پرامپت‌های بلند و ویرایش با چند تصویر مرجعflux2-dev40 Gems ($0.04)
GPT Image 2پرامپت‌های دقیق و متن خواناgpt-image-2, gpt-image-2.5-flare, gpt-image-2.5-sunburst9 Gems ($0.009)
Grok ImageGrok Imagine در سه سطح کیفیتgrok-imagine-image, grok-imagine-image-quality, grok-imagine-image-2.075 Gems ($0.075)
Guavaفوتورئالیسمی که با عکس واقعی اشتباه گرفته می‌شودguava, guava-pro, guava-pro-v1-5, guava-2, guava-2-pro37 Gems ($0.037)
HiDreamسریع و همه‌کاره، با پرامپت منفیhidream-fast20 Gems ($0.02)
Krea 2زیبایی خیره‌کننده در چند ثانیهkrea-2-turbo20 Gems ($0.02)
Mangoخانوادهٔ مدل‌های تصویر شاخص ماmango, mango-v2, mango-v3s, mango-v3, mango-v3-turbo135 Gems ($0.135)
Nano Banana 2متن شفاف و خوانا، تا 4Knano-banana-v2, nano-banana-v2.151 Gems ($0.051)
SDXL PlusSDXL با چهره و دست‌های اصلاح‌شده6A35A7855770AE9820A3C931D4964C3817B6D9E3C6F9C4DABB5B3A94E5643B8015 Gems ($0.015)
Stable Diffusion v1.5مدل کلاسیک، با هزینهٔ کم15012C538F503CE2EBFC2C8547B268C75CCDAFF7A281DB55399940FF1D70E21D10 Gems ($0.01)
Stable Diffusion v3.5 LargeStable Diffusion‌ای که بهتر از همه حرفتان را می‌فهمدsd-3-5-large10 Gems ($0.01)
Stable Diffusion XLSDXL تنظیم‌شده برای فوتورئال6A35A7855770AE9820A3C931D4964C3817B6D9E3C6F9C4DABB5B3A94E5643B8010 Gems ($0.01)
Z-Imageسریع‌ترین مدل تصویر در Magez-image-turbo10 Gems ($0.01)

شروع سریع

تولید تصویر با Anima v1

MAGE_API_KEY را تنظیم کنید، درخواست را ارسال کنید و تا تکمیل شدن آن پیگیری کنید. anima را در URL با هر یک از مدل‌های بالا عوض کنید.

cURL
STATUS_URL=$(curl --request POST 'https://api.mage.space/v1/anima/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": "anima-v1"
}' | 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('anima', {
  prompt: 'Editorial portrait in soft daylight, 35mm film look',
  aspect_ratio: '4:5',
  model_id: 'anima-v1',
});

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

mage = Mage()  # reads MAGE_API_KEY

request = mage.run("anima", {
    "prompt": "Editorial portrait in soft daylight, 35mm film look",
    "aspect_ratio": "4:5",
    "model_id": "anima-v1",
})

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 تصویر چه می‌سازند

  • تصاویر محصول و بازاریابی

    عکس محصول، نسخه‌های مختلف تبلیغ و پست‌های شبکه‌های اجتماعی را هر زمان لازم شد بسازید، با متن خوانا از GPT Image 2.5 یا Nano Banana 2.

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

    یک کاراکتر را فقط یک بار ذخیره کنید و با Mango 3، Guava 2 Pro و مدل‌های دیگری که منشن @handle را می‌پذیرند، چهرهٔ یکسان را در کل یک مجموعه حفظ کنید.

  • پایپ‌لاین‌های ویرایش تصویر

    یک تصویر مبدأ را همراه با دستور بفرستید تا دقیقاً همان چیزی که می‌خواهید تغییر کند و بقیهٔ تصویر سر جایش بماند.

  • اپ‌ها و بازی‌ها

    آواتار، استیکر، کارت و صحنه را داخل محصول خودتان بسازید، بدون اینکه حتی یک GPU میزبانی کنید.

  • پرتره‌های فوتورئال

    Guava 2 Pro پرتره، مد و عکس‌های لایف‌استایل را با پوست، پارچه و نوری شبیه به واقعیت می‌سازد.

  • پیش‌نویس‌های سریع در مقیاس بالا

    Z-Image Turbo و Krea 2 هزینه را برای تصاویر بندانگشتی پرحجم و نسخه‌های اولیه پایین نگه می‌دارند.

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

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

بهترین API تولید تصویر با هوش مصنوعی کدام است؟
بستگی به کار دارد. در Mage، مدل Mango 3 گزینهٔ پیش‌فرض برای بیشتر تصاویر است: دستورهای دقیق را دنبال می‌کند، شخصیت‌ها را یکدست نگه می‌دارد و بدون به‌هم‌زدن بقیهٔ تصویر ویرایش می‌کند. Guava 2 Pro برای فوتورئالیسم بهترین است، GPT Image 2.5 و Nano Banana 2 برای متن داخل تصویر، و Z-Image Turbo یا Krea 2 برای پیش‌نویس‌های سریع و ارزان. همهٔ آن‌ها از طریق یک API اجرا می‌شوند.
آیا API تصویر از ویرایش تصویر و تصاویر مرجع پشتیبانی می‌کند؟
بله. مدل‌هایی که تصویر می‌پذیرند، آن را در فیلدهای image و additional_images به‌صورت URL، data URL یا آپلود دریافت می‌کنند. صفحهٔ هر مدل ورودی‌ها و تعداد تصاویر مرجع قابل‌قبول آن را فهرست کرده است.
API تصویر از چه رزولوشن‌هایی پشتیبانی می‌کند؟
بسته به مدل فرق می‌کند: 1K و 2K در بیشتر مدل‌ها، 3K در Mango 3S و تا 4K در Mango 2 و Nano Banana 2. صفحهٔ هر مدل گزینه‌های رزولوشن و نسبت تصویر آن را نشان می‌دهد.
هزینه‌ی 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