Mage SDK · Python
Το Python SDK της Mage
Δημιούργησε εικόνες, βίντεο και ήχο από Python με sync και asyncio clients και τυποποιημένα configs για κάθε μοντέλο της Mage.
pip install mage-spaceΜε μια ματιά
Το Python SDK της Mage είναι ο επίσημος client ανοιχτού κώδικα για το Mage API και δημοσιεύεται ως mage-space. Εγκατάστησέ το με «pip install mage-space», όρισε το MAGE_API_KEY και κάλεσε το mage.run με ένα model id και ένα config, για να πάρεις έτοιμες εικόνες, βίντεο ή ήχο από οποιοδήποτε από τα 28 μοντέλα. Τρέχει σε Python 3.10 ή νεότερο και κάθε δημιουργία πληρώνεται με Gems.
- 3.10+Python
- httpxHTTP client
- 28Μοντέλα με τύπους
- MITΑνοιχτός κώδικας
Ρύθμιση
Εγκατάστησε το Python SDK και τρέξε ένα μοντέλο
Εγκατάσταση του πακέτου
Πρόσθεσε το mage-space στο project σου.
pip install mage-spaceΟρισμός του κλειδιού API
Δημιούργησε ένα κλειδί στο API → API Keys στο mage.space και κάνε export. Ο client διαβάζει το MAGE_API_KEY.
export MAGE_API_KEY="mage_sk_..."Δημιουργία
Κάλεσε το run με ένα id μοντέλου και τη ρύθμισή του. Περιμένει το αποτέλεσμα και το επιστρέφει· η έξοδος βρίσκεται στο 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-v3", }) print(request["result"]["url"])
Παραδείγματα
Το Python SDK στην πράξη
Κάθε παράδειγμα ξεκινά από έναν client που διαβάζει το MAGE_API_KEY.
Υποβολή τώρα, αναμονή αργότερα
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"]),
)Μεταφόρτωση αρχείου
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"]],
})Χρήση αποθηκευμένου Character
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"})Διαχείριση σφαλμάτων
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)Γιατί το SDK
Τι αναλαμβάνει το SDK για εσένα
Μία κλήση, έτοιμο πολυμέσο
Το run υποβάλλει τη δημιουργία, κάνει polling με το backoff που προτείνει το API και επιστρέφει το ολοκληρωμένο αίτημα με το result.url.
Επαναλήψεις χωρίς διπλή χρέωση
Κάθε υποβολή φέρει ένα idempotency key. Τα σφάλματα δικτύου και διακομιστή επαναλαμβάνονται με backoff και μια υποβολή που επαναλαμβάνεται δεν χρεώνεται ξανά.
Uploads με μία κλήση
Τα αρχεία που είναι πολύ μεγάλα για data URL περνούν από υπογεγραμμένο upload, με το ticket, το PUT και τον έλεγχο μεγέθους να γίνονται για σένα.
Σαφή σφάλματα
Οι απορρίψεις του API περιλαμβάνουν το HTTP status, τον κωδικό σφάλματος και το request id· οι αποτυχημένες ή ακυρωμένες δημιουργίες και τα timeouts έχουν δικούς τους τύπους σφαλμάτων.
Sync και asyncio
Τα Mage και AsyncMage έχουν όλες τις ίδιες μεθόδους. Ο async client ταιριάζει σε web servers, notebooks και pipelines που τρέχουν πολλές δημιουργίες ταυτόχρονα.
Τυποποιημένα configs
Κάθε μοντέλο έχει ένα TypedDict, όπως το MangoConfig, που παράγεται από την τεκμηρίωση του API. Δήλωσε τον τύπο ενός config με αυτό και ο type checker σου θα ελέγχει τα πεδία.
Αναφορά
Το Python SDK με μια ματιά
Οι ίδιες μέθοδοι καλύπτουν κάθε μοντέλο· το μοντέλο είναι το πρώτο όρισμα.
| Μέθοδος | Τι κάνει |
|---|---|
| mage.run(model, config) | Υποβάλλει μια δημιουργία, περιμένει να ολοκληρωθεί και επιστρέφει το ολοκληρωμένο αίτημα. |
| mage.generate(model, config) | Υποβάλλει μια δημιουργία και επιστρέφει αμέσως το αίτημα. |
| mage.requests.get / cancel / wait | Διαβάζει, σταματά ή περιμένει ένα αίτημα με βάση το id. |
| mage.uploads.upload(data) | Ανεβάζει μια διαδρομή, bytes ή αρχείο έως 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
Συχνές ερωτήσεις
Συχνές ερωτήσεις
Υποστηρίζει το Python SDK το asyncio;
Ποιες εκδόσεις Python υποστηρίζει το SDK;
Μπορώ να χρησιμοποιήσω το Python SDK σε notebook ή σε data pipeline;
Είναι τα Mage SDK δωρεάν και ανοιχτού κώδικα;
Λειτουργούν τα νέα μοντέλα της Mage με παλαιότερο SDK;
Πώς αποφεύγουν τα SDK τη διπλή χρέωση όταν ένα αίτημα επαναλαμβάνεται;
Είναι σταθερά τα SDK;
Πόσο κοστίζει το Mage API;
Χρειάζομαι συνδρομή στο Mage για να χρησιμοποιήσω το API;
Μπορώ να χρησιμοποιήσω τα αποτελέσματα του API εμπορικά;
Ξεκίνα να δημιουργείς με το Mage
Ένας λογαριασμός, ένα υπόλοιπο Gems, όλα τα μοντέλα. Πληρώνεις μόνο για ό,τι δημιουργείς.