SDK do Mage · TypeScript
O SDK TypeScript do Mage
Gere imagens, vídeos e áudio com Node.js usando configurações tipadas para cada modelo do Mage. Uma única chamada envia, espera e retorna o resultado.
npm install @mage-space/sdkResumo rápido
O SDK do Mage para TypeScript é o cliente oficial e de código aberto da API do Mage, publicado como @mage-space/sdk. Instale com "npm install @mage-space/sdk", defina MAGE_API_KEY e chame mage.run com um id de modelo e uma configuração para obter imagens, vídeos ou áudio prontos de qualquer um dos 37 modelos. Ele roda no Node.js 20.19 ou superior, ou em qualquer ambiente de servidor com fetch, e cada geração é paga em Gems.
- 20.19+Node.js
- 0Dependências de runtime
- 37Modelos tipados
- MITCódigo aberto
Configuração
Instale o SDK TypeScript e rode um modelo
Instale o pacote
Adicione @mage-space/sdk ao seu projeto.
npm install @mage-space/sdkDefina sua chave de API
Crie uma chave em API → API Keys em mage.space e exporte-a. O cliente lê MAGE_API_KEY.
export MAGE_API_KEY="mage_sk_..."Gere
Chame run com o id de um modelo e sua configuração. Ele espera o resultado e o retorna; a saída fica em 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);
Exemplos
O SDK TypeScript na prática
Cada exemplo parte de um cliente que lê MAGE_API_KEY.
Envie agora, espere depois
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),
});Enviar um arquivo
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],
});Usar um personagem salvo
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' });Tratar erros
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 que usar o SDK
O que o SDK resolve para você
Uma chamada, mídia pronta
O run envia a geração, faz polling com o backoff recomendado pela API e retorna a requisição concluída com result.url.
Novas tentativas sem cobrar duas vezes
Todo envio leva uma chave de idempotência. Erros de rede e de servidor são repetidos com backoff, e um envio repetido nunca é cobrado de novo.
Uploads em uma chamada
Arquivos grandes demais para uma data URL passam por um upload assinado, com ticket, PUT e verificação de tamanho tratados para você.
Erros claros
As recusas da API trazem o status HTTP, o código de erro e o ID da requisição; gerações com falha ou canceladas e timeouts têm tipos de erro próprios.
Tipado para todos os modelos
MangoConfig, CherryConfig e os demais são gerados a partir da referência da API, então seu editor completa os campos e aponta opções inválidas.
Zero dependências
ESM sem dependências de runtime. Usa o fetch nativo do Node.js, e toda chamada aceita um AbortSignal.
Referência
O SDK TypeScript em resumo
Os mesmos métodos servem para todos os modelos; o modelo é o primeiro argumento.
| Método | O que faz |
|---|---|
| mage.run(model, config) | Envia uma geração, espera por ela e retorna a requisição concluída. |
| mage.generate(model, config) | Envia uma geração e retorna a requisição imediatamente. |
| mage.requests.get / cancel / wait | Consulta, interrompe ou espera uma requisição pelo id. |
| mage.uploads.upload(data) | Envia um arquivo de até 100 MB e retorna a URL dele. |
| mage.characters / mage.references | Lista, cria e exclui personagens e referências salvos. |
| mage.account.get() | Seu saldo de Gems. |
| mage.architectures.list() | O catálogo de modelos em tempo real, com opções e preços. |
Modelos
Comece com estes modelos
API do Guava
Fotorrealismo que parece uma fotografia de verdade
API do Mango
Nossa família de imagens principal
API do Nano Banana 2
Texto nítido e legível, até 4K
API do Cherry
Nossa família de vídeos principal
API do Lemon
Todos os recursos de vídeo, por um preço mais amigável
API do Seed Audio
Vozes, música e efeitos sonoros a partir de um único prompt
Perguntas frequentes
Perguntas frequentes
Posso usar o SDK TypeScript do Mage no navegador?
O SDK TypeScript funciona com CommonJS?
O SDK TypeScript funciona com Next.js?
Os SDKs do Mage são gratuitos e de código aberto?
Os novos modelos do Mage funcionam com um SDK mais antigo?
Como os SDKs evitam cobrar duas vezes por uma requisição repetida?
Os SDKs são estáveis?
Quanto custa a API do Mage?
Preciso ser membro do Mage para usar a API?
Posso usar os resultados da API para fins comerciais?
Comece a criar com o Mage
Uma conta, um saldo de Gems, todos os modelos. Pague apenas pelo que você gerar.