Zum Inhalt springen

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/sdk

Auf 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

  1. Paket installieren

    Füge @mage-space/sdk zu deinem Projekt hinzu.

    npm install @mage-space/sdk
  2. API-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_..."
  3. 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.

MethodeWas 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 / waitEine 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.referencesGespeicherte 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

  • Bild · ab 37 Gems

    Guava API

    Fotorealismus, der als Foto durchgeht

  • Bild · ab 42 Gems

    Mango API

    Unsere Flaggschiff-Bildfamilie

  • Bild · ab 51 Gems

    Nano Banana 2 API

    Gestochen scharfer, lesbarer Text, bis zu 4K

  • Video · ab 618 Gems

    Cherry API

    Unsere Flaggschiff-Videofamilie

  • Video · ab 245 Gems

    Lemon API

    Alle Video-Funktionen zu einem fairen Preis

  • Audio · ab 19 Gems

    Seed Audio API

    Stimmen, Musik und Soundeffekte aus einem Prompt

FAQ

Häufig gestellte Fragen

Kann ich das Mage TypeScript-SDK im Browser verwenden?
Nein. Ein API-Key verbraucht deine Gems, deshalb solltest du ihn nur auf deinen Servern aufbewahren. Die API sendet keine CORS-Header, daher können Browser sie nicht direkt aufrufen. Ruf stattdessen dein eigenes Backend auf und lass es das SDK verwenden.
Funktioniert das TypeScript-SDK mit CommonJS?
Das Paket ist nur als ESM verfügbar. Ab Node.js 20.19 kannst du es aber auch per require() aus CommonJS laden.
Funktioniert das TypeScript-SDK mit Next.js?
Ja, in Servercode wie Route Handlers und Server Actions. Das SDK basiert auf fetch und Standard-Web-APIs wie AbortSignal, daher sollten auch andere Server-Laufzeitumgebungen mit fetch funktionieren, auch wenn die CI es mit Node.js testet.
Sind die Mage SDKs kostenlos und Open Source?
Ja. Die SDKs und die ComfyUI-Nodes stehen auf GitHub unter der MIT-Lizenz, und die Installation ist kostenlos. Du zahlst nur für die Generierungen, die du ausführst – in Gems, zum jeweils angegebenen Preis des Modells.
Funktionieren neue Mage-Modelle mit einem älteren SDK?
Ja. Übergib die ID des neuen Modells als String, dann läuft es. Das SDK prüft die Konfiguration anhand der Felder, die alle Modelle gemeinsam haben. Ein Bot aktualisiert die Typen, sobald sich die API-Referenz ändert, sodass neue Modelle mit eigenen Typen im nächsten Release erscheinen.
Wie verhindern die SDKs, dass ich bei einer wiederholten Anfrage doppelt zahle?
Jede Übermittlung enthält einen Idempotency-Key. Das SDK erzeugt pro Aufruf einen neuen Key und verwendet ihn erneut, wenn es diesen Aufruf selbst wiederholt. So gibt eine wiederholte Übermittlung die ursprüngliche Anfrage zurück und es fallen keine Kosten an.
Sind die SDKs stabil?
Sie befinden sich als 0.x in der Beta, daher kann sich mit einer Minor-Version noch etwas ändern. Die API selbst wird separat versioniert und bleibt innerhalb von v1 stabil.
Was kostet die Mage API?
Es gibt kein Abo und keine monatliche Gebühr. Jede Generierung wird in Gems zum angegebenen Preis des Modells bezahlt, und 1.000 Gems kosten im Standardpaket 1 $. Jede Modellseite nennt den Preis bei Standardeinstellungen, und jede Antwort enthält die genaue Abrechnung. Eine fehlgeschlagene Generierung wird erstattet; eine, die von der Inhaltsrichtlinie von Mage blockiert wird, nicht. Eine Anfrage, die dein Guthaben nicht deckt, wird abgelehnt, bevor etwas berechnet wird.
Brauche ich eine Mage-Mitgliedschaft, um die API zu nutzen?
Nein. Die API läuft ausschließlich über Gems. Mitgliedschaftspläne und die damit verbundene unbegrenzte Generierung in der App gelten nicht für API-Anfragen. Für dein Konto ist zuerst eine erfolgreiche Zahlung nötig, egal ob ein Gem-Paket oder ein Plan. Gems aus dem Anmeldebonus funktionieren nur in der Mage-App.
Kann ich API-Ergebnisse kommerziell nutzen?
Ja. Inhalte, die du mit Mage erstellst, auch über die API und den MCP-Server, kannst du kommerziell nutzen. Eine Namensnennung freut uns, ist aber nicht erforderlich.

Starte jetzt mit Mage

Ein Konto, ein Gems-Guthaben, alle Modelle. Du zahlst nur für das, was du generierst.

CharactersCommunity