Mage SDK · TypeScript
Das Mage TypeScript-SDK
Generiere Bilder, Videos und Audio mit Node.js und typisierten Konfigurationen für jedes Mage-Modell. Ein Aufruf sendet die Anfrage, wartet und liefert das Ergebnis.
npm install @mage-space/sdkAuf einen Blick
Das Mage TypeScript SDK ist der offizielle Open-Source-Client für die Mage API und wird als @mage-space/sdk veröffentlicht. Installiere es mit "npm install @mage-space/sdk", setze MAGE_API_KEY und rufe mage.run mit einer Modell-ID und einer Konfiguration auf, um fertige Bilder, Videos oder Audio von einem der 37 Modelle zu erhalten. Es läuft mit Node.js 20.19 oder neuer oder in jeder Server-Laufzeitumgebung mit fetch, und jede Generierung wird in Gems bezahlt.
- 20.19+Node.js
- 0Laufzeitabhängigkeiten
- 37Typisierte Modelle
- MITOpen Source
Einrichtung
TypeScript-SDK installieren und ein Modell ausführen
Paket installieren
Füge @mage-space/sdk zu deinem Projekt hinzu.
npm install @mage-space/sdkAPI-Key festlegen
Erstelle auf mage.space unter API → API Keys einen Key und exportiere ihn. Der Client liest MAGE_API_KEY.
export MAGE_API_KEY="mage_sk_..."Generieren
Rufe run mit einer Modell-ID und der zugehörigen Konfiguration auf. Es wartet auf das Ergebnis und gibt es zurück; die Ausgabe findest du unter 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);
Beispiele
Das TypeScript-SDK in der Praxis
Jedes Beispiel beginnt mit einem Client, der MAGE_API_KEY liest.
Jetzt senden, später warten
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),
});Datei hochladen
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],
});Gespeicherten Character verwenden
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' });Fehler behandeln
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;
}
}Warum das SDK
Was das SDK für dich übernimmt
Ein Aufruf, fertiges Medium
run sendet die Generierung ab, fragt mit dem von der API empfohlenen Backoff den Status ab und liefert die abgeschlossene Anfrage mit result.url zurück.
Wiederholungen ohne doppelte Kosten
Jede Anfrage enthält einen Idempotenzschlüssel. Netzwerk- und Serverfehler werden mit Backoff wiederholt, und eine wiederholte Anfrage wird nie erneut berechnet.
Uploads in einem Aufruf
Dateien, die für eine Data-URL zu groß sind, laufen über einen signierten Upload. Ticket, PUT und Größenprüfung übernehmen wir für dich.
Klare Fehlermeldungen
Ablehnungen der API enthalten HTTP-Status, Fehlercode und Request-ID; fehlgeschlagene oder abgebrochene Generierungen und Timeouts haben eigene Fehlertypen.
Typisiert für jedes Modell
MangoConfig, CherryConfig und alle weiteren werden aus der API-Referenz generiert, sodass dein Editor Felder vervollständigt und ungültige Optionen erkennt.
Keine Abhängigkeiten
ESM ohne Laufzeitabhängigkeiten. Es nutzt das in Node.js integrierte fetch, und jeder Aufruf akzeptiert ein AbortSignal.
Referenz
Das TypeScript-SDK im Überblick
Dieselben Methoden decken jedes Modell ab; das Modell ist das erste Argument.
| Methode | Was es macht |
|---|---|
| mage.run(model, config) | Sendet eine Generierung, wartet darauf und gibt die abgeschlossene Anfrage zurück. |
| mage.generate(model, config) | Sendet eine Generierung und gibt die Anfrage sofort zurück. |
| mage.requests.get / cancel / wait | Eine Anfrage per ID abrufen, stoppen oder auf sie warten. |
| mage.uploads.upload(data) | Lädt eine Datei mit bis zu 100 MB hoch und gibt ihre URL zurück. |
| mage.characters / mage.references | Gespeicherte Characters und References auflisten, erstellen und löschen. |
| mage.account.get() | Dein Gems-Guthaben. |
| mage.architectures.list() | Der aktuelle Modellkatalog mit Optionen und Preisen. |
Modelle
Starte mit diesen Modellen
Guava API
Fotorealismus, der als Foto durchgeht
Mango API
Unsere Flaggschiff-Bildfamilie
Nano Banana 2 API
Gestochen scharfer, lesbarer Text, bis zu 4K
Cherry API
Unsere Flaggschiff-Videofamilie
Lemon API
Alle Video-Funktionen zu einem fairen Preis
Seed Audio API
Stimmen, Musik und Soundeffekte aus einem Prompt
FAQ
Häufig gestellte Fragen
Kann ich das Mage TypeScript-SDK im Browser verwenden?
Funktioniert das TypeScript-SDK mit CommonJS?
Funktioniert das TypeScript-SDK mit Next.js?
Sind die Mage SDKs kostenlos und Open Source?
Funktionieren neue Mage-Modelle mit einem älteren SDK?
Wie verhindern die SDKs, dass ich bei einer wiederholten Anfrage doppelt zahle?
Sind die SDKs stabil?
Was kostet die Mage API?
Brauche ich eine Mage-Mitgliedschaft, um die API zu nutzen?
Kann ich API-Ergebnisse kommerziell nutzen?
Starte jetzt mit Mage
Ein Konto, ein Gems-Guthaben, alle Modelle. Du zahlst nur für das, was du generierst.