Mage SDK · Python
De Mage Python SDK
Genereer afbeeldingen, video en audio vanuit Python met sync- en asyncio-clients en getypeerde configs voor elk Mage-model.
pip install mage-spaceIn één oogopslag
De Mage Python SDK is de officiële open-sourceclient voor de Mage API, gepubliceerd als mage-space. Installeer hem met "pip install mage-space", stel MAGE_API_KEY in en roep mage.run aan met een model-id en een config om kant-en-klare afbeeldingen, video of audio te krijgen van elk van de 37 modellen. Hij draait op Python 3.10 of nieuwer, en elke generatie betaal je in Gems.
- 3.10+Python
- httpxHTTP-client
- 37Getypeerde modellen
- MITOpen source
Instellen
Installeer de Python SDK en draai een model
Installeer het pakket
Voeg mage-space toe aan je project.
pip install mage-spaceStel je API-sleutel in
Maak een sleutel aan via API → API Keys op mage.space en exporteer die. De client leest MAGE_API_KEY.
export MAGE_API_KEY="mage_sk_..."Genereer
Roep run aan met een model-id en de bijbehorende config. De functie wacht op het resultaat en geeft het terug; de output staat in 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"])
Voorbeelden
De Python SDK in de praktijk
Elk voorbeeld begint met een client die MAGE_API_KEY leest.
Nu versturen, later wachten
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"]),
)Een bestand uploaden
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"]],
})Een opgeslagen personage gebruiken
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"})Fouten afhandelen
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)Waarom de SDK
Wat de SDK voor je regelt
Eén aanroep, kant-en-klare media
run verstuurt de generatie, pollt met de backoff die de API aanbeveelt en levert de voltooide aanvraag op met result.url.
Nieuwe pogingen zonder dubbel te betalen
Elke aanvraag heeft een idempotentiesleutel. Netwerkfouten en serverfouten worden met backoff opnieuw geprobeerd en een opnieuw verstuurde aanvraag wordt nooit nogmaals in rekening gebracht.
Uploads in één aanroep
Bestanden die te groot zijn voor een data-URL gaan via een ondertekende upload. Het ticket, de PUT en de groottecontrole worden voor je afgehandeld.
Duidelijke foutmeldingen
Weigeringen van de API bevatten hun HTTP-status, foutcode en aanvraag-ID. Mislukte of geannuleerde generaties en time-outs hebben elk hun eigen fouttype.
Sync en asyncio
Mage en AsyncMage hebben dezelfde methoden. De async-client past goed bij webservers, notebooks en pipelines die veel generaties tegelijk draaien.
Getypeerde configs
Elk model heeft een TypedDict, zoals MangoConfig, gegenereerd uit de API-referentie. Annoteer een config ermee en je typechecker controleert de velden.
Referentie
De Python SDK in één oogopslag
Dezelfde methoden gelden voor elk model; het model is het eerste argument.
| Methode | Wat het doet |
|---|---|
| mage.run(model, config) | Verstuur een generatie, wacht erop en geef het voltooide verzoek terug. |
| mage.generate(model, config) | Verstuur een generatie en geef het verzoek direct terug. |
| mage.requests.get / cancel / wait | Een verzoek opvragen, stoppen of erop wachten via id. |
| mage.uploads.upload(data) | Upload een pad, bytes of bestand van maximaal 100 MB en krijg de URL terug. |
| mage.characters / mage.references | Opgeslagen personages en referenties weergeven, aanmaken en verwijderen. |
| mage.account.get() | Je Gems-saldo. |
| mage.architectures.list() | De actuele modelcatalogus met opties en prijzen. |
Modellen
Begin met deze modellen
Guava API
Fotorealisme dat voor een echte foto doorgaat
Mango API
Onze vlaggenschip-afbeeldingsfamilie
Nano Banana 2 API
Scherpe, leesbare tekst, tot 4K
Cherry API
Onze vlaggenschip-videofamilie
Lemon API
Alle videofuncties, tegen een vriendelijkere prijs
Seed Audio API
Stemmen, muziek en geluidseffecten vanuit één prompt
FAQ
Veelgestelde vragen
Ondersteunt de Python SDK asyncio?
Welke Python-versies ondersteunt de SDK?
Kan ik de Python SDK in een notebook of data pipeline gebruiken?
Zijn de Mage SDK's gratis en open source?
Werken nieuwe Mage-modellen met een oudere SDK?
Hoe voorkomen de SDK's dat je twee keer betaalt voor een opnieuw verzonden verzoek?
Zijn de SDK's stabiel?
Hoeveel kost de Mage API?
Heb ik een Mage-lidmaatschap nodig om de API te gebruiken?
Mag ik API-uitvoer commercieel gebruiken?
Begin met bouwen met Mage
Eén account, één Gems-saldo, alle modellen. Je betaalt alleen voor wat je genereert.