SDK Mage · Python
L'SDK Python di Mage
Genera immagini, video e audio da Python con client sync e asyncio e configurazioni tipizzate per ogni modello Mage.
pip install mage-spaceIn breve
L'SDK Python di Mage è il client ufficiale e open source per l'API di Mage, pubblicato come mage-space. Installalo con "pip install mage-space", 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 con Python 3.10 o successivo e ogni generazione si paga in Gems.
- 3.10+Python
- httpxClient HTTP
- 37Modelli tipizzati
- MITOpen source
Configurazione
Installa l'SDK Python ed esegui un modello
Installa il pacchetto
Aggiungi mage-space al tuo progetto.
pip install mage-spaceImposta 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.
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-v4", }) print(request["result"]["url"])
Esempi
L'SDK Python in pratica
Ogni esempio parte da un client che legge MAGE_API_KEY.
Invia ora, attendi dopo
from mage_space import Mage
mage = Mage() # reads MAGE_API_KEY
submitted = mage.generate("cherry", {
"prompt": "Waves rolling onto a black sand beach at sunset",
"resolution": "720p",
"duration": "5",
})
final = mage.requests.wait(
submitted["request_id"],
timeout=900,
on_update=lambda request: print(request["status"]),
)Carica un file
from mage_space import Mage
mage = Mage() # reads MAGE_API_KEY
clip = mage.uploads.upload("clip.mp4") # a path, bytes, or a binary file
mage.run("cherry", {
"prompt": "Restyle this clip as a watercolor painting",
"videos": [clip["url"]],
})Usa un personaggio salvato
from mage_space import Mage
mage = Mage() # reads MAGE_API_KEY
mage.characters.create(
name="Ana",
handle="ana",
image="https://example.com/ana.png",
)
mage.run("mango", {"prompt": "@ana walking through a night market"})Gestisci gli errori
from mage_space import Mage, MageAPIError, MageGenerationError
mage = Mage() # reads MAGE_API_KEY
try:
mage.run("mango", {"prompt": "A lighthouse at night"})
except MageAPIError as error:
if error.code == "insufficient_gems":
print("Gems needed:", error.body["error"]["gems_required"])
else:
raise
except MageGenerationError as error:
print("No output:", error.code)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.
Sync e asyncio
Mage e AsyncMage condividono tutti i metodi. Il client async è ideale per server web, notebook e pipeline che eseguono molte generazioni contemporaneamente.
Configurazioni tipizzate
Ogni modello ha un TypedDict, come MangoConfig, generato dalla documentazione di riferimento dell'API. Annota una configurazione con quel tipo e il type checker controllerà i campi.
Riferimento
L'SDK Python 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 percorso, dei byte o un file fino a 100 MB e ottieni il relativo 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
L'SDK Python supporta asyncio?
Quali versioni di Python supporta l'SDK?
Posso usare l'SDK Python in un notebook o in una pipeline di dati?
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.