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

Mage SDK · Python

Python SDK для Mage

Генеруй зображення, відео й аудіо з Python за допомогою синхронних та asyncio-клієнтів і типізованих конфігурацій для кожної моделі Mage.

Отримати API-ключЧитати посібник із PythonКод на GitHub
pip install mage-space

Коротко

Python SDK для Mage — це офіційний клієнт API Mage з відкритим кодом, опублікований як mage-space. Встанови його командою "pip install mage-space", задай MAGE_API_KEY і викличи mage.run з ідентифікатором моделі та конфігурацією, щоб отримати готові зображення, відео або аудіо від будь-якої з 28 моделей. Він працює на Python 3.10 або новіших версіях, а кожна генерація оплачується в Gems.

  • 3.10+Python
  • httpxHTTP-клієнт
  • 28Типізовані моделі
  • MITВідкритий код

Налаштування

Встанови Python SDK і запусти модель

  1. Установіть пакет

    Додай mage-space до свого проєкту.

    pip install mage-space

  2. Задайте API-ключ

    Створіть ключ у розділі API → API Keys на mage.space і експортуйте його. Клієнт читає MAGE_API_KEY.

    export MAGE_API_KEY="mage_sk_..."

  3. Згенеруйте

    Викличте run з id моделі та її конфігурацією. Він дочекається результату й поверне його; вихідний файл буде в 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"])

Приклади

Python 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"]],
})
Використати збереженого персонажа
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 надсилає генерацію, опитує API з рекомендованою затримкою (backoff) і повертає завершений запит із result.url.

  • Повтори без подвійної оплати

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

  • Завантаження одним викликом

    Файли, завеликі для data URL, надсилаються через підписане завантаження: квиток, PUT і перевірку розміру SDK бере на себе.

  • Зрозумілі помилки

    Відмови API містять HTTP-статус, код помилки та id запиту; невдалі або скасовані генерації й тайм-аути мають власні типи помилок.

  • Sync та asyncio

    Mage і AsyncMage мають однакові методи. Асинхронний клієнт підходить для вебсерверів, ноутбуків і пайплайнів, що запускають багато генерацій одночасно.

  • Типізовані конфігурації

    Для кожної моделі є TypedDict, наприклад MangoConfig, згенерований із довідника API. Анотуй ним конфігурацію, і твій перевірник типів перевірить поля.

Довідник

Python SDK коротко

Одні й ті самі методи працюють для всіх моделей; модель — це перший аргумент.

МетодЩо він робить
mage.run(model, config)Надсилає генерацію, чекає на неї й повертає завершений запит.
mage.generate(model, config)Надсилає генерацію й одразу повертає запит.
mage.requests.get / cancel / waitЧитає, зупиняє або очікує запит за id.
mage.uploads.upload(data)Завантажує шлях, байти або файл розміром до 100 MB і повертає його URL.
mage.characters / mage.referencesПоказує, створює та видаляє збережених персонажів і референси.
mage.account.get()Ваш баланс Gems.
mage.architectures.list()Актуальний каталог моделей із параметрами та цінами.

Моделі

Почніть із цих моделей

  • Зображення · від 37 Gems

    Guava API

    Фотореалізм, який не відрізниш від справжнього фото

  • Зображення · від 135 Gems

    Mango API

    Наша флагманська лінійка моделей для зображень

  • Зображення · від 51 Gems

    Nano Banana 2 API

    Чіткий, читабельний текст, до 4K

  • Відео · від 618 Gems

    Cherry API

    Наша флагманська лінійка моделей для відео

  • Відео · від 245 Gems

    Lemon API

    Усі відеофункції за привабливішою ціною

  • Аудіо · від 19 Gems

    Seed Audio API

    Голоси, музика та звукові ефекти з одного промпту

Поширені запитання

Поширені запитання

Чи підтримує Python SDK asyncio?
Так. AsyncMage має ті самі методи, що й Mage, але з await, і працює як асинхронний контекстний менеджер.
Які версії Python підтримує SDK?
Python 3.10 і новіші. Його єдині залежності — httpx і typing-extensions.
Чи можна використовувати Python SDK у ноутбуці або конвеєрі даних?
Так. Використовуй Mage у скриптах і ноутбуках або AsyncMage з asyncio, щоб запускати багато генерацій одночасно. Акаунт може виконувати до 20 генерацій одночасно.
Чи безкоштовні й відкриті SDK Mage?
Так. SDK і вузли ComfyUI мають ліцензію MIT та доступні на GitHub, а встановити їх можна безкоштовно. Ви платите лише за генерації, які запускаєте, у Gems за ціною, указаною для кожної моделі.
Чи працюють нові моделі Mage зі старішою версією SDK?
Так. Передайте id нової моделі рядком, і вона запрацює: SDK перевіряє конфігурацію за полями, спільними для всіх моделей. Бот оновлює типи щоразу, коли змінюється довідник API, тож нові моделі отримують власні типи в наступному релізі.
Як SDK уникають подвійної оплати за повторний запит?
Кожен запит містить Idempotency-Key. SDK створює новий ключ для кожного виклику й використовує його повторно, коли сам повторює цей виклик, тож повторне надсилання повертає початковий запит і не стягує плату.
Чи стабільні SDK?
Вони в бета-версії 0.x, тож другорядна версія ще може їх змінити. Версії самого API ведуться окремо, і в межах v1 він залишається стабільним.
Скільки коштує Mage API?
Жодної підписки чи щомісячної плати. Кожна генерація оплачується в Gems за ціною моделі, а 1000 Gems коштують $1 у стандартному пакеті. На сторінці кожної моделі вказана ціна за стандартних налаштувань, а у відповіді на запит показано точну суму списання. Якщо генерація не вдалася, кошти повертаються; якщо її заблокувала політика щодо контенту Mage — ні. Запит, на який не вистачає балансу, відхиляється ще до будь-якого списання.
Чи потрібна підписка на Mage, щоб користуватися API?
Ні. API працює лише на Gems. Плани підписки та безлімітна генерація в застосунку не поширюються на API-запити, тож його може викликати будь-який акаунт Mage з Gems.
Чи можна використовувати результати API в комерційних цілях?
Так. Контент, створений у Mage, зокрема через API та MCP-сервер, можна використовувати в комерційних цілях. Вказувати авторство бажано, але не обов’язково.

Створюй з Mage

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

Отримати API-ключЧитати посібник із Python