Mage SDK · TypeScript
A Mage TypeScript SDK
Generálj képeket, videókat és hangot Node.js-ből, minden Mage modellhez típusos konfigurációval. Egyetlen hívás beküld, megvárja és visszaadja az eredményt.
npm install @mage-space/sdkDióhéjban
A Mage TypeScript SDK az API hivatalos, nyílt forráskódú kliense, @mage-space/sdk néven érhető el. Telepítsd az "npm install @mage-space/sdk" paranccsal, állítsd be a MAGE_API_KEY változót, és hívd meg a mage.run függvényt egy modellazonosítóval és egy konfigurációval, hogy kész képeket, videókat vagy hangot kapj a 28 modell bármelyikéből. Node.js 20.19 vagy újabb verzión, illetve bármely fetch-t támogató szerverkörnyezetben fut, és minden generálásért Gemekkel fizetsz.
- 20.19+Node.js
- 0Futásidejű függőségek
- 28Típusos modellek
- MITNyílt forráskód
Beállítás
Telepítsd a TypeScript SDK-t, és futtass egy modellt
Csomag telepítése
Add hozzá a @mage-space/sdk csomagot a projektedhez.
npm install @mage-space/sdkAPI-kulcs beállítása
Hozz létre egy kulcsot a mage.space oldalon az API → API Keys menüben, és exportáld. A kliens a MAGE_API_KEY változót olvassa.
export MAGE_API_KEY="mage_sk_..."Generálás
Hívd meg a run metódust egy modellazonosítóval és a hozzá tartozó konfigurációval. Megvárja az eredményt, és visszaadja; a kimenet a result.url címen érhető el.
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éldák
A TypeScript SDK a gyakorlatban
Minden példa egy olyan kliensből indul, amely a MAGE_API_KEY változót olvassa.
Beküldés most, várakozás később
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),
});Fájl feltöltése
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],
});Mentett karakter használata
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' });Hibakezelés
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;
}
}Miért az SDK
Amit az SDK elintéz helyetted
Egy hívás, kész média
A run elküldi a generálást, az API által javasolt visszalépéses időzítéssel lekérdezi az állapotot, és a kész kéréssel tér vissza result.url értékkel.
Újrapróbálkozás kétszeri fizetés nélkül
Minden beküldés idempotencia-kulcsot visz magával. A hálózati és szerverhibáknál visszalépéses időzítéssel újrapróbálkozik, az újra elküldött kérésért pedig soha nem számolunk fel újabb díjat.
Feltöltés egy hívással
A data URL-hez túl nagy fájlok aláírt feltöltéssel mennek át, a jegyet, a PUT kérést és a méretellenőrzést pedig az SDK intézi helyetted.
Érthető hibák
Az API elutasításai tartalmazzák a HTTP-státuszt, a hibakódot és a kérésazonosítót; a sikertelen vagy megszakított generálásoknak és az időtúllépéseknek saját hibatípusuk van.
Minden modellhez típusozva
A MangoConfig, a CherryConfig és a többi az API-dokumentációból készül, így a szerkesztőd kiegészíti a mezőket, és kiszűri az érvénytelen beállításokat.
Nulla függőség
ESM futásidejű függőségek nélkül. A Node.js beépített fetch-ét használja, és minden hívás fogad egy AbortSignalt.
Referencia
A TypeScript SDK dióhéjban
Ugyanazok a metódusok minden modellt lefednek; a modell az első argumentum.
| Metódus | Mit csinál |
|---|---|
| mage.run(model, config) | Beküld egy generálást, megvárja, és visszaadja a befejezett kérést. |
| mage.generate(model, config) | Beküld egy generálást, és azonnal visszaadja a kérést. |
| mage.requests.get / cancel / wait | Kérés lekérdezése, leállítása vagy megvárása azonosító alapján. |
| mage.uploads.upload(data) | Legfeljebb 100 MB-os fájl feltöltése, az URL-jét adja vissza. |
| mage.characters / mage.references | Mentett karakterek és referenciák listázása, létrehozása és törlése. |
| mage.account.get() | A Gem-egyenleged. |
| mage.architectures.list() | Az élő modellkatalógus beállításokkal és árakkal. |
Modellek
Kezdd ezekkel a modellekkel
Guava API
Fotórealizmus, ami fényképnek is elmegy
Mango API
Zászlóshajó képmodellcsaládunk
Nano Banana 2 API
Éles, jól olvasható szöveg, akár 4K-ban
Cherry API
Zászlóshajó videómodellcsaládunk
Lemon API
Minden videófunkció, barátibb áron
Seed Audio API
Hangok, zene és hangeffektek egyetlen promptból
GYIK
Gyakran ismételt kérdések
Használhatom a Mage TypeScript SDK-t böngészőben?
Működik a TypeScript SDK CommonJS-sel?
Működik a TypeScript SDK a Next.js-sel?
Ingyenesek és nyílt forráskódúak a Mage SDK-k?
Működnek az új Mage modellek régebbi SDK-val?
Hogyan kerüli el az SDK, hogy kétszer fizess egy újrapróbált kérésért?
Stabilak az SDK-k?
Mennyibe kerül a Mage API?
Kell Mage-tagság az API használatához?
Felhasználhatom kereskedelmi célra az API kimeneteit?
Kezdj el építeni a Mage-dzsel
Egy fiók, egy Gems-egyenleg, az összes modell. Csak azért fizetsz, amit legenerálsz.