Mage SDK · Python
Python SDK pro Mage
Generuj obrázky, video a audio z Pythonu pomocí synchronních i asyncio klientů a typovaných konfigurací pro každý model Mage.
pip install mage-spaceStručně
Python SDK pro Mage je oficiální open source klient pro Mage API, vydaný pod názvem mage-space. Nainstaluj ho příkazem "pip install mage-space", nastav MAGE_API_KEY a zavolej mage.run s ID modelu a konfigurací. Hotové obrázky, video nebo audio získáš z kteréhokoli z 28 modelů. Funguje na Pythonu 3.10 nebo novějším a každá generace se platí v Gems.
- 3.10+Python
- httpxHTTP klient
- 28Typované modely
- MITOpen source
Nastavení
Nainstaluj Python SDK a spusť model
Nainstaluj balíček
Přidej mage-space do svého projektu.
pip install mage-spaceNastav API klíč
Vytvoř klíč v API → API Keys na mage.space a exportuj ho. Klient čte MAGE_API_KEY.
export MAGE_API_KEY="mage_sk_..."Generuj
Zavolej run s id modelu a jeho konfigurací. Počká na výsledek a vrátí ho; výstup najdeš v 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"])
Příklady
Python SDK v praxi
Každý příklad vychází z klienta, který čte MAGE_API_KEY.
Odešli hned, počkej později
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"]),
)Nahraj soubor
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"]],
})Použij uloženou postavu
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"})Ošetři chyby
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)Proč SDK
Co SDK vyřeší za tebe
Jedno volání, hotová média
run odešle generování, dotazuje se na stav s odstupy doporučenými API a vrátí dokončený požadavek s result.url.
Opakování, která nikdy neúčtují dvakrát
Každý požadavek nese idempotentní klíč. Při chybách sítě a serveru se pokus opakuje s postupně rostoucími odstupy a opakovaný požadavek se nikdy nezpoplatní znovu.
Nahrávání jedním voláním
Soubory příliš velké pro data URL se nahrávají přes podepsané nahrání, o tiket, PUT i kontrolu velikosti se postaráme za tebe.
Srozumitelné chyby
Odmítnutí ze strany API obsahují HTTP status, kód chyby a ID požadavku; neúspěšná nebo zrušená generování a vypršení časového limitu mají vlastní typy chyb.
Sync a asyncio
Mage a AsyncMage mají všechny metody společné. Asynchronní klient se hodí pro webové servery, notebooky i pipeline, které spouštějí mnoho generací najednou.
Typované konfigurace
Každý model má svůj TypedDict, například MangoConfig, vygenerovaný z reference API. Anotuj jím konfiguraci a tvůj type checker zkontroluje všechna pole.
Reference
Python SDK ve stručnosti
Stejné metody pokrývají každý model; model je první argument.
| Metoda | Co dělá |
|---|---|
| mage.run(model, config) | Odešle generování, počká na něj a vrátí dokončený požadavek. |
| mage.generate(model, config) | Odešle generování a okamžitě vrátí požadavek. |
| mage.requests.get / cancel / wait | Načte požadavek podle id, zastaví ho, nebo na něj počká. |
| mage.uploads.upload(data) | Nahraje cestu k souboru, bajty nebo soubor do velikosti 100 MB a vrátí jeho URL. |
| mage.characters / mage.references | Zobrazí, vytvoří a smaže uložené postavy a reference. |
| mage.account.get() | Tvůj zůstatek Gems. |
| mage.architectures.list() | Aktuální katalog modelů s možnostmi a cenami. |
Modely
Začni s těmito modely
Guava API
Fotorealismus, který projde jako fotografie
Mango API
Naše vlajková řada obrázkových modelů
Nano Banana 2 API
Ostrý, čitelný text až do 4K
Cherry API
Naše vlajková řada video modelů
Lemon API
Všechny video funkce za příznivější cenu
Seed Audio API
Hlasy, hudba a zvukové efekty z jednoho promptu
Časté dotazy
Často kladené otázky
Podporuje Python SDK asyncio?
Které verze Pythonu SDK podporuje?
Můžu Python SDK používat v notebooku nebo datové pipeline?
Jsou Mage SDK zdarma a open source?
Fungují nové modely Mage i se starším SDK?
Jak SDK zabrání dvojímu zaplacení za opakovaný požadavek?
Jsou SDK stabilní?
Kolik stojí Mage API?
Potřebuji k používání API členství v Mage?
Můžu výstupy z API používat komerčně?
Začni tvořit s Mage
Jeden účet, jeden zůstatek Gems, všechny modely. Platíš jen za to, co vygeneruješ.