SDK do Mage · Python

O SDK Python do Mage

Gere imagens, vídeos e áudios com Python usando clientes síncrono e asyncio e configs tipadas para todos os modelos do Mage.

Obter uma chave de API Ler o guia de Python Código-fonte no GitHub

pip install mage-space

Resumo rápido

O SDK Python do Mage é o cliente oficial e de código aberto da API do Mage, publicado como mage-space. Instale com "pip install mage-space", defina MAGE_API_KEY e chame mage.run com um id de modelo e uma config para receber imagens, vídeos ou áudios prontos de qualquer um dos 28 modelos. Ele funciona com Python 3.10 ou superior, e toda geração é paga em Gems.

3.10+
Python
httpx
Cliente HTTP
28
Modelos tipados
MIT
Código aberto

Configuração

Instale o SDK Python e execute um modelo

01
Instale o pacote
Adicione o mage-space ao seu projeto.
```
pip install mage-space
```
02
Defina 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.

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"])

Exemplos

O SDK Python na prática

Cada exemplo parte de um cliente que lê MAGE_API_KEY.

Envie agora, espere depois

from mage_space import Mage

mage = Mage()  # reads MAGE_API_KEY

submitted = mage.generate("cherry", {
    "prompt": "Waves rolling onto a black sand beach at sunset",
    "resolution": "720p",
    "duration": "5",
})

final = mage.requests.wait(
    submitted["request_id"],
    timeout=900,
    on_update=lambda request: print(request["status"]),
)

Enviar um arquivo

from mage_space import Mage

mage = Mage()  # reads MAGE_API_KEY

clip = mage.uploads.upload("clip.mp4")  # a path, bytes, or a binary file

mage.run("cherry", {
    "prompt": "Restyle this clip as a watercolor painting",
    "videos": [clip["url"]],
})

Usar um personagem salvo

from mage_space import Mage

mage = Mage()  # reads MAGE_API_KEY

mage.characters.create(
    name="Ana",
    handle="ana",
    image="https://example.com/ana.png",
)

mage.run("mango", {"prompt": "@ana walking through a night market"})

Tratar erros

from mage_space import Mage, MageAPIError, MageGenerationError

mage = Mage()  # reads MAGE_API_KEY

try:
    mage.run("mango", {"prompt": "A lighthouse at night"})
except MageAPIError as error:
    if error.code == "insufficient_gems":
        print("Gems needed:", error.body["error"]["gems_required"])
    else:
        raise
except MageGenerationError as error:
    print("No output:", error.code)

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.

Síncrono e asyncio

Mage e AsyncMage têm os mesmos métodos. O cliente assíncrono é ideal para servidores web, notebooks e pipelines que executam várias gerações ao mesmo tempo.

Configs tipadas

Cada modelo tem um TypedDict, como MangoConfig, gerado a partir da referência da API. Anote uma config com ele e seu verificador de tipos confere os campos.

Referência

O SDK Python 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)	Envie um caminho, bytes ou arquivo de até 100 MB e receba 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

Imagem · a partir de 37 Gems

API do Guava

Fotorrealismo que parece uma fotografia de verdade

Imagem · a partir de 135 Gems

API do Mango

Nossa família de imagens principal

Imagem · a partir de 68 Gems

API do Nano Banana 2

Texto nítido e legível, até 4K

Vídeo · a partir de 618 Gems

API do Cherry

Nossa família de vídeos principal

Vídeo · a partir de 245 Gems

API do Lemon

Todos os recursos de vídeo, por um preço mais amigável

Áudio · a partir de 19 Gems

API do Seed Audio

Vozes, música e efeitos sonoros a partir de um único prompt

Perguntas frequentes

O SDK Python é compatível com asyncio?

Sim. O AsyncMage tem os mesmos métodos do Mage, com await, e funciona como gerenciador de contexto assíncrono.

Quais versões do Python o SDK suporta?

Python 3.10 ou superior. As únicas dependências são httpx e typing-extensions.

Posso usar o SDK Python em um notebook ou em um pipeline de dados?

Sim. Use o Mage em scripts e notebooks, ou o AsyncMage com asyncio para executar várias gerações ao mesmo tempo. A conta pode ter até 20 gerações em andamento.

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.

Obter uma chave de API Ler o guia de Python