Langsung ke konten

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/sdk

Sekilas 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

  1. Pasang paketnya

    Tambahkan @mage-space/sdk ke proyekmu.

    npm install @mage-space/sdk
  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.

    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.

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 file hingga 100 MB dan kembalikan 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

Bisakah saya memakai SDK TypeScript Mage di browser?
Tidak. API key menghabiskan Gems-mu, jadi simpan di server-mu. API tidak mengirim header CORS, sehingga browser tidak bisa memanggilnya langsung; panggil backend-mu sendiri, lalu biarkan backend itu memakai SDK.
Apakah SDK TypeScript bisa dipakai dengan CommonJS?
Paket ini hanya ESM. Node.js 20.19 ke atas juga bisa memanggilnya dengan require() dari CommonJS.
Apakah SDK TypeScript bisa dipakai dengan Next.js?
Bisa, di kode server seperti route handler dan server action. SDK dibangun di atas fetch dan Web API standar seperti AbortSignal, jadi runtime server lain yang punya fetch seharusnya juga bisa, meski CI mengujinya di Node.js.
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