Mage SDK · TypeScript
Mage TypeScript SDK
Generuj obrázky, video a audio z Node.js s typovanými konfiguracemi pro každý model Mage. Jedno volání odešle, počká a vrátí výsledek.
npm install @mage-space/sdkStručně
Mage TypeScript SDK je oficiální open source klient pro Mage API, publikovaný jako @mage-space/sdk. Nainstaluj ho příkazem „npm install @mage-space/sdk“, nastav MAGE_API_KEY a zavolej mage.run s id modelu a konfigurací – získáš hotové obrázky, video nebo audio z kteréhokoli z 28 modelů. Běží na Node.js 20.19 nebo novějším, případně v jakémkoli serverovém runtime s fetch, a každé generování se platí v Gems.
- 20.19+Node.js
- 0Závislosti za běhu
- 28Typované modely
- MITOpen source
Nastavení
Nainstaluj TypeScript SDK a spusť model
Nainstaluj balíček
Přidej @mage-space/sdk do svého projektu.
npm install @mage-space/sdkNastav API klíč
Vytvoř klíč v API → API Keys na mage.space a exportuj ho. Klient čte MAGE_API_KEY.
export MAGE_API_KEY="mage_sk_..."Generuj
Zavolej run s id modelu a jeho konfigurací. Počká na výsledek a vrátí ho; výstup najdeš v 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);
Příklady
TypeScript SDK v praxi
Každý příklad vychází z klienta, který čte MAGE_API_KEY.
Odešli hned, počkej později
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),
});Nahraj soubor
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],
});Použij uloženou postavu
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' });Ošetři chyby
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;
}
}Proč SDK
Co SDK vyřeší za tebe
Jedno volání, hotová média
run odešle generování, dotazuje se na stav s odstupy doporučenými API a vrátí dokončený požadavek s result.url.
Opakování, která nikdy neúčtují dvakrát
Každý požadavek nese idempotentní klíč. Při chybách sítě a serveru se pokus opakuje s postupně rostoucími odstupy a opakovaný požadavek se nikdy nezpoplatní znovu.
Nahrávání jedním voláním
Soubory příliš velké pro data URL se nahrávají přes podepsané nahrání, o tiket, PUT i kontrolu velikosti se postaráme za tebe.
Srozumitelné chyby
Odmítnutí ze strany API obsahují HTTP status, kód chyby a ID požadavku; neúspěšná nebo zrušená generování a vypršení časového limitu mají vlastní typy chyb.
Typované pro každý model
MangoConfig, CherryConfig a další se generují z API reference, takže editor doplňuje pole a zachytí neplatné volby.
Nula závislostí
ESM bez závislostí za běhu. Využívá fetch zabudovaný v Node.js a každé volání přijímá AbortSignal.
Reference
TypeScript SDK ve zkratce
Stejné metody pokrývají každý model; model je první argument.
| Metoda | Co dělá |
|---|---|
| mage.run(model, config) | Odešle generování, počká na něj a vrátí dokončený požadavek. |
| mage.generate(model, config) | Odešle generování a okamžitě vrátí požadavek. |
| mage.requests.get / cancel / wait | Načte požadavek podle id, zastaví ho, nebo na něj počká. |
| mage.uploads.upload(data) | Nahraje soubor do velikosti 100 MB a vrátí jeho URL. |
| mage.characters / mage.references | Zobrazí, vytvoří a smaže uložené postavy a reference. |
| mage.account.get() | Tvůj zůstatek Gems. |
| mage.architectures.list() | Aktuální katalog modelů s možnostmi a cenami. |
Modely
Začni s těmito modely
Guava API
Fotorealismus, který projde jako fotografie
Mango API
Naše vlajková řada obrázkových modelů
Nano Banana 2 API
Ostrý, čitelný text až do 4K
Cherry API
Naše vlajková řada video modelů
Lemon API
Všechny video funkce za příznivější cenu
Seed Audio API
Hlasy, hudba a zvukové efekty z jednoho promptu
Časté dotazy
Často kladené otázky
Můžu Mage TypeScript SDK používat v prohlížeči?
Funguje TypeScript SDK s CommonJS?
Funguje TypeScript SDK s Next.js?
Jsou Mage SDK zdarma a open source?
Fungují nové modely Mage i se starším SDK?
Jak SDK zabrání dvojímu zaplacení za opakovaný požadavek?
Jsou SDK stabilní?
Kolik stojí Mage API?
Potřebuji k používání API členství v Mage?
Můžu výstupy z API používat komerčně?
Začni tvořit s Mage
Jeden účet, jeden zůstatek Gems, všechny modely. Platíš jen za to, co vygeneruješ.