Mage SDK · Python
Python SDK Mage
Generuj obrazy, wideo i audio w Pythonie dzięki klientom sync i asyncio oraz typowanym konfiguracjom dla każdego modelu Mage.
pip install mage-spaceW skrócie
SDK Mage dla Pythona to oficjalny, otwartoźródłowy klient API Mage, publikowany jako mage-space. Zainstaluj je poleceniem „pip install mage-space”, ustaw MAGE_API_KEY i wywołaj mage.run z id modelu i konfiguracją, aby dostać gotowe obrazy, wideo lub dźwięk z dowolnego z 37 modeli. Działa na Pythonie 3.10 lub nowszym, a każda generacja jest płatna w Gems.
- 3.10+Python
- httpxKlient HTTP
- 37Typowane modele
- MITOpen source
Konfiguracja
Zainstaluj Python SDK i uruchom model
Zainstaluj pakiet
Dodaj mage-space do swojego projektu.
pip install mage-spaceUstaw klucz API
Utwórz klucz w API → API Keys na mage.space i wyeksportuj go. Klient odczytuje MAGE_API_KEY.
export MAGE_API_KEY="mage_sk_..."Generuj
Wywołaj run z ID modelu i jego konfiguracją. Metoda czeka na wynik i go zwraca; wynik znajdziesz w 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"])
Przykłady
Python SDK w praktyce
Każdy przykład zaczyna się od klienta, który odczytuje MAGE_API_KEY.
Wyślij teraz, poczekaj później
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"]),
)Prześlij plik
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"]],
})Użyj zapisanej postaci
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"})Obsługa błędów
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)Dlaczego SDK
Co SDK robi za ciebie
Jedno wywołanie, gotowe media
run wysyła generację, odpytuje API z zalecanym przez nie opóźnieniem (backoff) i zwraca ukończone zgłoszenie z result.url.
Ponowienia, które nigdy nie kosztują podwójnie
Każde zgłoszenie ma klucz idempotentności. Błędy sieci i serwera są ponawiane z opóźnieniem (backoff), a ponowione zgłoszenie nigdy nie jest rozliczane drugi raz.
Przesyłanie plików jednym wywołaniem
Pliki zbyt duże na data URL trafiają przez podpisany upload, a bilet, żądanie PUT i sprawdzenie rozmiaru obsługujemy za Ciebie.
Czytelne błędy
Odmowy API zawierają status HTTP, kod błędu i identyfikator żądania, a nieudane lub anulowane generacje i przekroczenia czasu mają własne typy błędów.
Sync i asyncio
Mage i AsyncMage mają te same metody. Klient asynchroniczny sprawdza się w serwerach WWW, notebookach i potokach, które uruchamiają wiele generacji naraz.
Typowane konfiguracje
Każdy model ma swój TypedDict, np. MangoConfig, generowany na podstawie dokumentacji API. Otaguj nim konfigurację, a type checker sprawdzi pola.
Dokumentacja
Python SDK w skrócie
Te same metody obsługują każdy model; model jest pierwszym argumentem.
| Metoda | Co robi |
|---|---|
| mage.run(model, config) | Wysyła generowanie, czeka na nie i zwraca ukończone żądanie. |
| mage.generate(model, config) | Wysyła generowanie i od razu zwraca żądanie. |
| mage.requests.get / cancel / wait | Odczytaj, zatrzymaj lub poczekaj na żądanie według ID. |
| mage.uploads.upload(data) | Prześlij ścieżkę, bajty lub plik do 100 MB i zwróć jego adres URL. |
| mage.characters / mage.references | Wyświetla, tworzy i usuwa zapisane postaci oraz referencje. |
| mage.account.get() | Twoje saldo Gems. |
| mage.architectures.list() | Aktualny katalog modeli z opcjami i cenami. |
Modele
Zacznij od tych modeli
Guava API
Fotorealizm, który uchodzi za prawdziwe zdjęcie
Mango API
Nasza flagowa rodzina modeli obrazu
Nano Banana 2 API
Wyraźny, czytelny tekst, do 4K
Cherry API
Nasza flagowa rodzina modeli wideo
Lemon API
Wszystkie funkcje wideo w bardziej przyjaznej cenie
Seed Audio API
Głosy, muzyka i efekty dźwiękowe z jednego promptu
FAQ
Najczęściej zadawane pytania
Czy Python SDK obsługuje asyncio?
Jakie wersje Pythona obsługuje SDK?
Czy mogę używać Python SDK w notebooku lub potoku danych?
Czy SDK Mage są darmowe i open source?
Czy nowe modele Mage działają ze starszym SDK?
Jak SDK chroni przed podwójną opłatą za ponowione żądanie?
Czy SDK są stabilne?
Ile kosztuje Mage API?
Czy potrzebuję członkostwa w Mage, żeby korzystać z API?
Czy mogę używać wyników z API komercyjnie?
Zacznij tworzyć z Mage
Jedno konto, jedno saldo Gems, wszystkie modele. Płacisz tylko za to, co wygenerujesz.