Langsung ke konten

SDK Mage · Python

SDK Python Mage

Buat gambar, video, dan audio dari Python dengan klien sinkron dan asyncio serta konfigurasi bertipe untuk setiap model Mage.

pip install mage-space

Sekilas info

SDK Python Mage adalah klien resmi open-source untuk Mage API, diterbitkan sebagai mage-space. Instal dengan "pip install mage-space", atur MAGE_API_KEY, lalu panggil mage.run dengan model id dan config untuk mendapatkan gambar, video, atau audio jadi dari salah satu dari 37 model. SDK ini berjalan di Python 3.10 atau lebih baru, dan setiap pembuatan dibayar dengan Gems.

  • 3.10+Python
  • httpxKlien HTTP
  • 37Model bertipe
  • MITOpen source

Penyiapan

Instal SDK Python dan jalankan model

  1. Pasang paketnya

    Tambahkan mage-space ke proyekmu.

    pip install mage-space
  2. Atur API key-mu

    Buat kunci di API → API Keys di mage.space, lalu ekspor. Klien membaca MAGE_API_KEY.

    export MAGE_API_KEY="mage_sk_..."
  3. Buat

    Panggil run dengan id model dan konfigurasinya. Fungsi ini menunggu hasilnya dan mengembalikannya; keluarannya ada di 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"])

Contoh

SDK Python dalam praktik

Setiap contoh dimulai dari klien yang membaca MAGE_API_KEY.

Kirim sekarang, tunggu nanti
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"]),
)
Unggah file
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"]],
})
Pakai karakter tersimpan
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"})
Tangani error
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)

Kenapa SDK

Yang diurus SDK untukmu

  • Satu panggilan, media jadi

    run mengirim permintaan generasi, melakukan polling dengan backoff yang direkomendasikan API, lalu menghasilkan permintaan yang selesai beserta result.url.

  • Percobaan ulang tanpa bayar dua kali

    Setiap pengiriman membawa idempotency key. Error jaringan dan error server dicoba ulang dengan backoff, dan pengiriman ulang tidak pernah ditagih lagi.

  • Unggah dalam satu panggilan

    File yang terlalu besar untuk data URL diunggah lewat unggahan bertanda tangan, dengan tiket, PUT, dan pengecekan ukuran yang diurus untukmu.

  • Error yang jelas

    Penolakan API membawa status HTTP, kode error, dan request id; generasi yang gagal atau dibatalkan serta timeout punya tipe error masing-masing.

  • Sinkron dan asyncio

    Mage dan AsyncMage memiliki semua metode yang sama. Klien async cocok untuk server web, notebook, dan pipeline yang menjalankan banyak pembuatan sekaligus.

  • Konfigurasi bertipe

    Setiap model punya TypedDict, seperti MangoConfig, yang dibuat dari referensi API. Anotasikan konfigurasi dengannya dan type checker-mu akan memeriksa field-nya.

Referensi

SDK Python sekilas

Metode yang sama berlaku untuk semua model; modelnya menjadi argumen pertama.

MetodeFungsinya
mage.run(model, config)Kirim generasi, tunggu hingga selesai, lalu kembalikan permintaan yang sudah selesai.
mage.generate(model, config)Kirim generasi dan langsung kembalikan permintaannya.
mage.requests.get / cancel / waitBaca, hentikan, atau tunggu permintaan berdasarkan id.
mage.uploads.upload(data)Unggah path, bytes, atau file hingga 100 MB dan dapatkan URL-nya.
mage.characters / mage.referencesLihat daftar, buat, dan hapus karakter serta referensi tersimpan.
mage.account.get()Saldo Gems-mu.
mage.architectures.list()Katalog model terbaru lengkap dengan opsi dan harga.

Model

