Mage SDK · Python
Mage Python SDK'sı
Python'dan senkron ve asyncio istemcileriyle, her Mage modeli için tip tanımlı yapılandırmalarla yapay zeka görsel, video ve ses üret.
pip install mage-spaceBir bakışta
Mage Python SDK'sı, mage-space adıyla yayınlanan, Mage API için resmî açık kaynak istemcidir. "pip install mage-space" ile kur, MAGE_API_KEY'i ayarla ve 37 modelden herhangi birinden hazır görsel, video veya ses almak için mage.run'ı bir model id'si ve bir yapılandırmayla çağır. Python 3.10 veya üzerinde çalışır ve her üretim Gems ile ödenir.
- 3.10+Python
- httpxHTTP istemcisi
- 37Tip tanımlı modeller
- MITAçık kaynak
Kurulum
Python SDK'sını kur ve bir model çalıştır
Paketi kur
mage-space paketini projene ekle.
pip install mage-spaceAPI anahtarını ayarla
mage.space'te API → API Keys bölümünden bir anahtar oluştur ve dışa aktar. İstemci MAGE_API_KEY değerini okur.
export MAGE_API_KEY="mage_sk_..."Üret
run fonksiyonunu bir model kimliği ve yapılandırmasıyla çağır. Sonucu bekler ve döndürür; çıktı result.url adresindedir.
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"])
Örnekler
Python SDK'sı kullanımda
Her örnek, MAGE_API_KEY değerini okuyan bir istemciyle başlar.
Şimdi gönder, sonra bekle
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"]),
)Dosya yükle
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"]],
})Kayıtlı bir karakter kullan
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"})Hataları yönet
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)Neden SDK
SDK senin için neleri halleder
Tek çağrı, hazır medya
run üretimi gönderir, API'nin önerdiği geri çekilme süreleriyle durumu yoklar ve result.url içeren tamamlanmış isteği döndürür.
İki kez ödetmeyen yeniden denemeler
Her istek bir idempotency anahtarı taşır. Ağ ve sunucu hataları geri çekilmeyle yeniden denenir, yeniden denenen istek için tekrar ücret alınmaz.
Tek çağrıda yükleme
Data URL için fazla büyük dosyalar imzalı yükleme üzerinden gider; bilet, PUT isteği ve boyut kontrolü senin yerine halledilir.
Anlaşılır hatalar
API ret yanıtları HTTP durumunu, hata kodunu ve istek kimliğini taşır; başarısız veya iptal edilen üretimlerin ve zaman aşımlarının kendi hata türleri vardır.
Senkron ve asyncio
Mage ve AsyncMage tüm yöntemleri paylaşır. Asenkron istemci; web sunucularına, not defterlerine ve aynı anda birçok üretim çalıştıran işlem hatlarına uygundur.
Tip tanımlı yapılandırmalar
Her modelin API referansından oluşturulan bir TypedDict'i vardır; örneğin MangoConfig. Yapılandırmanı bununla işaretlersen tip denetleyicin alanları kontrol eder.
Referans
Python SDK'sına kısa bakış
Aynı yöntemler her modeli kapsar; model ilk argümandır.
| Yöntem | Ne yapar? |
|---|---|
| mage.run(model, config) | Bir üretim gönderir, bitmesini bekler ve tamamlanan isteği döndürür. |
| mage.generate(model, config) | Bir üretim gönderir ve isteği hemen döndürür. |
| mage.requests.get / cancel / wait | Bir isteği kimliğiyle okur, durdurur veya bekler. |
| mage.uploads.upload(data) | 100 MB'a kadar bir dosya yolu, bayt verisi veya dosya yükler ve URL'sini döndürür. |
| mage.characters / mage.references | Kayıtlı karakterleri ve referansları listeler, oluşturur ve siler. |
| mage.account.get() | Gems bakiyen. |
| mage.architectures.list() | Seçenekleri ve fiyatlarıyla güncel model kataloğu. |
Modeller
Bu modellerle başla
Guava API
Fotoğraf sanılacak kadar gerçekçi görseller
Mango API
Amiral gemisi görsel model ailemiz
Nano Banana 2 API
Net, okunaklı metin, 4K'ya kadar
Cherry API
Amiral gemisi video model ailemiz
Lemon API
Tüm video özellikleri, daha uygun fiyata
Seed Audio API
Tek bir prompt'tan sesler, müzik ve ses efektleri
SSS
Sık sorulan sorular
Python SDK'sı asyncio'yu destekliyor mu?
SDK hangi Python sürümlerini destekliyor?
Python SDK'sını not defterinde veya veri işlem hattında kullanabilir miyim?
Mage SDK'ları ücretsiz ve açık kaynak mı?
Yeni Mage modelleri eski bir SDK ile çalışır mı?
SDK'lar yeniden denenen bir istek için iki kez ödeme yapılmasını nasıl önler?
SDK'lar kararlı mı?
Mage API ne kadar?
API'yi kullanmak için Mage üyeliği gerekir mi?
API çıktılarını ticari amaçla kullanabilir miyim?
Mage ile geliştirmeye başla
Tek hesap, tek Gems bakiyesi, tüm modeller. Yalnızca ürettiğin kadar öde.