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.

Dapatkan kunci API Baca panduan Python Kode sumber di GitHub

pip install mage-space

Sekilas info

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

3.10+
Python
httpx
Klien HTTP
28
Model bertipe
MIT
Open source

Penyiapan

Instal SDK Python dan jalankan model

01
Pasang paketnya
Tambahkan mage-space ke proyekmu.
```
pip install mage-space
```
02
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_..."
```

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-v3",
})

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.

Metode	Fungsinya
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 / wait	Baca, 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.references	Lihat 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 135 Gems

Mango API

Keluarga model gambar andalan kami

Gambar · mulai dari 68 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 berjalan hanya dengan Gems. Paket keanggotaan beserta generasi tanpa batas di dalam aplikasi tidak berlaku untuk permintaan API, jadi akun Mage mana pun yang punya Gems bisa memakainya.

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.

Dapatkan kunci API Baca panduan Python