Перейти к содержимому

Mage SDK · Python

Python SDK для Mage

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

pip install mage-space

Главное

Python SDK Mage — официальный клиент с открытым исходным кодом для Mage API, опубликованный как mage-space. Установите его командой «pip install mage-space», задайте MAGE_API_KEY и вызовите mage.run с id модели и конфигом, чтобы получить готовые изображения, видео или аудио от любой из 37 моделей. Работает на Python 3.10 и новее; каждая генерация оплачивается в Gems.

  • 3.10+Python
  • httpxHTTP-клиент
  • 37Типизированные модели
  • 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-v4",
    })
    
    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, и возвращает завершённый запрос с result.url.

  • Повторы без двойной оплаты

    Каждый запрос содержит ключ идемпотентности. При сетевых и серверных ошибках запрос повторяется с нарастающей задержкой, а повторная отправка никогда не оплачивается снова.

  • Загрузка файлов одним вызовом

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

  • Понятные ошибки

    Отказы API содержат HTTP-статус, код ошибки и идентификатор запроса; для неудачных и отменённых генераций и для тайм-аутов есть отдельные типы ошибок.

  • Синхронный режим и 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 МБ и возвращает его URL.
mage.characters / mage.referencesСписок, создание и удаление сохранённых персонажей и референсов.
mage.account.get()Ваш баланс Gems.
mage.architectures.list()Актуальный каталог моделей с параметрами и ценами.

Модели

Начните с этих моделей

  • Изображения · от 37 Gems

    Guava API

    Фотореализм, неотличимый от настоящего снимка

  • Изображение · от 42 Gems

    Mango API

    Наше флагманское семейство моделей для изображений

  • Изображение · от 51 Gems

    Nano Banana 2 API

    Чёткий, читаемый текст, до 4K

  • Видео · от 618 Gems

    Cherry API

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

  • Видео · от 245 Gems

    Lemon API

    Все возможности видео по более доступной цене

  • Аудио · от 19 Gems

    Seed Audio API

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

FAQ

Частые вопросы

Поддерживает ли Python SDK asyncio?
Да. У AsyncMage те же методы, что и у Mage, но с await, и он работает как асинхронный контекстный менеджер.
Какие версии Python поддерживает SDK?
Python 3.10 и новее. Единственные зависимости — httpx и typing-extensions.
Можно ли использовать Python SDK в ноутбуке или конвейере данных?
Да. Используйте Mage в скриптах и ноутбуках или AsyncMage с asyncio, чтобы запускать много генераций одновременно. Для аккаунта одновременно может выполняться до 20 генераций.
SDK Mage бесплатные и с открытым кодом?
Да. SDK и узлы ComfyUI распространяются на GitHub по лицензии MIT, а установка бесплатна. Вы платите только за запущенные генерации — в Gems, по цене, указанной для каждой модели.
Будут ли новые модели Mage работать со старой версией SDK?
Да. Передайте id новой модели строкой — и она запустится: SDK проверяет конфигурацию по полям, общим для всех моделей. Бот обновляет типы при каждом изменении справочника API, поэтому новые модели получают собственные типы в следующем релизе.
Как SDK не позволяет заплатить дважды за повторный запрос?
Каждый запрос отправляется с Idempotency-Key. SDK создаёт новый ключ для каждого вызова и использует его повторно, когда сам повторяет этот вызов, поэтому повторная отправка возвращает исходный запрос и ничего не списывает.
Стабильны ли SDK?
Они находятся в бета-версии 0.x, поэтому в минорных версиях возможны изменения. Сам API версионируется отдельно и остаётся стабильным в рамках v1.
Сколько стоит Mage API?
Подписки и ежемесячной платы нет. Каждая генерация оплачивается в Gems по цене её модели, а 1 000 Gems в стандартном пакете стоят $1. На странице каждой модели указана цена при настройках по умолчанию, а в каждом ответе — точная сумма списания. Если генерация не удалась, Gems возвращаются; если её заблокировала политика контента Mage — нет. Запрос, на который не хватает баланса, отклоняется до любого списания.
Нужна ли подписка Mage, чтобы пользоваться API?
Нет. API работает только на Gems. Тарифные планы и безлимитная генерация в приложении на запросы через API не распространяются. Сначала на аккаунте должен пройти один успешный платёж: подойдёт любой пакет Gems или любой план. Бонусные Gems, полученные при регистрации, действуют только в приложении Mage.
Можно ли использовать результаты API в коммерческих целях?
Да. Контент, созданный в Mage, в том числе через API и MCP-сервер, можно использовать в коммерческих целях. Указывать авторство приятно, но необязательно.

Начните создавать с Mage

Один аккаунт, один баланс Gems, все модели. Платите только за то, что генерируете.

CharactersСообщество