Перейти до вмісту
PlaygroundДокументаціяОтримати API-ключ

API Mage · Генерація зображень

API генерації зображень ШІ для всіх моделей

Текст у зображення, редагування та послідовні персонажі з 15 моделей, зокрема флагманської Mango 3 від Mage, — через один ключ і один баланс.

Отримати API-ключЧитати документацію API
POST https://api.mage.space/v1/{model}/generate

Коротко

API генерації зображень Mage — це REST API за адресою https://api.mage.space/v1, що запускає 15 моделей для створення зображень із тексту та їх редагування, зокрема Mango 3, Guava 2 Pro, GPT Image 2.5, Nano Banana 2, Flux 2 і Krea 2. Ти надсилаєш POST із промптом на /{model}/generate, опитуєш запит і завантажуєш зображення. Кожне зображення оплачується в Gems, без підписки.

  • 15моделей зображень
  • $0.009Найдешевший варіант за замовчуванням, за зображення
  • 20Одночасні генерації
  • $0Щомісячна плата

Моделі

Усі моделі зображень в API Mage

Ціни вказано за одну генерацію, у Gems. 1 000 Gems коштують $1 у стандартному пакеті, а більші пакети дають додаткові Gems. Ціна залежить від моделі, роздільної здатності та тривалості; показано ціну за стандартних налаштувань, а точну суму списання кожна відповідь містить у 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_ і показується лише один раз. В акаунті може бути 10 активних ключів.

  2. Надішли генерацію

    Надішли POST із JSON-тілом на https://api.mage.space/v1/{model}/generate із заголовком Authorization: Bearer. Відповідь приходить одразу й містить request_id, status і status_url. Додай заголовок Idempotency-Key, щоб повторна спроба ніколи не списувала оплату двічі.

  3. Опитуй і завантажуй

    Опитуй status_url, доки статус не стане completed, failed або cancelled. Завершений запит містить result.url із файлом зображення, відео чи аудіо, який зберігається 30 днів.

Створено для продакшну

Що отримує кожен запит до Mage API

  • Один ключ — усі моделі

    28 моделей для зображень, відео й аудіо в одному REST API з єдиним балансом Gems. Щоб змінити модель, достатньо змінити шлях в URL.

  • Оплата за кожну генерацію

    Без підписки й мінімальних витрат. Ти купуєш Gems, а за кожен запит списується його вказана ціна. Якщо генерація не вдалася, кошти повертаються — крім випадків, коли її заблокувала політика щодо контенту Mage.

  • Безпечні повторні спроби

    Ключі ідемпотентності гарантують, що повторне надсилання поверне початковий запит без повторного списання коштів.

  • Стабільні персонажі

    Збережи персонажа або референс один раз, а потім пиши @handle у будь-якому промпті, щоб використовувати його з усіма моделями, які це підтримують.

  • Великі вхідні файли

    Надсилай зображення, відео й аудіо як URL чи data URL або завантажуй файли до 100 МБ через підписане завантаження.

  • 20 генерацій одночасно

    Кожен обліковий запис може запускати 20 генерацій одночасно, а ліміт можна підвищити під твій сценарій. За відхилені запити кошти не списуються.

Сценарії використання

Що розробники створюють за допомогою 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?
Жодної підписки чи щомісячної плати. Кожна генерація оплачується в Gems за ціною моделі, а 1000 Gems коштують $1 у стандартному пакеті. На сторінці кожної моделі вказана ціна за стандартних налаштувань, а у відповіді на запит показано точну суму списання. Якщо генерація не вдалася, кошти повертаються; якщо її заблокувала політика щодо контенту Mage — ні. Запит, на який не вистачає балансу, відхиляється ще до будь-якого списання.
Чи потрібна підписка на Mage, щоб користуватися API?
Ні. API працює лише на Gems. Плани підписки та безлімітна генерація в застосунку не поширюються на API-запити, тож його може викликати будь-який акаунт Mage з Gems.
Чи можна використовувати результати API в комерційних цілях?
Так. Контент, створений у Mage, зокрема через API та MCP-сервер, можна використовувати в комерційних цілях. Вказувати авторство бажано, але не обов’язково.
Які є ліміти запитів?
В одному акаунті може одночасно бути 20 генерацій у черзі або в роботі. Запит понад ліміт відхиляється з помилкою 429 і нічого не коштує. Напиши на [email protected], щоб збільшити ліміт під твій сценарій.
Чи може мій ШІ-агент користуватися API Mage?
Так. Агенти можуть викликати REST API за допомогою ключа або підключитися до MCP-сервера Mage, який дає Claude, ChatGPT, Claude Code, Grok і Cursor шістнадцять готових інструментів для вибору моделі, розрахунку ціни, генерації та отримання результату. Докладніше — про MCP-сервер.
Чи є SDK для API Mage?
Так. Офіційні пакети @mage-space/sdk на npm і mage-space на PyPI мають відкритий код і типізовані для кожної моделі. Вони самі надсилають запити, чекають на результат, безпечно повторюють спроби та завантажують файли. Користувачі ComfyUI можуть встановити набір нод comfyui-mage. Докладніше — про SDK Mage.
Я вже користуюся іншим API для генерації. Що мені потрібно змінити?
Вкажи у своєму клієнті https://api.mage.space/v1, надсилай ключ Mage як Bearer-токен і зістав свої поля зі сторінкою моделі: prompt, aspect_ratio, resolution, duration і model_id працюють однаково в усіх моделях Mage. Запити асинхронні, тому надішли запит, а потім опитуй status_url.

Створюй з Mage

Один акаунт, один баланс Gems, усі моделі. Плати лише за те, що генеруєш.

Отримати API-ключЧитати документацію API