Mage SDK · TypeScript
Mage TypeScript SDK
Генеруйте зображення, відео й аудіо з Node.js за допомогою типізованих конфігурацій для кожної моделі Mage. Один виклик надсилає запит, чекає й повертає результат.
npm install @mage-space/sdkКоротко
Mage TypeScript SDK — це офіційний клієнт із відкритим кодом для Mage API, опублікований як @mage-space/sdk. Установіть його командою "npm install @mage-space/sdk", задайте MAGE_API_KEY і викличте mage.run з id моделі та конфігурацією, щоб отримати готові зображення, відео чи аудіо від будь-якої з 28 моделей. Він працює на Node.js 20.19 або новішій версії, а також у будь-якому серверному середовищі з fetch, і кожна генерація оплачується в Gems.
- 20.19+Node.js
- 0Залежності під час виконання
- 28Типізовані моделі
- 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-v3', }); 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 з рекомендованою затримкою (backoff) і повертає завершений запит із result.url.
Повтори без подвійної оплати
Кожен запит містить ключ ідемпотентності. Мережеві та серверні помилки повторюються з наростаючою затримкою, а повторний запит ніколи не оплачується вдруге.
Завантаження одним викликом
Файли, завеликі для data URL, надсилаються через підписане завантаження: квиток, PUT і перевірку розміру SDK бере на себе.
Зрозумілі помилки
Відмови API містять HTTP-статус, код помилки та id запиту; невдалі або скасовані генерації й тайм-аути мають власні типи помилок.
Типи для кожної моделі
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
Голоси, музика та звукові ефекти з одного промпту
Поширені запитання
Поширені запитання
Чи можна використовувати Mage TypeScript SDK у браузері?
Чи працює TypeScript SDK з CommonJS?
Чи працює TypeScript SDK з Next.js?
Чи безкоштовні й відкриті SDK Mage?
Чи працюють нові моделі Mage зі старішою версією SDK?
Як SDK уникають подвійної оплати за повторний запит?
Чи стабільні SDK?
Скільки коштує Mage API?
Чи потрібна підписка на Mage, щоб користуватися API?
Чи можна використовувати результати API в комерційних цілях?
Створюй з Mage
Один акаунт, один баланс Gems, усі моделі. Плати лише за те, що генеруєш.