İçeriğe geç

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-space

Bir 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

  1. Paketi kur

    mage-space paketini projene ekle.

    pip install mage-space
  2. API 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_..."
  3. Ü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öntemNe 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 / waitBir 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.referencesKayı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

  • Görsel · 37 Gem'den başlayan fiyatlarla

    Guava API

    Fotoğraf sanılacak kadar gerçekçi görseller

  • Görsel · 42 Gem'den başlayan fiyatlarla

    Mango API

    Amiral gemisi görsel model ailemiz

  • Görsel · 51 Gems'ten başlayan fiyatlarla

    Nano Banana 2 API

    Net, okunaklı metin, 4K'ya kadar

  • Video · 618 Gem'den başlayan fiyatlarla

    Cherry API

    Amiral gemisi video model ailemiz

  • Video · 245 Gem'den başlayan fiyatlarla

    Lemon API

    Tüm video özellikleri, daha uygun fiyata

  • Ses · 19 Gem'den başlayan fiyatlarla

    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?
Evet. AsyncMage, Mage ile aynı yöntemlere sahiptir (await ile beklenir) ve asenkron bağlam yöneticisi olarak çalışır.
SDK hangi Python sürümlerini destekliyor?
Python 3.10 ve üzeri. Tek bağımlılıkları httpx ve typing-extensions'tır.
Python SDK'sını not defterinde veya veri işlem hattında kullanabilir miyim?
Evet. Betiklerde ve not defterlerinde Mage'i, aynı anda birçok üretim çalıştırmak için ise asyncio ile AsyncMage'i kullan. Hesap aynı anda en fazla 20 üretimi işleyebilir.
Mage SDK'ları ücretsiz ve açık kaynak mı?
Evet. SDK'lar ve ComfyUI düğümleri GitHub'da MIT lisanslıdır ve kurulumları ücretsizdir. Yalnızca çalıştırdığın üretimler için, her modelin belirtilen fiyatı üzerinden Gems ile ödersin.
Yeni Mage modelleri eski bir SDK ile çalışır mı?
Evet. Yeni modelin kimliğini bir metin olarak ver, çalışır; SDK yapılandırmayı her modelin ortak kullandığı alanlara göre kontrol eder. API referansı değiştiğinde bir bot tipleri günceller, böylece yeni modeller kendi tipleriyle bir sonraki sürümde gelir.
SDK'lar yeniden denenen bir istek için iki kez ödeme yapılmasını nasıl önler?
Her gönderim bir Idempotency-Key taşır. SDK her çağrı için yeni bir anahtar oluşturur ve o çağrıyı kendisi yeniden denediğinde aynı anahtarı kullanır. Böylece yeniden denenen gönderim orijinal isteği döndürür ve ek ücret almaz.
SDK'lar kararlı mı?
0.x sürümünde beta aşamasındalar, bu yüzden bir alt sürüm onları değiştirebilir. API'nin kendisi ayrı sürümlenir ve v1 içinde kararlı kalır.
Mage API ne kadar?
Abonelik veya aylık ücret yoktur. Her üretim, modelin listelenen fiyatı üzerinden Gem ile ödenir; standart pakette 1.000 Gem 1 $ tutarındadır. Her model sayfasında varsayılan ayarların fiyatı yer alır ve her yanıt tam ücreti bildirir. Başarısız olan üretimin ücreti iade edilir; Mage'in içerik politikasına takılanın iade edilmez. Bakiyenin karşılayamadığı istek, hiçbir ücret alınmadan reddedilir.
API'yi kullanmak için Mage üyeliği gerekir mi?
Hayır. API yalnızca Gem ile çalışır. Üyelik planları ve bunların sunduğu uygulama içi sınırsız üretim API isteklerinde geçerli değildir. Hesabın önce bir kez başarılı ödeme yapması gerekir (herhangi bir Gem paketi veya plan olabilir). Kayıt bonusu olarak verilen Gem'ler yalnızca Mage uygulamasında kullanılabilir.
API çıktılarını ticari amaçla kullanabilir miyim?
Evet. Mage ile oluşturduğun içerikler, API ve MCP sunucusu üzerinden oluşturdukların da dahil, ticari olarak kullanılabilir. Atıf yapmanı memnuniyetle karşılarız ama zorunlu değil.

Mage ile geliştirmeye başla

Tek hesap, tek Gems bakiyesi, tüm modeller. Yalnızca ürettiğin kadar öde.

CharactersTopluluk