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 и запустите модель
Установите пакет
Добавьте mage-space в свой проект.
pip install mage-spaceЗадайте API-ключ
Создайте ключ в разделе API → API Keys на mage.space и экспортируйте его. Клиент читает переменную MAGE_API_KEY.
export MAGE_API_KEY="mage_sk_..."Сгенерируйте
Вызовите 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() | Актуальный каталог моделей с параметрами и ценами. |
Модели
Начните с этих моделей
Guava API
Фотореализм, неотличимый от настоящего снимка
Mango API
Наше флагманское семейство моделей для изображений
Nano Banana 2 API
Чёткий, читаемый текст, до 4K
Cherry API
Наше флагманское семейство моделей для видео
Lemon API
Все возможности видео по более доступной цене
Seed Audio API
Голоса, музыка и звуковые эффекты из одного промпта
FAQ
Частые вопросы
Поддерживает ли Python SDK asyncio?
Какие версии Python поддерживает SDK?
Можно ли использовать Python SDK в ноутбуке или конвейере данных?
SDK Mage бесплатные и с открытым кодом?
Будут ли новые модели Mage работать со старой версией SDK?
Как SDK не позволяет заплатить дважды за повторный запрос?
Стабильны ли SDK?
Сколько стоит Mage API?
Нужна ли подписка Mage, чтобы пользоваться API?
Можно ли использовать результаты API в коммерческих целях?
Начните создавать с Mage
Один аккаунт, один баланс Gems, все модели. Платите только за то, что генерируете.