SDK Mage · TypeScript
SDK-ul Mage pentru TypeScript
Generează imagini, video și audio din Node.js, cu configurații tipizate pentru fiecare model Mage. Un singur apel trimite cererea, așteaptă și returnează rezultatul.
npm install @mage-space/sdkPe scurt
SDK-ul Mage pentru TypeScript este clientul oficial open source pentru API-ul Mage, publicat ca @mage-space/sdk. Instalează-l cu „npm install @mage-space/sdk”, setează MAGE_API_KEY și apelează mage.run cu un id de model și o configurație ca să primești imagini, video sau audio gata făcute de la oricare dintre cele 28 de modele. Rulează pe Node.js 20.19 sau mai nou, ori pe orice runtime de server cu fetch, iar fiecare generare se plătește în Gems.
- 20.19+Node.js
- 0Dependențe la rulare
- 28Modele tipizate
- MITOpen source
Configurare
Instalează SDK-ul TypeScript și rulează un model
Instalează pachetul
Adaugă @mage-space/sdk în proiectul tău.
npm install @mage-space/sdkSetează cheia API
Creează o cheie în API → API Keys pe mage.space și exportă-o. Clientul citește MAGE_API_KEY.
export MAGE_API_KEY="mage_sk_..."Generează
Apelează run cu un id de model și configurația lui. Așteaptă rezultatul și îl returnează; fișierul generat se află la 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);
Exemple
SDK-ul TypeScript în practică
Fiecare exemplu pornește de la un client care citește MAGE_API_KEY.
Trimite acum, așteaptă mai târziu
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),
});Încarcă un fișier
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],
});Folosește un personaj salvat
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' });Gestionează erorile
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;
}
}De ce SDK-ul
Ce face SDK-ul pentru tine
Un apel, conținut media gata
run trimite cererea de generare, face polling cu backoff-ul recomandat de API și se rezolvă cu cererea finalizată, împreună cu result.url.
Reîncercări care nu se plătesc de două ori
Fiecare trimitere poartă o cheie de idempotență. Erorile de rețea și de server sunt reîncercate cu backoff, iar o trimitere reîncercată nu este taxată niciodată a doua oară.
Încărcări dintr-un singur apel
Fișierele prea mari pentru un URL de date trec printr-o încărcare semnată, iar tichetul, PUT-ul și verificarea dimensiunii sunt gestionate pentru tine.
Erori clare
Refuzurile API includ statusul HTTP, codul de eroare și ID-ul cererii; generările eșuate sau anulate și expirările de timp au propriile tipuri de erori.
Tipizat pentru fiecare model
MangoConfig, CherryConfig și celelalte sunt generate din referința API, așa că editorul îți completează câmpurile și semnalează opțiunile nevalide.
Zero dependențe
ESM fără dependențe la rulare. Folosește fetch-ul integrat în Node.js, iar fiecare apel acceptă un AbortSignal.
Referință
SDK-ul TypeScript pe scurt
Aceleași metode acoperă toate modelele; modelul este primul argument.
| Metodă | Ce face |
|---|---|
| mage.run(model, config) | Trimite o generare, așteaptă finalizarea ei și returnează cererea completă. |
| mage.generate(model, config) | Trimite o generare și returnează imediat cererea. |
| mage.requests.get / cancel / wait | Citește, oprește sau așteaptă o cerere după id. |
| mage.uploads.upload(data) | Încarcă un fișier de până la 100 MB și returnează URL-ul lui. |
| mage.characters / mage.references | Listează, creează și șterge personaje și referințe salvate. |
| mage.account.get() | Soldul tău de Gems. |
| mage.architectures.list() | Catalogul de modele actualizat, cu opțiuni și prețuri. |
Modele
Începe cu aceste modele
API Guava
Fotorealism care trece drept fotografie
API Mango
Familia noastră principală de modele de imagine
API Nano Banana 2
Text clar și lizibil, până la 4K
API Cherry
Familia noastră principală de modele video
API Lemon
Toate funcțiile video, la un preț mai prietenos
API Seed Audio
Voci, muzică și efecte sonore dintr-un singur prompt
Întrebări frecvente
Întrebări frecvente
Pot folosi SDK-ul Mage pentru TypeScript în browser?
Funcționează SDK-ul TypeScript cu CommonJS?
Funcționează SDK-ul TypeScript cu Next.js?
Sunt SDK-urile Mage gratuite și open source?
Funcționează modelele Mage noi cu un SDK mai vechi?
Cum evită SDK-urile să plătești de două ori pentru o cerere reîncercată?
Sunt SDK-urile stabile?
Cât costă API-ul Mage?
Am nevoie de un abonament Mage ca să folosesc API-ul?
Pot folosi rezultatele din API în scop comercial?
Începe să construiești cu Mage
Un singur cont, un singur sold de Gems, toate modelele. Plătești doar pentru ce generezi.