Mage SDK · TypeScript
De Mage TypeScript SDK
Genereer afbeeldingen, video en audio vanuit Node.js met getypeerde configs voor elk Mage-model. Eén aanroep verstuurt, wacht en geeft het resultaat terug.
npm install @mage-space/sdkIn één oogopslag
De Mage TypeScript SDK is de officiële open-sourceclient voor de Mage API, gepubliceerd als @mage-space/sdk. Installeer hem met "npm install @mage-space/sdk", stel MAGE_API_KEY in en roep mage.run aan met een model-id en een config om kant-en-klare afbeeldingen, video of audio te krijgen van elk van de 37 modellen. Hij draait op Node.js 20.19 of nieuwer, of op elke serveromgeving met fetch, en elke generatie betaal je in Gems.
- 20.19+Node.js
- 0Runtime-afhankelijkheden
- 37Getypeerde modellen
- MITOpen source
Instellen
Installeer de TypeScript SDK en draai een model
Installeer het pakket
Voeg @mage-space/sdk toe aan je project.
npm install @mage-space/sdkStel je API-sleutel in
Maak een sleutel aan via API → API Keys op mage.space en exporteer die. De client leest MAGE_API_KEY.
export MAGE_API_KEY="mage_sk_..."Genereer
Roep run aan met een model-id en de bijbehorende config. De functie wacht op het resultaat en geeft het terug; de output staat in 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);
Voorbeelden
De TypeScript SDK in de praktijk
Elk voorbeeld begint met een client die MAGE_API_KEY leest.
Nu versturen, later wachten
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),
});Een bestand uploaden
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],
});Een opgeslagen personage gebruiken
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' });Fouten afhandelen
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;
}
}Waarom de SDK
Wat de SDK voor je regelt
Eén aanroep, kant-en-klare media
run verstuurt de generatie, pollt met de backoff die de API aanbeveelt en levert de voltooide aanvraag op met result.url.
Nieuwe pogingen zonder dubbel te betalen
Elke aanvraag heeft een idempotentiesleutel. Netwerkfouten en serverfouten worden met backoff opnieuw geprobeerd en een opnieuw verstuurde aanvraag wordt nooit nogmaals in rekening gebracht.
Uploads in één aanroep
Bestanden die te groot zijn voor een data-URL gaan via een ondertekende upload. Het ticket, de PUT en de groottecontrole worden voor je afgehandeld.
Duidelijke foutmeldingen
Weigeringen van de API bevatten hun HTTP-status, foutcode en aanvraag-ID. Mislukte of geannuleerde generaties en time-outs hebben elk hun eigen fouttype.
Getypeerd voor elk model
MangoConfig, CherryConfig en de rest worden gegenereerd uit de API-referentie, zodat je editor velden aanvult en ongeldige opties herkent.
Geen afhankelijkheden
ESM zonder runtime-afhankelijkheden. Hij gebruikt de fetch die in Node.js zit ingebouwd, en elke aanroep accepteert een AbortSignal.
Referentie
De TypeScript SDK in één oogopslag
Dezelfde methoden gelden voor elk model; het model is het eerste argument.
| Methode | Wat het doet |
|---|---|
| mage.run(model, config) | Verstuur een generatie, wacht erop en geef het voltooide verzoek terug. |
| mage.generate(model, config) | Verstuur een generatie en geef het verzoek direct terug. |
| mage.requests.get / cancel / wait | Een verzoek opvragen, stoppen of erop wachten via id. |
| mage.uploads.upload(data) | Upload een bestand van maximaal 100 MB en krijg de URL terug. |
| mage.characters / mage.references | Opgeslagen personages en referenties weergeven, aanmaken en verwijderen. |
| mage.account.get() | Je Gems-saldo. |
| mage.architectures.list() | De actuele modelcatalogus met opties en prijzen. |
Modellen
Begin met deze modellen
Guava API
Fotorealisme dat voor een echte foto doorgaat
Mango API
Onze vlaggenschip-afbeeldingsfamilie
Nano Banana 2 API
Scherpe, leesbare tekst, tot 4K
Cherry API
Onze vlaggenschip-videofamilie
Lemon API
Alle videofuncties, tegen een vriendelijkere prijs
Seed Audio API
Stemmen, muziek en geluidseffecten vanuit één prompt
FAQ
Veelgestelde vragen
Kan ik de Mage TypeScript SDK in de browser gebruiken?
Werkt de TypeScript SDK met CommonJS?
Werkt de TypeScript SDK met Next.js?
Zijn de Mage SDK's gratis en open source?
Werken nieuwe Mage-modellen met een oudere SDK?
Hoe voorkomen de SDK's dat je twee keer betaalt voor een opnieuw verzonden verzoek?
Zijn de SDK's stabiel?
Hoeveel kost de Mage API?
Heb ik een Mage-lidmaatschap nodig om de API te gebruiken?
Mag ik API-uitvoer commercieel gebruiken?
Begin met bouwen met Mage
Eén account, één Gems-saldo, alle modellen. Je betaalt alleen voor wat je genereert.