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