SDK de Mage · Python
El SDK de Mage para Python
Genera imágenes, video y audio con IA desde Python, con clientes síncrono y asyncio y configuraciones tipadas para cada modelo de Mage.
pip install mage-spaceDe un vistazo
El SDK de Python de Mage es el cliente oficial y de código abierto de la API de Mage, publicado como mage-space. Instálalo con "pip install mage-space", define MAGE_API_KEY y llama a mage.run con un id de modelo y una configuración para obtener imágenes, video o audio terminados de cualquiera de los 37 modelos. Funciona en Python 3.10 o posterior, y cada generación se paga en Gems.
- 3.10+Python
- httpxCliente HTTP
- 37Modelos tipados
- MITCódigo abierto
Configuración
Instala el SDK de Python y ejecuta un modelo
Instala el paquete
Añade mage-space a tu proyecto.
pip install mage-spaceDefine tu clave de API
Crea una clave en API → API Keys en mage.space y expórtala. El cliente lee MAGE_API_KEY.
export MAGE_API_KEY="mage_sk_..."Genera
Llama a run con un id de modelo y su configuración. Espera el resultado y lo devuelve; la salida está en 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"])
Ejemplos
El SDK de Python en la práctica
Cada ejemplo parte de un cliente que lee MAGE_API_KEY.
Envía ahora, espera después
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"]),
)Sube un archivo
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"]],
})Usa un personaje guardado
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"})Gestiona los errores
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 qué el SDK
Lo que el SDK hace por ti
Una llamada, contenido terminado
run envía la generación, consulta el estado con el backoff que recomienda la API y se resuelve con la solicitud completada y result.url.
Reintentos que nunca cobran dos veces
Cada envío lleva una clave de idempotencia. Los errores de red y de servidor se reintentan con backoff, y un envío reintentado nunca se cobra de nuevo.
Subidas en una llamada
Los archivos demasiado grandes para una URL de datos pasan por una subida firmada, y el ticket, el PUT y la comprobación de tamaño se gestionan por ti.
Errores claros
Los rechazos de la API incluyen su estado HTTP, código de error e ID de solicitud; las generaciones fallidas o canceladas y los tiempos de espera agotados tienen sus propios tipos de error.
Síncrono y asyncio
Mage y AsyncMage comparten todos los métodos. El cliente asíncrono encaja con servidores web, notebooks y pipelines que ejecutan muchas generaciones a la vez.
Configuraciones tipadas
Cada modelo tiene un TypedDict, como MangoConfig, generado a partir de la referencia de la API. Anota una configuración con él y tu verificador de tipos comprobará los campos.
Referencia
El SDK de Python de un vistazo
Los mismos métodos sirven para todos los modelos; el modelo es el primer argumento.
| Método | Qué hace |
|---|---|
| mage.run(model, config) | Envía una generación, espera a que termine y devuelve la solicitud completada. |
| mage.generate(model, config) | Envía una generación y devuelve la solicitud de inmediato. |
| mage.requests.get / cancel / wait | Consulta, detén o espera una solicitud por su id. |
| mage.uploads.upload(data) | Sube una ruta, bytes o un archivo de hasta 100 MB y devuelve su URL. |
| mage.characters / mage.references | Lista, crea y elimina personajes y referencias guardados. |
| mage.account.get() | Tu saldo de Gems. |
| mage.architectures.list() | El catálogo de modelos en vivo con opciones y precios. |
Modelos
Empieza con estos modelos
API de Guava
Fotorrealismo que parece una fotografía
API de Mango
Nuestra familia de imágenes insignia
API de Nano Banana 2
Texto nítido y legible, hasta 4K
API de Cherry
Nuestra familia de vídeo insignia
API de Lemon
Todas las funciones de vídeo, a un precio más amable
API de Seed Audio
Voces, música y efectos de sonido con un solo prompt
Preguntas frecuentes
Preguntas frecuentes
¿El SDK de Python es compatible con asyncio?
¿Qué versiones de Python admite el SDK?
¿Puedo usar el SDK de Python en un notebook o en un pipeline de datos?
¿Los SDK de Mage son gratuitos y de código abierto?
¿Los modelos nuevos de Mage funcionan con un SDK anterior?
¿Cómo evitan los SDK pagar dos veces por una solicitud reintentada?
¿Son estables los SDK?
¿Cuánto cuesta la API de Mage?
¿Necesito una membresía de Mage para usar la API?
¿Puedo usar comercialmente los resultados de la API?
Empieza a crear con Mage
Una cuenta, un saldo de Gems, todos los modelos. Paga solo por lo que generes.