Saltar al contenido

API de Mage · SDK

SDK oficiales para la API de Mage

Clientes tipados para TypeScript y Python, y nodos de Mage para ComfyUI. Todos los modelos de imagen, vídeo y audio en unas pocas líneas de código.

De un vistazo

Mage publica SDK de código abierto para su API: @mage-space/sdk en npm para TypeScript y JavaScript, mage-space en PyPI para Python y el paquete de nodos comfyui-mage para ComfyUI. Cada uno envuelve la API REST con configuraciones tipadas para los 37 modelos, sondeo automático, reintentos idempotentes y subidas de archivos.

  • 3SDK e integraciones
  • 37Modelos tipados
  • MITCódigo abierto
  • $0Para instalar

Elige el tuyo

SDK e integraciones

  • npm install @mage-space/sdk

    SDK de TypeScript

    Genera imágenes, vídeo y audio desde Node.js con configuraciones tipadas para cada modelo de Mage. Una sola llamada envía, espera y devuelve el resultado.

  • pip install mage-space

    SDK de Python

    Genera imágenes, vídeo y audio desde Python con clientes síncronos y asyncio, y configuraciones tipadas para cada modelo de Mage.

  • comfy node install comfyui-mage

    Mage para ComfyUI

    Mango, Cherry, Seed Audio y todos los demás modelos de Mage como nodos de ComfyUI. Sin GPU ni descargas de modelos.

Inicio rápido

Tu primera generación con un SDK

Instala el paquete, exporta MAGE_API_KEY y ejecuta un modelo.

TypeScript
// npm install @mage-space/sdk
import Mage from '@mage-space/sdk';

const mage = new Mage(); // reads MAGE_API_KEY

const request = await mage.run('mango', {
  prompt: 'Editorial portrait in soft daylight, 35mm film look',
  aspect_ratio: '4:5',
  model_id: 'mango-v4',
});

console.log(request.result.url);
Python
# pip install mage-space
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"])

Integrado

Lo que todos los SDK hacen 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.

Paquetes

Dónde conseguirlos

SDKPaqueteInstalaciónCódigo fuente
SDK de TypeScript@mage-space/sdknpm install @mage-space/sdkGitHub
SDK de Pythonmage-spacepip install mage-spaceGitHub
Mage para ComfyUIcomfyui-magecomfy node install comfyui-mageGitHub

Preguntas frecuentes

Preguntas frecuentes

¿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