SDK de Mage · TypeScript
El SDK de TypeScript de Mage
Genera imágenes, video y audio desde Node.js con configuraciones tipadas para cada modelo de Mage. Una sola llamada envía, espera y devuelve el resultado.
npm install @mage-space/sdkDe un vistazo
El SDK de TypeScript de Mage es el cliente oficial y de código abierto de la API de Mage, publicado como @mage-space/sdk. Instálalo con "npm install @mage-space/sdk", define MAGE_API_KEY y llama a mage.run con un id de modelo y una configuración para obtener imágenes, video o audio terminados de cualquiera de los 37 modelos. Funciona en Node.js 20.19 o posterior, o en cualquier entorno de servidor con fetch, y cada generación se paga en Gems.
- 20.19+Node.js
- 0Dependencias en tiempo de ejecución
- 37Modelos tipados
- MITCódigo abierto
Configuración
Instala el SDK de TypeScript y ejecuta un modelo
Instala el paquete
Añade @mage-space/sdk a tu proyecto.
npm install @mage-space/sdkDefine tu clave de API
Crea una clave en API → API Keys en mage.space y expórtala. El cliente lee MAGE_API_KEY.
export MAGE_API_KEY="mage_sk_..."Genera
Llama a run con un id de modelo y su configuración. Espera el resultado y lo devuelve; la salida está en 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);
Ejemplos
El SDK de TypeScript en la práctica
Cada ejemplo parte de un cliente que lee MAGE_API_KEY.
Envía ahora, espera después
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),
});Sube un archivo
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],
});Usa un personaje guardado
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' });Gestiona los errores
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;
}
}Por qué el SDK
Lo que el SDK hace por ti
Una llamada, contenido terminado
run envía la generación, consulta el estado con el backoff que recomienda la API y se resuelve con la solicitud completada y result.url.
Reintentos que nunca cobran dos veces
Cada envío lleva una clave de idempotencia. Los errores de red y de servidor se reintentan con backoff, y un envío reintentado nunca se cobra de nuevo.
Subidas en una llamada
Los archivos demasiado grandes para una URL de datos pasan por una subida firmada, y el ticket, el PUT y la comprobación de tamaño se gestionan por ti.
Errores claros
Los rechazos de la API incluyen su estado HTTP, código de error e ID de solicitud; las generaciones fallidas o canceladas y los tiempos de espera agotados tienen sus propios tipos de error.
Tipado para cada modelo
MangoConfig, CherryConfig y los demás se generan a partir de la referencia de la API, así que tu editor autocompleta los campos y detecta opciones no válidas.
Cero dependencias
ESM sin dependencias en tiempo de ejecución. Usa el fetch integrado en Node.js y cada llamada acepta una AbortSignal.
Referencia
El SDK de TypeScript de un vistazo
Los mismos métodos sirven para todos los modelos; el modelo es el primer argumento.
| Método | Qué hace |
|---|---|
| mage.run(model, config) | Envía una generación, espera a que termine y devuelve la solicitud completada. |
| mage.generate(model, config) | Envía una generación y devuelve la solicitud de inmediato. |
| mage.requests.get / cancel / wait | Consulta, detén o espera una solicitud por su id. |
| mage.uploads.upload(data) | Sube un archivo de hasta 100 MB y devuelve su URL. |
| mage.characters / mage.references | Lista, crea y elimina personajes y referencias guardados. |
| mage.account.get() | Tu saldo de Gems. |
| mage.architectures.list() | El catálogo de modelos en vivo con opciones y precios. |
Modelos
Empieza con estos modelos
API de Guava
Fotorrealismo que parece una fotografía
API de Mango
Nuestra familia de imágenes insignia
API de Nano Banana 2
Texto nítido y legible, hasta 4K
API de Cherry
Nuestra familia de vídeo insignia
API de Lemon
Todas las funciones de vídeo, a un precio más amable
API de Seed Audio
Voces, música y efectos de sonido con un solo prompt
Preguntas frecuentes
Preguntas frecuentes
¿Puedo usar el SDK de TypeScript de Mage en el navegador?
¿El SDK de TypeScript funciona con CommonJS?
¿El SDK de TypeScript funciona con Next.js?
¿Los SDK de Mage son gratuitos y de código abierto?
¿Los modelos nuevos de Mage funcionan con un SDK anterior?
¿Cómo evitan los SDK pagar dos veces por una solicitud reintentada?
¿Son estables los SDK?
¿Cuánto cuesta la API de Mage?
¿Necesito una membresía de Mage para usar la API?
¿Puedo usar comercialmente los resultados de la API?
Empieza a crear con Mage
Una cuenta, un saldo de Gems, todos los modelos. Paga solo por lo que generes.