SDK Mage · TypeScript
Le SDK TypeScript de Mage
Génère des images, des vidéos et de l’audio depuis Node.js avec des configurations typées pour chaque modèle Mage. Un seul appel envoie la requête, attend et renvoie le résultat.
npm install @mage-space/sdkEn un coup d’œil
Le SDK TypeScript de Mage est le client officiel open source de l'API Mage, publié sous le nom @mage-space/sdk. Installe-le avec « npm install @mage-space/sdk », définis MAGE_API_KEY, puis appelle mage.run avec un id de modèle et une config pour obtenir des images, des vidéos ou de l'audio terminés, avec n'importe lequel des 37 modèles. Il fonctionne avec Node.js 20.19 ou version ultérieure, ou n'importe quel runtime serveur avec fetch, et chaque génération se paie en Gems.
- 20.19+Node.js
- 0Dépendances d’exécution
- 37Modèles typés
- MITOpen source
Configuration
Installe le SDK TypeScript et lance un modèle
Installer le paquet
Ajoute @mage-space/sdk à ton projet.
npm install @mage-space/sdkDéfinir ta clé d’API
Crée une clé dans API → API Keys sur mage.space et exporte-la. Le client lit MAGE_API_KEY.
export MAGE_API_KEY="mage_sk_..."Générer
Appelle run avec un identifiant de modèle et sa configuration. Il attend le résultat et le renvoie ; le fichier généré se trouve dans 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);
Exemples
Le SDK TypeScript en pratique
Chaque exemple part d’un client qui lit MAGE_API_KEY.
Envoyer maintenant, attendre plus tard
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),
});Téléverser un fichier
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],
});Utiliser un personnage enregistré
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' });Gérer les erreurs
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;
}
}Pourquoi le SDK
Ce que le SDK gère pour toi
Un appel, un média prêt
run envoie la génération, interroge l'API avec le backoff qu'elle recommande et renvoie la requête terminée avec result.url.
Des nouvelles tentatives sans double paiement
Chaque envoi porte une clé d'idempotence. Les erreurs réseau et serveur sont retentées avec backoff, et un envoi retenté n'est jamais facturé deux fois.
Uploads en un appel
Les fichiers trop volumineux pour une data URL passent par un upload signé, avec le ticket, le PUT et la vérification de taille gérés pour toi.
Des erreurs claires
Les refus de l'API incluent leur statut HTTP, leur code d'erreur et leur identifiant de requête ; les générations échouées ou annulées et les délais dépassés ont leurs propres types d'erreur.
Typé pour chaque modèle
MangoConfig, CherryConfig et les autres sont générés à partir de la référence de l’API : ton éditeur complète les champs et repère les options invalides.
Zéro dépendance
ESM sans aucune dépendance d’exécution. Il utilise le fetch intégré à Node.js, et chaque appel accepte un AbortSignal.
Référence
Le SDK TypeScript en un coup d’œil
Les mêmes méthodes couvrent tous les modèles ; le modèle est le premier argument.
| Méthode | Ce qu'il fait |
|---|---|
| mage.run(model, config) | Envoie une génération, attend son résultat et renvoie la requête terminée. |
| mage.generate(model, config) | Envoie une génération et renvoie aussitôt la requête. |
| mage.requests.get / cancel / wait | Lit, arrête ou attend une requête à partir de son identifiant. |
| mage.uploads.upload(data) | Téléverse un fichier de 100 Mo maximum et renvoie son URL. |
| mage.characters / mage.references | Liste, crée et supprime les personnages et références enregistrés. |
| mage.account.get() | Ton solde de Gems. |
| mage.architectures.list() | Le catalogue des modèles en temps réel, avec options et prix. |
Modèles
Commence avec ces modèles
API Guava
Un photoréalisme digne d'une vraie photo
API Mango
Notre famille d'images phare
API Nano Banana 2
Texte net et lisible, jusqu'en 4K
API Cherry
Notre famille de vidéos phare
API Lemon
Toutes les fonctions vidéo, à un prix plus doux
API Seed Audio
Voix, musique et effets sonores à partir d'un seul prompt
FAQ
Questions fréquentes
Puis-je utiliser le SDK TypeScript de Mage dans le navigateur ?
Le SDK TypeScript fonctionne-t-il avec CommonJS ?
Le SDK TypeScript fonctionne-t-il avec Next.js ?
Les SDK Mage sont-ils gratuits et open source ?
Les nouveaux modèles Mage fonctionnent-ils avec un ancien SDK ?
Comment les SDK évitent-ils de payer deux fois une requête renvoyée ?
Les SDK sont-ils stables ?
Combien coûte l'API Mage ?
Faut-il un abonnement Mage pour utiliser l'API ?
Puis-je utiliser les résultats de l'API à des fins commerciales ?
Lance-toi avec Mage
Un seul compte, un seul solde de Gems, tous les modèles. Ne paie que ce que tu génères.