SDK Mage · Python
Le SDK Python de Mage
Génère des images, des vidéos et de l'audio depuis Python avec des clients synchrone et asyncio, et des configurations typées pour chaque modèle Mage.
pip install mage-spaceEn un coup d’œil
Le SDK Python de Mage est le client officiel open source de l'API Mage, publié sous le nom mage-space. Installe-le avec « pip install mage-space », 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 Python 3.10 ou version ultérieure, et chaque génération se paie en Gems.
- 3.10+Python
- httpxClient HTTP
- 37Modèles typés
- MITOpen source
Configuration
Installe le SDK Python et lance un modèle
Installer le paquet
Ajoute mage-space à ton projet.
pip install mage-spaceDé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.
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"])
Exemples
Le SDK Python en pratique
Chaque exemple part d’un client qui lit MAGE_API_KEY.
Envoyer maintenant, attendre plus tard
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"]),
)Téléverser un fichier
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"]],
})Utiliser un personnage enregistré
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"})Gérer les erreurs
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)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.
Synchrone et asyncio
Mage et AsyncMage partagent toutes leurs méthodes. Le client asynchrone convient aux serveurs web, aux notebooks et aux pipelines qui lancent de nombreuses générations à la fois.
Configurations typées
Chaque modèle a son TypedDict, comme MangoConfig, généré à partir de la référence de l'API. Annote une configuration avec lui et ton vérificateur de types contrôle les champs.
Référence
Le SDK Python 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) | Envoie un chemin, des octets ou un fichier jusqu'à 100 Mo 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
Le SDK Python prend-il en charge asyncio ?
Quelles versions de Python le SDK prend-il en charge ?
Puis-je utiliser le SDK Python dans un notebook ou un pipeline de données ?
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.