Mage SDK · Python
A Mage Python SDK
Generálj képeket, videókat és hangot Pythonból szinkron és asyncio kliensekkel, valamint típusos konfigurációkkal minden Mage-modellhez.
pip install mage-spaceDióhéjban
A Mage Python SDK a Mage API hivatalos, nyílt forráskódú kliense, mage-space néven publikálva. Telepítsd a "pip install mage-space" paranccsal, állítsd be a MAGE_API_KEY változót, majd hívd meg a mage.run függvényt egy modellazonosítóval és egy konfigurációval, és kész képeket, videókat vagy hangot kapsz a 28 modell bármelyikéből. Python 3.10 vagy újabb verzión fut, és minden generálás Gems-ben fizetendő.
- 3.10+Python
- httpxHTTP-kliens
- 28Típusos modellek
- MITNyílt forráskód
Beállítás
Telepítsd a Python SDK-t, és futtass egy modellt
Csomag telepítése
Add hozzá a mage-space csomagot a projektedhez.
pip install mage-spaceAPI-kulcs beállítása
Hozz létre egy kulcsot a mage.space oldalon az API → API Keys menüben, és exportáld. A kliens a MAGE_API_KEY változót olvassa.
export MAGE_API_KEY="mage_sk_..."Generálás
Hívd meg a run metódust egy modellazonosítóval és a hozzá tartozó konfigurációval. Megvárja az eredményt, és visszaadja; a kimenet a result.url címen érhető el.
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éldák
A Python SDK a gyakorlatban
Minden példa egy olyan kliensből indul, amely a MAGE_API_KEY változót olvassa.
Beküldés most, várakozás később
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"]),
)Fájl feltöltése
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"]],
})Mentett karakter használata
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"})Hibakezelés
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)Miért az SDK
Amit az SDK elintéz helyetted
Egy hívás, kész média
A run elküldi a generálást, az API által javasolt visszalépéses időzítéssel lekérdezi az állapotot, és a kész kéréssel tér vissza result.url értékkel.
Újrapróbálkozás kétszeri fizetés nélkül
Minden beküldés idempotencia-kulcsot visz magával. A hálózati és szerverhibáknál visszalépéses időzítéssel újrapróbálkozik, az újra elküldött kérésért pedig soha nem számolunk fel újabb díjat.
Feltöltés egy hívással
A data URL-hez túl nagy fájlok aláírt feltöltéssel mennek át, a jegyet, a PUT kérést és a méretellenőrzést pedig az SDK intézi helyetted.
Érthető hibák
Az API elutasításai tartalmazzák a HTTP-státuszt, a hibakódot és a kérésazonosítót; a sikertelen vagy megszakított generálásoknak és az időtúllépéseknek saját hibatípusuk van.
Szinkron és asyncio
A Mage és az AsyncMage minden metódusa közös. Az aszinkron kliens jól illik webszerverekhez, notebookokhoz és olyan pipeline-okhoz, amelyek egyszerre sok generálást futtatnak.
Típusos konfigurációk
Minden modellhez tartozik egy TypedDict, például a MangoConfig, amelyet az API-referenciából generálunk. Jelöld meg vele a konfigurációt, és a típusellenőrződ ellenőrzi a mezőket.
Referencia
A Python SDK dióhéjban
Ugyanazok a metódusok minden modellt lefednek; a modell az első argumentum.
| Metódus | Mit csinál |
|---|---|
| mage.run(model, config) | Beküld egy generálást, megvárja, és visszaadja a befejezett kérést. |
| mage.generate(model, config) | Beküld egy generálást, és azonnal visszaadja a kérést. |
| mage.requests.get / cancel / wait | Kérés lekérdezése, leállítása vagy megvárása azonosító alapján. |
| mage.uploads.upload(data) | Feltölt egy elérési utat, bájtokat vagy legfeljebb 100 MB-os fájlt, és visszaadja az URL-jét. |
| mage.characters / mage.references | Mentett karakterek és referenciák listázása, létrehozása és törlése. |
| mage.account.get() | A Gem-egyenleged. |
| mage.architectures.list() | Az élő modellkatalógus beállításokkal és árakkal. |
Modellek
Kezdd ezekkel a modellekkel
Guava API
Fotórealizmus, ami fényképnek is elmegy
Mango API
Zászlóshajó képmodellcsaládunk
Nano Banana 2 API
Éles, jól olvasható szöveg, akár 4K-ban
Cherry API
Zászlóshajó videómodellcsaládunk
Lemon API
Minden videófunkció, barátibb áron
Seed Audio API
Hangok, zene és hangeffektek egyetlen promptból
GYIK
Gyakran ismételt kérdések
Támogatja a Python SDK az asyncio-t?
Mely Python-verziókat támogatja az SDK?
Használhatom a Python SDK-t notebookban vagy adatfeldolgozó pipeline-ban?
Ingyenesek és nyílt forráskódúak a Mage SDK-k?
Működnek az új Mage modellek régebbi SDK-val?
Hogyan kerüli el az SDK, hogy kétszer fizess egy újrapróbált kérésért?
Stabilak az SDK-k?
Mennyibe kerül a Mage API?
Kell Mage-tagság az API használatához?
Felhasználhatom kereskedelmi célra az API kimeneteit?
Kezdj el építeni a Mage-dzsel
Egy fiók, egy Gems-egyenleg, az összes modell. Csak azért fizetsz, amit legenerálsz.