Mage SDK · TypeScript
Mage TypeScript SDK
Node.js ile görsel, video ve ses üret; her Mage modeli için tipli yapılandırmalar hazır. Tek çağrı gönderir, bekler ve sonucu döndürür.
npm install @mage-space/sdkBir bakışta
Mage TypeScript SDK'sı, @mage-space/sdk adıyla yayınlanan, Mage API için resmî açık kaynak istemcidir. "npm install @mage-space/sdk" ile kur, MAGE_API_KEY'i ayarla ve 37 modelden herhangi birinden hazır görsel, video veya ses almak için mage.run'ı bir model id'si ve bir yapılandırmayla çağır. Node.js 20.19 veya üzerinde ya da fetch destekleyen herhangi bir sunucu çalışma ortamında çalışır ve her üretim Gems ile ödenir.
- 20.19+Node.js
- 0Çalışma zamanı bağımlılıkları
- 37Tip tanımlı modeller
- MITAçık kaynak
Kurulum
TypeScript SDK'yı kur ve bir model çalıştır
Paketi kur
@mage-space/sdk paketini projene ekle.
npm install @mage-space/sdkAPI anahtarını ayarla
mage.space'te API → API Keys bölümünden bir anahtar oluştur ve dışa aktar. İstemci MAGE_API_KEY değerini okur.
export MAGE_API_KEY="mage_sk_..."Üret
run fonksiyonunu bir model kimliği ve yapılandırmasıyla çağır. Sonucu bekler ve döndürür; çıktı result.url adresindedir.
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);
Örnekler
TypeScript SDK uygulamada
Her örnek, MAGE_API_KEY değerini okuyan bir istemciyle başlar.
Şimdi gönder, sonra bekle
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),
});Dosya yükle
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],
});Kayıtlı bir karakter kullan
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' });Hataları yönet
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;
}
}Neden SDK
SDK senin için neleri halleder
Tek çağrı, hazır medya
run üretimi gönderir, API'nin önerdiği geri çekilme süreleriyle durumu yoklar ve result.url içeren tamamlanmış isteği döndürür.
İki kez ödetmeyen yeniden denemeler
Her istek bir idempotency anahtarı taşır. Ağ ve sunucu hataları geri çekilmeyle yeniden denenir, yeniden denenen istek için tekrar ücret alınmaz.
Tek çağrıda yükleme
Data URL için fazla büyük dosyalar imzalı yükleme üzerinden gider; bilet, PUT isteği ve boyut kontrolü senin yerine halledilir.
Anlaşılır hatalar
API ret yanıtları HTTP durumunu, hata kodunu ve istek kimliğini taşır; başarısız veya iptal edilen üretimlerin ve zaman aşımlarının kendi hata türleri vardır.
Her model için tipli
MangoConfig, CherryConfig ve diğerleri API referansından üretilir; böylece editörün alanları tamamlar ve geçersiz seçenekleri yakalar.
Sıfır bağımlılık
Çalışma zamanı bağımlılığı olmayan ESM. Node.js'in yerleşik fetch'ini kullanır ve her çağrı bir AbortSignal alır.
Referans
TypeScript SDK bir bakışta
Aynı yöntemler her modeli kapsar; model ilk argümandır.
| Yöntem | Ne yapar? |
|---|---|
| mage.run(model, config) | Bir üretim gönderir, bitmesini bekler ve tamamlanan isteği döndürür. |
| mage.generate(model, config) | Bir üretim gönderir ve isteği hemen döndürür. |
| mage.requests.get / cancel / wait | Bir isteği kimliğiyle okur, durdurur veya bekler. |
| mage.uploads.upload(data) | En fazla 100 MB'lık bir dosya yükler ve URL'sini döndürür. |
| mage.characters / mage.references | Kayıtlı karakterleri ve referansları listeler, oluşturur ve siler. |
| mage.account.get() | Gems bakiyen. |
| mage.architectures.list() | Seçenekleri ve fiyatlarıyla güncel model kataloğu. |
Modeller
Bu modellerle başla
Guava API
Fotoğraf sanılacak kadar gerçekçi görseller
Mango API
Amiral gemisi görsel model ailemiz
Nano Banana 2 API
Net, okunaklı metin, 4K'ya kadar
Cherry API
Amiral gemisi video model ailemiz
Lemon API
Tüm video özellikleri, daha uygun fiyata
Seed Audio API
Tek bir prompt'tan sesler, müzik ve ses efektleri
SSS
Sık sorulan sorular
Mage TypeScript SDK'yı tarayıcıda kullanabilir miyim?
TypeScript SDK CommonJS ile çalışır mı?
TypeScript SDK Next.js ile çalışır mı?
Mage SDK'ları ücretsiz ve açık kaynak mı?
Yeni Mage modelleri eski bir SDK ile çalışır mı?
SDK'lar yeniden denenen bir istek için iki kez ödeme yapılmasını nasıl önler?
SDK'lar kararlı mı?
Mage API ne kadar?
API'yi kullanmak için Mage üyeliği gerekir mi?
API çıktılarını ticari amaçla kullanabilir miyim?
Mage ile geliştirmeye başla
Tek hesap, tek Gems bakiyesi, tüm modeller. Yalnızca ürettiğin kadar öde.