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

Mage SDK · TypeScript

Mage TypeScript SDK

Генерируйте изображения, видео и аудио из Node.js с типизированными конфигурациями для каждой модели Mage. Один вызов отправляет запрос, ждёт и возвращает результат.

npm install @mage-space/sdk

Главное

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

  • 20.19+Node.js
  • 0Зависимости времени выполнения
  • 37Типизированные модели
  • MITОткрытый код

Настройка

Установите TypeScript SDK и запустите модель

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

    Добавьте @mage-space/sdk в свой проект.

    npm install @mage-space/sdk
  2. Задайте API-ключ

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

    export MAGE_API_KEY="mage_sk_..."
  3. Сгенерируйте

    Вызовите run с id модели и её конфигурацией. Метод дождётся результата и вернёт его; файл доступен по адресу result.url.

    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-v4',
    });
    
    console.log(request.result.url);

Примеры

TypeScript SDK на практике

Каждый пример начинается с клиента, который читает MAGE_API_KEY.

Отправить сейчас, дождаться позже
import Mage from '@mage-space/sdk';

const mage = new Mage(); // reads MAGE_API_KEY

const submitted = await mage.generate('cherry', {
  prompt: 'Waves rolling onto a black sand beach at sunset',
  resolution: '720p',
  duration: '5',
});

const final = await mage.requests.wait(submitted.request_id, {
  timeout: 15 * 60_000,
  onUpdate: (request) => console.log(request.status),
});
Загрузить файл
import { readFile } from 'node:fs/promises';
import Mage from '@mage-space/sdk';

const mage = new Mage(); // reads MAGE_API_KEY

const clip = await mage.uploads.upload(await readFile('clip.mp4'), {
  contentType: 'video/mp4',
});

await mage.run('cherry', {
  prompt: 'Restyle this clip as a watercolor painting',
  videos: [clip.url],
});
Использовать сохранённого персонажа
import Mage from '@mage-space/sdk';

const mage = new Mage(); // reads MAGE_API_KEY

await mage.characters.create({
  name: 'Ana',
  handle: 'ana',
  image: 'https://example.com/ana.png',
});

await mage.run('mango', { prompt: '@ana walking through a night market' });
Обработка ошибок
import Mage, { MageAPIError, MageGenerationError } from '@mage-space/sdk';

const mage = new Mage(); // reads MAGE_API_KEY

try {
  await mage.run('mango', { prompt: 'A lighthouse at night' });
} catch (error) {
  if (error instanceof MageAPIError && error.code === 'insufficient_gems') {
    // Top up Gems, then try again.
  } else if (error instanceof MageGenerationError) {
    console.log('No output:', error.code);
  } else {
    throw error;
  }
}

Зачем нужен SDK

Что SDK делает за вас

  • Один вызов — готовый файл

    run отправляет генерацию, опрашивает статус с интервалом, который рекомендует API, и возвращает завершённый запрос с result.url.

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

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

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

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

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

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

  • Типы для каждой модели

    MangoConfig, CherryConfig и остальные генерируются из справочника API, поэтому редактор подсказывает поля и находит недопустимые параметры.

  • Без зависимостей

    ESM без зависимостей времени выполнения. Используется встроенный в Node.js fetch, а каждый вызов принимает AbortSignal.

Справочник

TypeScript 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

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

Можно ли использовать Mage TypeScript SDK в браузере?
Нет. API-ключ тратит ваши Gems, поэтому храните его на своих серверах. API не отправляет заголовки CORS, поэтому браузеры не могут обращаться к нему напрямую: вызывайте собственный бэкенд, а он пусть использует SDK.
Работает ли TypeScript SDK с CommonJS?
Пакет поддерживает только ESM. В Node.js 20.19 и новее его можно подключить через require() и из CommonJS.
Работает ли TypeScript SDK с Next.js?
Да, в серверном коде: обработчиках маршрутов и server actions. SDK построен на fetch и стандартных веб-API, таких как AbortSignal, поэтому должен работать и в других серверных средах с fetch, хотя в CI он тестируется на Node.js.
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Сообщество