SDK Mage · Python
SDK-ul Mage pentru Python
Generează imagini, video și audio din Python, cu clienți sync și asyncio și configurări tipizate pentru fiecare model Mage.
pip install mage-spacePe scurt
SDK-ul Mage pentru Python este clientul oficial open source pentru API-ul Mage, publicat ca mage-space. Instalează-l cu „pip install mage-space”, setează MAGE_API_KEY și apelează mage.run cu un id de model și o configurare, ca să primești imagini, video sau audio gata făcute de la oricare dintre cele 28 de modele. Rulează pe Python 3.10 sau mai nou, iar fiecare generare se plătește în Gems.
- 3.10+Python
- httpxClient HTTP
- 28Modele tipizate
- MITOpen source
Configurare
Instalează SDK-ul Python și rulează un model
Instalează pachetul
Adaugă mage-space în proiectul tău.
pip install mage-spaceSetează cheia API
Creează o cheie în API → API Keys pe mage.space și exportă-o. Clientul citește MAGE_API_KEY.
export MAGE_API_KEY="mage_sk_..."Generează
Apelează run cu un id de model și configurația lui. Așteaptă rezultatul și îl returnează; fișierul generat se află la 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"])
Exemple
SDK-ul Python în practică
Fiecare exemplu pornește de la un client care citește MAGE_API_KEY.
Trimite acum, așteaptă mai târziu
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"]),
)Încarcă un fișier
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"]],
})Folosește un personaj salvat
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"})Gestionează erorile
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)De ce SDK-ul
Ce face SDK-ul pentru tine
Un apel, conținut media gata
run trimite cererea de generare, face polling cu backoff-ul recomandat de API și se rezolvă cu cererea finalizată, împreună cu result.url.
Reîncercări care nu se plătesc de două ori
Fiecare trimitere poartă o cheie de idempotență. Erorile de rețea și de server sunt reîncercate cu backoff, iar o trimitere reîncercată nu este taxată niciodată a doua oară.
Încărcări dintr-un singur apel
Fișierele prea mari pentru un URL de date trec printr-o încărcare semnată, iar tichetul, PUT-ul și verificarea dimensiunii sunt gestionate pentru tine.
Erori clare
Refuzurile API includ statusul HTTP, codul de eroare și ID-ul cererii; generările eșuate sau anulate și expirările de timp au propriile tipuri de erori.
Sync și asyncio
Mage și AsyncMage au aceleași metode. Clientul async se potrivește pentru servere web, notebook-uri și pipeline-uri care rulează multe generări simultan.
Configurări tipizate
Fiecare model are un TypedDict, precum MangoConfig, generat din referința API. Adnotează o configurare cu el, iar verificatorul de tipuri îți verifică câmpurile.
Referință
SDK-ul Python pe scurt
Aceleași metode acoperă toate modelele; modelul este primul argument.
| Metodă | Ce face |
|---|---|
| mage.run(model, config) | Trimite o generare, așteaptă finalizarea ei și returnează cererea completă. |
| mage.generate(model, config) | Trimite o generare și returnează imediat cererea. |
| mage.requests.get / cancel / wait | Citește, oprește sau așteaptă o cerere după id. |
| mage.uploads.upload(data) | Încarcă o cale, bytes sau un fișier de până la 100 MB și returnează URL-ul lui. |
| mage.characters / mage.references | Listează, creează și șterge personaje și referințe salvate. |
| mage.account.get() | Soldul tău de Gems. |
| mage.architectures.list() | Catalogul de modele actualizat, cu opțiuni și prețuri. |
Modele
Începe cu aceste modele
API Guava
Fotorealism care trece drept fotografie
API Mango
Familia noastră principală de modele de imagine
API Nano Banana 2
Text clar și lizibil, până la 4K
API Cherry
Familia noastră principală de modele video
API Lemon
Toate funcțiile video, la un preț mai prietenos
API Seed Audio
Voci, muzică și efecte sonore dintr-un singur prompt
Întrebări frecvente
Întrebări frecvente
Acceptă SDK-ul Python asyncio?
Ce versiuni de Python acceptă SDK-ul?
Pot folosi SDK-ul Python într-un notebook sau într-un pipeline de date?
Sunt SDK-urile Mage gratuite și open source?
Funcționează modelele Mage noi cu un SDK mai vechi?
Cum evită SDK-urile să plătești de două ori pentru o cerere reîncercată?
Sunt SDK-urile stabile?
Cât costă API-ul Mage?
Am nevoie de un abonament Mage ca să folosesc API-ul?
Pot folosi rezultatele din API în scop comercial?
Începe să construiești cu Mage
Un singur cont, un singur sold de Gems, toate modelele. Plătești doar pentru ce generezi.