Una chiamata, contenuto pronto
run invia la generazione, fa polling con il backoff consigliato dall'API e restituisce la richiesta completata con result.url.
In breve
Mage pubblica SDK open source per la sua API: @mage-space/sdk su npm per TypeScript e JavaScript, mage-space su PyPI per Python e il pacchetto di nodi comfyui-mage per ComfyUI. Ognuno racchiude l'API REST con configurazioni tipizzate per tutti i 28 modelli, polling automatico, retry idempotenti e upload.
3
SDK e integrazioni
28
Modelli tipizzati
MIT
Open source
$0
Per installare
Scegli il tuo
SDK e integrazioni
npm install @mage-space/sdk
SDK TypeScript
Genera immagini, video e audio da Node.js con configurazioni tipizzate per ogni modello di Mage. Una sola chiamata invia, attende e restituisce il risultato.
pip install mage-space
SDK Python
Genera immagini, video e audio da Python con client sincroni e asyncio e configurazioni tipizzate per ogni modello di Mage.
comfy node install comfyui-mage
Mage per ComfyUI
Mango, Cherry, Seed Audio e tutti gli altri modelli di Mage come nodi ComfyUI. Nessuna GPU, nessun download di modelli.
Guida rapida
La tua prima generazione con un SDK
Installa il pacchetto, esporta MAGE_API_KEY ed esegui un modello.
TypeScript
// npm install @mage-space/sdk
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);Python
# pip install mage-space
from mage_space import Mage
mage = Mage() # reads MAGE_API_KEY
request = mage.run("mango", {
"prompt": "Editorial portrait in soft daylight, 35mm film look",
"aspect_ratio": "4:5",
"model_id": "mango-v3",
})
print(request["result"]["url"])Già incluso
Cosa gestisce ogni SDK al posto tuo
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.
Pacchetti
Dove trovarli
| SDK | Pacchetto | Installazione | Codice sorgente |
|---|---|---|---|
| SDK TypeScript | @mage-space/sdk | npm install @mage-space/sdk | GitHub |
| SDK Python | mage-space | pip install mage-space | GitHub |
| Mage per ComfyUI | comfyui-mage | comfy node install comfyui-mage | GitHub |
FAQ
Domande frequenti
Gli SDK di Mage sono gratuiti e open source?
Sì. Gli SDK e i nodi ComfyUI hanno licenza MIT su GitHub e installarli è gratis. Paghi solo le generazioni che esegui, in Gems, al prezzo indicato per ogni modello.
I nuovi modelli Mage funzionano con un SDK più vecchio?
Sì. Passa l'id del nuovo modello come stringa e il modello viene eseguito: l'SDK controlla la configurazione in base ai campi che tutti i modelli hanno in comune. Un bot aggiorna i tipi ogni volta che cambia il riferimento API, quindi i nuovi modelli arrivano con i propri tipi nella release successiva.
Come evitano gli SDK di pagare due volte per una richiesta ripetuta?
Ogni invio include una Idempotency-Key. L'SDK crea una nuova chiave per ogni chiamata e la riutilizza quando ripete quella stessa chiamata, così un invio ripetuto restituisce la richiesta originale e non addebita nulla.
Gli SDK sono stabili?
Sono in beta alla versione 0.x, quindi una versione minor può ancora modificarli. L'API ha un versionamento separato e resta stabile all'interno della v1.
Quanto costa l'API di Mage?
Non ci sono abbonamenti né canoni mensili. Ogni generazione si paga in Gems al prezzo indicato per il suo modello, e 1.000 Gems costano 1 $ con il pacchetto standard. La pagina di ogni modello riporta il prezzo con le impostazioni predefinite e ogni risposta indica l'addebito esatto. Se una generazione fallisce, viene rimborsata; se la blocca la content policy di Mage, no. Una richiesta che il tuo saldo non copre viene rifiutata prima di qualsiasi addebito.
Mi serve un abbonamento a Mage per usare l'API?
No. L'API funziona solo con i Gems. I piani di abbonamento e la generazione illimitata nell'app non valgono per le richieste API, quindi qualsiasi account Mage con dei Gems può usarla.
Posso usare a fini commerciali i contenuti generati con l'API?
Sì. I contenuti che crei con Mage, anche tramite l'API e il server MCP, possono essere usati a fini commerciali. L'attribuzione è gradita ma non obbligatoria.
Inizia a creare con Mage
Un solo account, un solo saldo di Gems, tutti i modelli. Paghi solo ciò che generi.