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.
Resumo rápido
O Mage publica SDKs de código aberto para a sua API: @mage-space/sdk no npm para TypeScript e JavaScript, mage-space no PyPI para Python e o pacote de nodes comfyui-mage para ComfyUI. Cada um envolve a API REST com configurações tipadas para todos os 28 modelos, polling automático, novas tentativas idempotentes e uploads.
3
SDKs e integrações
28
Modelos tipados
MIT
Código aberto
$0
Para instalar
Escolha o seu
SDKs e integrações
npm install @mage-space/sdk
SDK para TypeScript
Gere imagens, vídeos e áudios no Node.js com configurações tipadas para cada modelo do Mage. Uma só chamada envia, aguarda e retorna o resultado.
pip install mage-space
SDK para Python
Gere imagens, vídeos e áudios em Python com clientes síncronos e asyncio e configurações tipadas para cada modelo do Mage.
comfy node install comfyui-mage
Mage para ComfyUI
Mango, Cherry, Seed Audio e todos os outros modelos do Mage como nós do ComfyUI. Sem GPU, sem baixar modelos.
Início rápido
Sua primeira geração com um SDK
Instale o pacote, exporte MAGE_API_KEY e execute um modelo.
TypeScript
// npm install @mage-space/sdk
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-v3',
});
console.log(request.result.url);Python
# pip install mage-space
from mage_space import Mage
mage = Mage() # reads MAGE_API_KEY
request = mage.run("mango", {
"prompt": "Editorial portrait in soft daylight, 35mm film look",
"aspect_ratio": "4:5",
"model_id": "mango-v3",
})
print(request["result"]["url"])Já incluído
O que todo SDK faz por você
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.
Pacotes
Onde encontrá-los
| SDK | Pacote | Instalação | Código-fonte |
|---|---|---|---|
| SDK para TypeScript | @mage-space/sdk | npm install @mage-space/sdk | GitHub |
| SDK para Python | mage-space | pip install mage-space | GitHub |
| Mage para ComfyUI | comfyui-mage | comfy node install comfyui-mage | GitHub |
Perguntas frequentes
Perguntas frequentes
Os SDKs do Mage são gratuitos e de código aberto?
Sim. Os SDKs e os nodes do ComfyUI têm licença MIT no GitHub, e instalá-los é grátis. Você paga apenas pelas gerações que executar, em Gems, pelo preço listado de cada modelo.
Os novos modelos do Mage funcionam com um SDK mais antigo?
Sim. Passe o id do novo modelo como string e ele roda; o SDK confere a configuração com os campos que todos os modelos compartilham. Um bot atualiza os tipos sempre que a referência da API muda, então os novos modelos chegam com seus próprios tipos na versão seguinte.
Como os SDKs evitam cobrar duas vezes por uma requisição repetida?
Todo envio leva uma Idempotency-Key. O SDK cria uma nova chave a cada chamada e a reutiliza quando ele mesmo tenta essa chamada de novo, então um envio repetido retorna a requisição original e não cobra nada.
Os SDKs são estáveis?
Eles estão em beta na versão 0.x, então uma versão secundária ainda pode alterá-los. A API em si tem versionamento separado e permanece estável dentro da v1.
Quanto custa a API do Mage?
Não há assinatura nem mensalidade. Cada geração é paga em Gems, pelo preço listado do modelo, e 1.000 Gems custam US$ 1 no pacote padrão. A página de cada modelo mostra o preço com as configurações padrão, e cada resposta informa o valor exato cobrado. Uma geração que falha é reembolsada; uma bloqueada pela política de conteúdo do Mage, não. Uma requisição que o seu saldo não cobre é recusada antes de qualquer cobrança.
Preciso ser membro do Mage para usar a API?
Não. A API funciona apenas com Gems. Os planos de assinatura e a geração ilimitada no app não valem para requisições de API, então qualquer conta do Mage com Gems pode usá-la.
Posso usar os resultados da API para fins comerciais?
Sim. O conteúdo que você cria com o Mage, inclusive pela API e pelo servidor MCP, pode ser usado comercialmente. Os créditos são bem-vindos, mas não obrigatórios.
Comece a criar com o Mage
Uma conta, um saldo de Gems, todos os modelos. Pague apenas pelo que você gerar.