SDK Mage · TypeScript
SDK TypeScript Mage
Buat gambar, video, dan audio dengan AI dari Node.js memakai konfigurasi bertipe untuk setiap model Mage. Satu panggilan mengirim, menunggu, dan mengembalikan hasilnya.
npm install @mage-space/sdkSekilas info
SDK TypeScript Mage adalah klien resmi open-source untuk Mage API, diterbitkan sebagai @mage-space/sdk. Instal dengan "npm install @mage-space/sdk", 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 Node.js 20.19 atau lebih baru, atau runtime server apa pun dengan fetch, dan setiap pembuatan dibayar dengan Gems.
- 20.19+Node.js
- 0Dependensi runtime
- 37Model bertipe
- MITOpen source
Penyiapan
Pasang SDK TypeScript dan jalankan model
Pasang paketnya
Tambahkan @mage-space/sdk ke proyekmu.
npm install @mage-space/sdkAtur 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.
import Mage from '@mage-space/sdk'; const mage = new Mage(); // reads MAGE_API_KEY const request = await mage.run('mango', { prompt: 'Editorial portrait in soft daylight, 35mm film look', aspect_ratio: '4:5', model_id: 'mango-v4', }); console.log(request.result.url);
Contoh
SDK TypeScript dalam praktik
Setiap contoh dimulai dari klien yang membaca MAGE_API_KEY.
Kirim sekarang, tunggu nanti
import Mage from '@mage-space/sdk';
const mage = new Mage(); // reads MAGE_API_KEY
const submitted = await mage.generate('cherry', {
prompt: 'Waves rolling onto a black sand beach at sunset',
resolution: '720p',
duration: '5',
});
const final = await mage.requests.wait(submitted.request_id, {
timeout: 15 * 60_000,
onUpdate: (request) => console.log(request.status),
});Unggah file
import { readFile } from 'node:fs/promises';
import Mage from '@mage-space/sdk';
const mage = new Mage(); // reads MAGE_API_KEY
const clip = await mage.uploads.upload(await readFile('clip.mp4'), {
contentType: 'video/mp4',
});
await mage.run('cherry', {
prompt: 'Restyle this clip as a watercolor painting',
videos: [clip.url],
});Pakai karakter tersimpan
import Mage from '@mage-space/sdk';
const mage = new Mage(); // reads MAGE_API_KEY
await mage.characters.create({
name: 'Ana',
handle: 'ana',
image: 'https://example.com/ana.png',
});
await mage.run('mango', { prompt: '@ana walking through a night market' });Tangani error
import Mage, { MageAPIError, MageGenerationError } from '@mage-space/sdk';
const mage = new Mage(); // reads MAGE_API_KEY
try {
await mage.run('mango', { prompt: 'A lighthouse at night' });
} catch (error) {
if (error instanceof MageAPIError && error.code === 'insufficient_gems') {
// Top up Gems, then try again.
} else if (error instanceof MageGenerationError) {
console.log('No output:', error.code);
} else {
throw error;
}
}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.
Bertipe untuk setiap model
MangoConfig, CherryConfig, dan lainnya dihasilkan dari referensi API, sehingga editor-mu melengkapi kolom dan menangkap opsi yang tidak valid.
Tanpa dependensi
ESM tanpa dependensi runtime. SDK memakai fetch bawaan Node.js, dan setiap panggilan menerima AbortSignal.
Referensi
Sekilas SDK TypeScript
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 file hingga 100 MB dan kembalikan 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
Bisakah saya memakai SDK TypeScript Mage di browser?
Apakah SDK TypeScript bisa dipakai dengan CommonJS?
Apakah SDK TypeScript bisa dipakai dengan Next.js?
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.