Mage SDK · TypeScript
Το Mage TypeScript SDK
Δημιούργησε εικόνες, βίντεο και ήχο από το Node.js με τυποποιημένες ρυθμίσεις για κάθε μοντέλο της Mage. Μία κλήση υποβάλλει, περιμένει και επιστρέφει το αποτέλεσμα.
npm install @mage-space/sdkΜε μια ματιά
Το Mage TypeScript SDK είναι ο επίσημος client ανοιχτού κώδικα για το Mage API, δημοσιευμένος ως @mage-space/sdk. Εγκατάστησέ το με «npm install @mage-space/sdk», όρισε το MAGE_API_KEY και κάλεσε το mage.run με ένα id μοντέλου και μια ρύθμιση, για να πάρεις έτοιμες εικόνες, βίντεο ή ήχο από οποιοδήποτε από τα 28 μοντέλα. Τρέχει σε Node.js 20.19 ή νεότερο, ή σε οποιοδήποτε περιβάλλον διακομιστή με fetch, και κάθε δημιουργία πληρώνεται σε Gems.
- 20.19+Node.js
- 0Εξαρτήσεις χρόνου εκτέλεσης
- 28Μοντέλα με τύπους
- MITΑνοιχτός κώδικας
Ρύθμιση
Εγκατάστησε το TypeScript SDK και τρέξε ένα μοντέλο
Εγκατάσταση του πακέτου
Πρόσθεσε το @mage-space/sdk στο έργο σου.
npm install @mage-space/sdkΟρισμός του κλειδιού API
Δημιούργησε ένα κλειδί στο API → API Keys στο mage.space και κάνε export. Ο client διαβάζει το MAGE_API_KEY.
export MAGE_API_KEY="mage_sk_..."Δημιουργία
Κάλεσε το run με ένα id μοντέλου και τη ρύθμισή του. Περιμένει το αποτέλεσμα και το επιστρέφει· η έξοδος βρίσκεται στο 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);
Παραδείγματα
Το TypeScript SDK στην πράξη
Κάθε παράδειγμα ξεκινά από έναν client που διαβάζει το MAGE_API_KEY.
Υποβολή τώρα, αναμονή αργότερα
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),
});Μεταφόρτωση αρχείου
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],
});Χρήση αποθηκευμένου Character
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' });Διαχείριση σφαλμάτων
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;
}
}Γιατί το SDK
Τι αναλαμβάνει το SDK για εσένα
Μία κλήση, έτοιμο πολυμέσο
Το run υποβάλλει τη δημιουργία, κάνει polling με το backoff που προτείνει το API και επιστρέφει το ολοκληρωμένο αίτημα με το result.url.
Επαναλήψεις χωρίς διπλή χρέωση
Κάθε υποβολή φέρει ένα idempotency key. Τα σφάλματα δικτύου και διακομιστή επαναλαμβάνονται με backoff και μια υποβολή που επαναλαμβάνεται δεν χρεώνεται ξανά.
Uploads με μία κλήση
Τα αρχεία που είναι πολύ μεγάλα για data URL περνούν από υπογεγραμμένο upload, με το ticket, το PUT και τον έλεγχο μεγέθους να γίνονται για σένα.
Σαφή σφάλματα
Οι απορρίψεις του API περιλαμβάνουν το HTTP status, τον κωδικό σφάλματος και το request id· οι αποτυχημένες ή ακυρωμένες δημιουργίες και τα timeouts έχουν δικούς τους τύπους σφαλμάτων.
Τυποποιημένο για κάθε μοντέλο
Τα MangoConfig, CherryConfig και τα υπόλοιπα παράγονται από την τεκμηρίωση του API, ώστε ο editor σου να συμπληρώνει πεδία και να εντοπίζει μη έγκυρες επιλογές.
Μηδενικές εξαρτήσεις
ESM χωρίς εξαρτήσεις χρόνου εκτέλεσης. Χρησιμοποιεί το fetch που είναι ενσωματωμένο στο Node.js και κάθε κλήση δέχεται ένα AbortSignal.
Αναφορά
Το TypeScript SDK με μια ματιά
Οι ίδιες μέθοδοι καλύπτουν κάθε μοντέλο· το μοντέλο είναι το πρώτο όρισμα.
| Μέθοδος | Τι κάνει |
|---|---|
| mage.run(model, config) | Υποβάλλει μια δημιουργία, περιμένει να ολοκληρωθεί και επιστρέφει το ολοκληρωμένο αίτημα. |
| mage.generate(model, config) | Υποβάλλει μια δημιουργία και επιστρέφει αμέσως το αίτημα. |
| mage.requests.get / cancel / wait | Διαβάζει, σταματά ή περιμένει ένα αίτημα με βάση το id. |
| mage.uploads.upload(data) | Ανεβάζει αρχείο έως 100 MB και επιστρέφει το URL του. |
| mage.characters / mage.references | Εμφανίζει, δημιουργεί και διαγράφει αποθηκευμένα Characters και References. |
| mage.account.get() | Το υπόλοιπο των Gems σου. |
| mage.architectures.list() | Ο ζωντανός κατάλογος μοντέλων με επιλογές και τιμές. |
Μοντέλα
Ξεκίνα με αυτά τα μοντέλα
Guava API
Φωτορεαλισμός που περνά για φωτογραφία
Mango API
Η κορυφαία οικογένεια μοντέλων εικόνας μας
Nano Banana 2 API
Καθαρό, ευανάγνωστο κείμενο, έως 4K
Cherry API
Η κορυφαία οικογένεια μοντέλων βίντεο μας
Lemon API
Όλες οι δυνατότητες βίντεο, σε πιο προσιτή τιμή
Seed Audio API
Φωνές, μουσική και ηχητικά εφέ από ένα μόνο prompt
Συχνές ερωτήσεις
Συχνές ερωτήσεις
Μπορώ να χρησιμοποιήσω το Mage TypeScript SDK στον browser;
Λειτουργεί το TypeScript SDK με CommonJS;
Λειτουργεί το TypeScript SDK με το Next.js;
Είναι τα Mage SDK δωρεάν και ανοιχτού κώδικα;
Λειτουργούν τα νέα μοντέλα της Mage με παλαιότερο SDK;
Πώς αποφεύγουν τα SDK τη διπλή χρέωση όταν ένα αίτημα επαναλαμβάνεται;
Είναι σταθερά τα SDK;
Πόσο κοστίζει το Mage API;
Χρειάζομαι συνδρομή στο Mage για να χρησιμοποιήσω το API;
Μπορώ να χρησιμοποιήσω τα αποτελέσματα του API εμπορικά;
Ξεκίνα να δημιουργείς με το Mage
Ένας λογαριασμός, ένα υπόλοιπο Gems, όλα τα μοντέλα. Πληρώνεις μόνο για ό,τι δημιουργείς.