Mage SDK · TypeScript
Mage TypeScript SDK
Generuj obrazy, wideo i audio z poziomu Node.js dzięki typowanym konfiguracjom każdego modelu Mage. Jedno wywołanie wysyła zadanie, czeka i zwraca wynik.
npm install @mage-space/sdkW skrócie
SDK Mage dla TypeScriptu to oficjalny, otwartoźródłowy klient API Mage, publikowany jako @mage-space/sdk. Zainstaluj je poleceniem „npm install @mage-space/sdk”, ustaw MAGE_API_KEY i wywołaj mage.run z id modelu i konfiguracją, aby dostać gotowe obrazy, wideo lub dźwięk z dowolnego z 37 modeli. Działa na Node.js 20.19 lub nowszym albo w dowolnym środowisku serwerowym z fetch, a każda generacja jest płatna w Gems.
- 20.19+Node.js
- 0Zależności uruchomieniowe
- 37Typowane modele
- MITOpen source
Konfiguracja
Zainstaluj SDK TypeScript i uruchom model
Zainstaluj pakiet
Dodaj @mage-space/sdk do swojego projektu.
npm install @mage-space/sdkUstaw klucz API
Utwórz klucz w API → API Keys na mage.space i wyeksportuj go. Klient odczytuje MAGE_API_KEY.
export MAGE_API_KEY="mage_sk_..."Generuj
Wywołaj run z ID modelu i jego konfiguracją. Metoda czeka na wynik i go zwraca; wynik znajdziesz w 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);
Przykłady
SDK TypeScript w praktyce
Każdy przykład zaczyna się od klienta, który odczytuje MAGE_API_KEY.
Wyślij teraz, poczekaj później
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),
});Prześlij plik
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],
});Użyj zapisanej postaci
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' });Obsługa błędów
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;
}
}Dlaczego SDK
Co SDK robi za ciebie
Jedno wywołanie, gotowe media
run wysyła generację, odpytuje API z zalecanym przez nie opóźnieniem (backoff) i zwraca ukończone zgłoszenie z result.url.
Ponowienia, które nigdy nie kosztują podwójnie
Każde zgłoszenie ma klucz idempotentności. Błędy sieci i serwera są ponawiane z opóźnieniem (backoff), a ponowione zgłoszenie nigdy nie jest rozliczane drugi raz.
Przesyłanie plików jednym wywołaniem
Pliki zbyt duże na data URL trafiają przez podpisany upload, a bilet, żądanie PUT i sprawdzenie rozmiaru obsługujemy za Ciebie.
Czytelne błędy
Odmowy API zawierają status HTTP, kod błędu i identyfikator żądania, a nieudane lub anulowane generacje i przekroczenia czasu mają własne typy błędów.
Typy dla każdego modelu
MangoConfig, CherryConfig i pozostałe są generowane z dokumentacji API, więc edytor podpowiada pola i wychwytuje nieprawidłowe opcje.
Zero zależności
ESM bez zależności uruchomieniowych. Korzysta z wbudowanego w Node.js fetch, a każde wywołanie przyjmuje AbortSignal.
Dokumentacja
SDK TypeScript w skrócie
Te same metody obsługują każdy model; model jest pierwszym argumentem.
| Metoda | Co robi |
|---|---|
| mage.run(model, config) | Wysyła generowanie, czeka na nie i zwraca ukończone żądanie. |
| mage.generate(model, config) | Wysyła generowanie i od razu zwraca żądanie. |
| mage.requests.get / cancel / wait | Odczytaj, zatrzymaj lub poczekaj na żądanie według ID. |
| mage.uploads.upload(data) | Przesyła plik do 100 MB i zwraca jego URL. |
| mage.characters / mage.references | Wyświetla, tworzy i usuwa zapisane postaci oraz referencje. |
| mage.account.get() | Twoje saldo Gems. |
| mage.architectures.list() | Aktualny katalog modeli z opcjami i cenami. |
Modele
Zacznij od tych modeli
Guava API
Fotorealizm, który uchodzi za prawdziwe zdjęcie
Mango API
Nasza flagowa rodzina modeli obrazu
Nano Banana 2 API
Wyraźny, czytelny tekst, do 4K
Cherry API
Nasza flagowa rodzina modeli wideo
Lemon API
Wszystkie funkcje wideo w bardziej przyjaznej cenie
Seed Audio API
Głosy, muzyka i efekty dźwiękowe z jednego promptu
FAQ
Najczęściej zadawane pytania
Czy mogę używać Mage TypeScript SDK w przeglądarce?
Czy SDK TypeScript działa z CommonJS?
Czy SDK TypeScript działa z Next.js?
Czy SDK Mage są darmowe i open source?
Czy nowe modele Mage działają ze starszym SDK?
Jak SDK chroni przed podwójną opłatą za ponowione żądanie?
Czy SDK są stabilne?
Ile kosztuje Mage API?
Czy potrzebuję członkostwa w Mage, żeby korzystać z API?
Czy mogę używać wyników z API komercyjnie?
Zacznij tworzyć z Mage
Jedno konto, jedno saldo Gems, wszystkie modele. Płacisz tylko za to, co wygenerujesz.