Один вызов — готовый файл
run отправляет генерацию, опрашивает статус с интервалом, который рекомендует API, и возвращает завершённый запрос с result.url.
Главное
Mage публикует открытые SDK для своего API: @mage-space/sdk в npm для TypeScript и JavaScript, mage-space в PyPI для Python и набор нод comfyui-mage для ComfyUI. Каждый SDK оборачивает REST API и включает типизированные конфигурации всех 28 моделей, автоматический опрос статуса, идемпотентные повторные запросы и загрузку файлов.
3
SDK и интеграции
28
Типизированные модели
MIT
Открытый код
$0
Для установки
Выберите свой
SDK и интеграции
npm install @mage-space/sdk
SDK для TypeScript
Генерируйте изображения, видео и аудио из Node.js с типизированными конфигурациями для каждой модели Mage. Один вызов отправляет запрос, ждёт и возвращает результат.
pip install mage-space
SDK для Python
Генерируйте изображения, видео и аудио из Python с синхронным и asyncio-клиентами и типизированными конфигурациями для каждой модели Mage.
comfy node install comfyui-mage
Mage для ComfyUI
Mango, Cherry, Seed Audio и все остальные модели Mage в виде нод ComfyUI. Без GPU и без загрузки моделей.
Быстрый старт
Ваша первая генерация с SDK
Установите пакет, задайте 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('mango', {
prompt: 'Editorial portrait in soft daylight, 35mm film look',
aspect_ratio: '4:5',
model_id: 'mango-v3',
});
console.log(request.result.url);Python
# pip install mage-space
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"])Встроено
Что каждый SDK делает за вас
Повторы без двойной оплаты
Каждый запрос содержит ключ идемпотентности. При сетевых и серверных ошибках запрос повторяется с нарастающей задержкой, а повторная отправка никогда не оплачивается снова.
Загрузка файлов одним вызовом
Файлы, слишком большие для data URL, загружаются по подписанной ссылке: тикет, PUT-запрос и проверку размера SDK берёт на себя.
Понятные ошибки
Отказы API содержат HTTP-статус, код ошибки и идентификатор запроса; для неудачных и отменённых генераций и для тайм-аутов есть отдельные типы ошибок.
Пакеты
Где их взять
| SDK | Пакет | Установка | Исходный код |
|---|---|---|---|
| SDK для TypeScript | @mage-space/sdk | npm install @mage-space/sdk | GitHub |
| SDK для Python | mage-space | pip install mage-space | GitHub |
| Mage для ComfyUI | comfyui-mage | comfy node install comfyui-mage | GitHub |
FAQ
Частые вопросы
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 не распространяются, поэтому им может пользоваться любой аккаунт Mage с Gems.
Можно ли использовать результаты API в коммерческих целях?
Да. Контент, созданный в Mage, в том числе через API и MCP-сервер, можно использовать в коммерческих целях. Указывать авторство приятно, но необязательно.
Начните создавать с Mage
Один аккаунт, один баланс Gems, все модели. Платите только за то, что генерируете.