Pular para o conteúdo

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.

pip install mage-space

Resumo rápido

O SDK do Mage para Python é 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 configuração para obter imagens, vídeos ou áudio prontos de qualquer um dos 37 modelos. Ele roda no Python 3.10 ou superior, e cada geração é paga em Gems.

  • 3.10+Python
  • httpxCliente HTTP
  • 37Modelos tipados
  • MITCódigo aberto

Configuração

Instale o SDK Python e execute um modelo

  1. Instale o pacote

    Adicione o mage-space ao seu projeto.

    pip install mage-space
  2. 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_..."
  3. 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-v4",
    })
    
    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étodoO 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 / waitConsulta, 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.referencesLista, 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 42 Gems

    API do Mango

    Nossa família de imagens principal

  • Imagem · a partir de 51 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

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 somente com Gems. Os planos de assinatura e a geração ilimitada no app não valem para requisições da API. Antes de tudo, a conta precisa ter um pagamento aprovado, seja de um pacote de Gems ou de um plano. Os Gems de bônus de cadastro funcionam apenas no app do Mage.
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.

CharactersComunidade