Saltar al contenido

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-space

De 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

  1. Instala el paquete

    Añade mage-space a tu proyecto.

    pip install mage-space
  2. Define 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_..."
  3. 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étodoQué 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 / waitConsulta, 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.referencesLista, 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

  • Imagen · desde 37 Gems

    API de Guava

    Fotorrealismo que parece una fotografía

  • Imagen · desde 42 Gems

    API de Mango

    Nuestra familia de imágenes insignia

  • Imagen · desde 51 Gems

    API de Nano Banana 2

    Texto nítido y legible, hasta 4K

  • Vídeo · desde 618 Gems

    API de Cherry

    Nuestra familia de vídeo insignia

  • Vídeo · desde 245 Gems

    API de Lemon

    Todas las funciones de vídeo, a un precio más amable

  • Audio · desde 19 Gems

    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?
Sí. AsyncMage tiene los mismos métodos que Mage, con await, y funciona como gestor de contexto asíncrono.
¿Qué versiones de Python admite el SDK?
Python 3.10 y posteriores. Sus únicas dependencias son httpx y typing-extensions.
¿Puedo usar el SDK de Python en un notebook o en un pipeline de datos?
Sí. Usa Mage en scripts y notebooks, o AsyncMage con asyncio para ejecutar muchas generaciones a la vez. La cuenta admite hasta 20 generaciones en curso.
¿Los SDK de Mage son gratuitos y de código abierto?
Sí. Los SDK y los nodos de ComfyUI tienen licencia MIT en GitHub y instalarlos es gratis. Solo pagas por las generaciones que ejecutes, en Gems, al precio que figura para cada modelo.
¿Los modelos nuevos de Mage funcionan con un SDK anterior?
Sí. Pasa el id del nuevo modelo como cadena y se ejecuta; el SDK comprueba su configuración con los campos que comparten todos los modelos. Un bot actualiza los tipos cada vez que cambia la referencia de la API, así que los modelos nuevos llegan con sus propios tipos en la siguiente versión.
¿Cómo evitan los SDK pagar dos veces por una solicitud reintentada?
Cada envío lleva una Idempotency-Key. El SDK genera una clave nueva por llamada y la reutiliza cuando reintenta esa llamada por su cuenta, así que un envío reintentado devuelve la solicitud original y no cobra nada.
¿Son estables los SDK?
Están en beta en la versión 0.x, así que una versión menor aún puede cambiarlos. La API en sí tiene su propio versionado y se mantiene estable dentro de v1.
¿Cuánto cuesta la API de Mage?
No hay suscripción ni cuota mensual. Cada generación se paga en Gems al precio indicado de su modelo, y 1000 Gems cuestan 1 $ en el paquete estándar. La página de cada modelo muestra su precio con la configuración por defecto, y cada respuesta indica el cargo exacto. Si una generación falla, se reembolsa; si la política de contenido de Mage la bloquea, no. Una solicitud que tu saldo no pueda cubrir se rechaza antes de cobrar nada.
¿Necesito una membresía de Mage para usar la API?
No. La API funciona solo con Gems. Los planes de membresía y su generación ilimitada dentro de la app no se aplican a las solicitudes a la API. Antes, la cuenta necesita un primer pago completado, ya sea un paquete de Gems o un plan; los Gems de bonificación por registrarte solo funcionan en la app de Mage.
¿Puedo usar comercialmente los resultados de la API?
Sí. El contenido que creas con Mage, también a través de la API y el servidor MCP, se puede usar con fines comerciales. Se agradece la atribución, pero no es obligatoria.

Empieza a crear con Mage

Una cuenta, un saldo de Gems, todos los modelos. Paga solo por lo que generes.

CharactersComunidad