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-spaceResumo 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
Instale o pacote
Adicione o mage-space ao seu projeto.
pip install mage-spaceDefina 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-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é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
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
O SDK Python é compatível com asyncio?
Quais versões do Python o SDK suporta?
Posso usar o SDK Python em um notebook ou em um pipeline de dados?
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.