Mulai dengan model-model ini

  • Gambar · mulai dari 37 Gems

    Guava API

    Fotorealisme yang tampak seperti foto asli

  • Gambar · mulai dari 42 Gems

    Mango API

    Keluarga model gambar andalan kami

  • Gambar · mulai dari 51 Gems

    Nano Banana 2 API

    Teks tajam dan mudah dibaca, hingga 4K

  • Video · mulai dari 618 Gems

    Cherry API

    Keluarga model video andalan kami

  • Video · mulai dari 245 Gems

    Lemon API

    Semua fitur video dengan harga lebih bersahabat

  • Audio · mulai dari 19 Gems

    Seed Audio API

    Suara, musik, dan efek suara dari satu prompt

FAQ

Pertanyaan yang sering diajukan

Apakah SDK Python mendukung asyncio?
Ya. AsyncMage punya metode yang sama dengan Mage, dipanggil dengan await, dan bisa dipakai sebagai async context manager.
Versi Python apa saja yang didukung SDK?
Python 3.10 dan yang lebih baru. Dependensinya hanya httpx dan typing-extensions.
Bisakah aku memakai SDK Python di notebook atau pipeline data?
Bisa. Gunakan Mage di skrip dan notebook, atau AsyncMage dengan asyncio untuk menjalankan banyak pembuatan sekaligus. Akun dapat menjalankan hingga 20 pembuatan secara bersamaan.
Apakah SDK Mage gratis dan open source?
Ya. SDK dan node ComfyUI berlisensi MIT di GitHub, dan memasangnya gratis. Kamu hanya membayar generasi yang kamu jalankan, dalam Gems, sesuai harga yang tercantum untuk tiap model.
Apakah model Mage baru bisa dipakai dengan SDK versi lama?
Bisa. Berikan id model baru sebagai string, lalu model langsung berjalan; SDK memeriksa konfigurasinya terhadap kolom yang dimiliki semua model. Sebuah bot memperbarui tipe setiap kali referensi API berubah, jadi model baru hadir lengkap dengan tipenya sendiri di rilis berikutnya.
Bagaimana SDK mencegah pembayaran ganda saat permintaan dicoba ulang?
Setiap pengiriman membawa Idempotency-Key. SDK membuat kunci baru untuk setiap panggilan dan memakainya kembali saat SDK mencoba ulang panggilan itu sendiri, sehingga pengiriman yang diulang mengembalikan permintaan asli dan tidak dikenai biaya.
Apakah SDK-nya stabil?
SDK masih dalam versi beta di 0.x, jadi versi minor masih bisa mengubahnya. API-nya sendiri diberi versi terpisah dan tetap stabil di dalam v1.
Berapa biaya Mage API?
Tidak ada langganan atau biaya bulanan. Setiap generasi dibayar dengan Gems sesuai harga model tersebut, dan 1.000 Gems seharga $1 pada paket standar. Setiap halaman model mencantumkan harga dengan pengaturan default, dan setiap respons menyebutkan biaya yang tepat. Generasi yang gagal akan dikembalikan biayanya; yang diblokir oleh kebijakan konten Mage tidak. Permintaan yang tidak bisa ditutup oleh saldomu akan ditolak sebelum ada biaya yang dikenakan.
Apakah aku perlu keanggotaan Mage untuk memakai API?
Tidak. API hanya berjalan dengan Gems. Paket keanggotaan dan generasi tanpa batas di dalam aplikasi tidak berlaku untuk permintaan API. Akunmu harus melakukan satu pembayaran yang berhasil terlebih dahulu, baik untuk paket Gem maupun paket langganan apa pun; Gems bonus pendaftaran hanya bisa dipakai di aplikasi Mage.
Bolehkah hasil dari API dipakai untuk tujuan komersial?
Ya. Konten yang kamu buat dengan Mage, termasuk lewat API dan server MCP, boleh dipakai secara komersial. Atribusi kami hargai, tetapi tidak wajib.

Mulai berkarya dengan Mage

Satu akun, satu saldo Gems, semua model. Bayar hanya untuk yang kamu buat.

CharactersKomunitas