SDK Mage · TypeScript
L'SDK TypeScript di Mage
Genera immagini, video e audio da Node.js con configurazioni tipizzate per ogni modello Mage. Una sola chiamata invia la richiesta, attende e restituisce il risultato.
npm install @mage-space/sdkIn breve
L'SDK TypeScript di Mage è il client ufficiale e open source per l'API di Mage, pubblicato come @mage-space/sdk. Installalo con "npm install @mage-space/sdk", imposta MAGE_API_KEY e chiama mage.run con un id modello e una configurazione per ottenere immagini, video o audio già pronti da uno qualsiasi dei 37 modelli. Funziona su Node.js 20.19 o successivo, o su qualsiasi runtime server con fetch, e ogni generazione si paga in Gems.
- 20.19+Node.js
- 0Dipendenze runtime
- 37Modelli tipizzati
- MITOpen source
Configurazione
Installa l'SDK TypeScript ed esegui un modello
Installa il pacchetto
Aggiungi @mage-space/sdk al tuo progetto.
npm install @mage-space/sdkImposta la tua chiave API
Crea una chiave in API → API Keys su mage.space ed esportala. Il client legge MAGE_API_KEY.
export MAGE_API_KEY="mage_sk_..."Genera
Chiama run con l'id di un modello e la sua configurazione. Attende il risultato e lo restituisce; l'output si trova 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);
Esempi
L'SDK TypeScript in pratica
Ogni esempio parte da un client che legge MAGE_API_KEY.
Invia ora, attendi dopo
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),
});Carica un file
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],
});Usa un personaggio salvato
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' });Gestisci gli errori
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;
}
}Perché l'SDK
Cosa fa l'SDK al posto tuo
Una chiamata, contenuto pronto
run invia la generazione, fa polling con il backoff consigliato dall'API e restituisce la richiesta completata con result.url.
Retry che non si pagano mai due volte
Ogni invio include una chiave di idempotenza. Gli errori di rete e del server vengono ritentati con backoff, e un invio ritentato non viene mai addebitato di nuovo.
Upload in una sola chiamata
I file troppo grandi per un data URL passano da un upload firmato, con ticket, PUT e controllo delle dimensioni gestiti al posto tuo.
Errori chiari
I rifiuti dell'API includono stato HTTP, codice di errore e ID della richiesta; generazioni fallite o annullate e timeout hanno tipi di errore dedicati.
Tipizzato per ogni modello
MangoConfig, CherryConfig e gli altri sono generati dal riferimento API, così il tuo editor completa i campi e segnala le opzioni non valide.
Zero dipendenze
ESM senza dipendenze runtime. Usa il fetch integrato in Node.js e ogni chiamata accetta un AbortSignal.
Riferimento
L'SDK TypeScript in breve
Gli stessi metodi valgono per ogni modello; il modello è il primo argomento.
| Metodo | Cosa fa |
|---|---|
| mage.run(model, config) | Invia una generazione, attende il completamento e restituisce la richiesta completata. |
| mage.generate(model, config) | Invia una generazione e restituisce subito la richiesta. |
| mage.requests.get / cancel / wait | Leggi, interrompi o attendi una richiesta tramite id. |
| mage.uploads.upload(data) | Carica un file fino a 100 MB e restituisce il suo URL. |
| mage.characters / mage.references | Elenca, crea ed elimina personaggi e riferimenti salvati. |
| mage.account.get() | Il tuo saldo di Gems. |
| mage.architectures.list() | Il catalogo dei modelli in tempo reale con opzioni e prezzi. |
Modelli
Inizia con questi modelli
API Guava
Un fotorealismo che sembra una vera fotografia
API Mango
La nostra famiglia di modelli immagine di punta
API Nano Banana 2
Testo nitido e leggibile, fino a 4K
API Cherry
La nostra famiglia di modelli video di punta
API Lemon
Tutte le funzioni video, a un prezzo più accessibile
API Seed Audio
Voci, musica ed effetti sonori da un unico prompt
FAQ
Domande frequenti
Posso usare l'SDK TypeScript di Mage nel browser?
L'SDK TypeScript funziona con CommonJS?
L'SDK TypeScript funziona con Next.js?
Gli SDK di Mage sono gratuiti e open source?
I nuovi modelli Mage funzionano con un SDK più vecchio?
Come evitano gli SDK di pagare due volte per una richiesta ripetuta?
Gli SDK sono stabili?
Quanto costa l'API di Mage?
Mi serve un abbonamento a Mage per usare l'API?
Posso usare a fini commerciali i contenuti generati con l'API?
Inizia a creare con Mage
Un solo account, un solo saldo di Gems, tutti i modelli. Paghi solo ciò che generi.