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-spaceSekilas 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
Pasang paketnya
Tambahkan mage-space ke proyekmu.
pip install mage-spaceAtur 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-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.
| 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
Guava API
Fotorealisme yang tampak seperti foto asli
Mango API
Keluarga model gambar andalan kami
Nano Banana 2 API
Teks tajam dan mudah dibaca, hingga 4K
Cherry API
Keluarga model video andalan kami
Lemon API
Semua fitur video dengan harga lebih bersahabat
Seed Audio API
Suara, musik, dan efek suara dari satu prompt
FAQ
Pertanyaan yang sering diajukan
Apakah SDK Python mendukung asyncio?
Versi Python apa saja yang didukung SDK?
Bisakah aku memakai SDK Python di notebook atau pipeline data?
Apakah SDK Mage gratis dan open source?
Apakah model Mage baru bisa dipakai dengan SDK versi lama?
Bagaimana SDK mencegah pembayaran ganda saat permintaan dicoba ulang?
Apakah SDK-nya stabil?
Berapa biaya Mage API?
Apakah aku perlu keanggotaan Mage untuk memakai API?
Bolehkah hasil dari API dipakai untuk tujuan komersial?
Mulai berkarya dengan Mage
Satu akun, satu saldo Gems, semua model. Bayar hanya untuk yang kamu buat.