GenMagic
Servidor MCP alojado para más de 450 modelos de IA: genera imágenes, video, voz, música y texto con una sola clave de API y un saldo de pago por uso. Elige cualquier modelo por id (list_models muestra ids y precios) o deja que GenMagic elija; el video se cobra solo cuando se completa.
Servidor MCP alojado
npx add-mcp 'https://genmagic.co/api/mcp'Se instala en Claude Code, Codex, Cursor y más
Documentación
La API de GenMagic
Endpoints compatibles con OpenAI para cada modelo de texto y visión, para generación de imágenes, para voz y música, y para video, una llamada tipada a /text para artefactos alineados con tu marca, además de un servidor MCP para agentes. Apunta cualquier SDK de OpenAI a tu URL base, introduce una clave y listo. Una llamada desde tu código cuesta exactamente lo mismo que una llamada desde el estudio: el mismo saldo de créditos, al mismo precio. Cada modalidad que el estudio ofrece, tu código también la ofrece.
URL base y autenticación
La API se sirve desde tu dominio de GenMagic bajo /api/v1. Autentícate con una clave secreta en el encabezado Authorization. Crea claves en la configuración de tu cuenta; una clave se muestra una sola vez, así que guárdala en un lugar seguro.
https://genmagic.co/api/v1
Authorization: Bearer gm_live_...
Mantén las claves en el lado del servidor. Nunca incrustes una clave en un paquete de navegador o en una aplicación móvil: cualquiera que la lea puede gastar tus créditos.
Tu primera llamada
POST /chat/completions es la llamada principal. Es compatible con OpenAI, por lo que los SDK oficiales de OpenAI funcionan sin cambios: solo configura la URL base y tu clave de GenMagic.
curl https://genmagic.co/api/v1/chat/completions \
-H "Authorization: Bearer $GENMAGIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "anthropic/claude-sonnet-5",
"messages": [{ "role": "user", "content": "Write a haiku about shipping fast." }]
}'
from openai import OpenAI
client = OpenAI(
base_url="https://genmagic.co/api/v1",
api_key="YOUR_GENMAGIC_API_KEY",
)
resp = client.chat.completions.create(
model="anthropic/claude-sonnet-5",
messages=[{"role": "user", "content": "Write a haiku about shipping fast."}],
)
print(resp.choices[0].message.content)
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://genmagic.co/api/v1",
apiKey: process.env.GENMAGIC_API_KEY,
});
const resp = await client.chat.completions.create({
model: "anthropic/claude-sonnet-5",
messages: [{ role: "user", content: "Write a haiku about shipping fast." }],
});
console.log(resp.choices[0].message.content);
Transmisión en streaming
Establece "stream": true para recibir tokens como eventos enviados por el servidor, en el mismo formato de fragmentos que usa OpenAI. El uso se mide según el recuento autoritativo de tokens del proveedor cuando la transmisión finaliza.
curl https://genmagic.co/api/v1/chat/completions \
-H "Authorization: Bearer $GENMAGIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "anthropic/claude-sonnet-5",
"stream": true,
"messages": [{ "role": "user", "content": "Stream a short story." }]
}'
Razonamiento, parámetros y caché
/chat/completions reenvía el cuerpo de tu solicitud al modelo sin cambios, por lo que cada parámetro que el modelo admite funciona tal como se envía: temperature, tools, response_format, seed y el resto. Cada modelo enumera los que respeta en supported_parameters en GET /models.
Los modelos de razonamiento aceptan reasoning_effort, o la forma de objeto reasoning: { effort, enabled, max_tokens }. Los valores de esfuerzo que acepta un modelo están en su capabilities.reasoning_efforts; cuando capabilities.reasoning_mandatory es verdadero, el pensamiento no se puede desactivar y "enabled": false se rechaza con un 400. Los tokens de razonamiento se reportan en usage.completion_tokens_details.reasoning_tokens.
curl https://genmagic.co/api/v1/chat/completions \
-H "Authorization: Bearer $GENMAGIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-oss-120b",
"reasoning_effort": "high",
"messages": [{ "role": "user", "content": "How many weekdays are there in March 2027?" }]
}'
Cada llamada factura el costo de uso del propio proveedor del modelo, por lo que la entrada en caché y los avisos largos cuestan lo que el modelo cobra por ellos: tokens de entrada en caché a pricing.cache_read_usd_per_million (escrituras de caché a cache_write_usd_per_million) donde un modelo los publica, y un aviso que alcanza el min_prompt_tokens de una banda en pricing.tiers a los precios de esa banda.
Generar
Texto tipado y alineado con tu marca
POST /text devuelve un ARTEFACTO de texto específico, dirigido a tu marca como lo hace el estudio: pasa un type y recibe el resultado terminado. Con la personalización de marca activada, un svg y un website salen con tu paleta y tipografía exactas, y writing y code llevan tu voz. Esta es la diferencia con /chat/completions: ese endpoint es la llamada al modelo cruda compatible con OpenAI (se aplica la VOZ de tu marca, pero no tiene noción de un tipo de artefacto), mientras que /text añade el aviso de sistema del tipo y, para svg / website, la paleta visual y la tipografía. Se devuelve un SVG con metadatos de procedencia del contenido incrustados.
type es uno de writing, code, svg o website (omítelo para una generación simple con la voz de tu marca). Cada tipo elige un modelo predeterminado sensato, o establece model tú mismo desde /models. El system opcional añade una dirección adicional sobre tu marca, y attachments permiten que el modelo lea una imagen de referencia, un PDF o un documento.
curl https://genmagic.co/api/v1/text \
-H "Authorization: Bearer $GENMAGIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "svg",
"prompt": "A geometric mountain badge, flat, three shapes"
}'
# -> { "created": ..., "model": "...", "type": "svg", "text": "<svg ...>...</svg>",
# "usage": { "input_tokens": ..., "output_tokens": ... } }
curl (una página de aterrizaje con tu marca)
curl https://genmagic.co/api/v1/text \
-H "Authorization: Bearer $GENMAGIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "website",
"prompt": "A landing page for a small-batch coffee roaster, warm and minimal"
}'
import requests
r = requests.post(
"https://genmagic.co/api/v1/text",
headers={"Authorization": "Bearer YOUR_GENMAGIC_API_KEY"},
json={"type": "svg", "prompt": "A minimalist wifi icon"},
).json()
print(r["text"])
La respuesta es { created, model, type?, text, usage }. El costo y el saldo restante vuelven en los encabezados X-Cost-Cents y X-Credits-Remaining (consulta Errores), igual que en cada llamada medida. Un svg o website generado con personalización de marca activada también devuelve X-Brand-Fit (on_brand, wrong_palette o monochrome): una lectura de los colores del artefacto (los rellenos del vector, o el CSS de la página), para que puedas regenerar uno que haya salido fuera de tu paleta. Es una sugerencia de mejor esfuerzo, presente solo cuando la salida se puede medir contra un color de marca.
Imágenes
POST /images/generations genera imágenes, en la forma de imagen de OpenAI, por lo que client.images.generate(...) funciona sin cambios. Elige cualquier modelo de imagen de /models (u omite model para el predeterminado recomendado). Establece size (por ejemplo, 1024x1024, 1792x1024) y response_format (url o b64_json).
Imagen a imagen (referencias). Pasa un image (una URL https o una URL data:image) para TRANSFORMAR esa imagen en lugar de generarla desde cero: envía un personaje o producto y se conserva, no se reemplaza. El modelo recibe la referencia (una inutilizable se rechaza, nunca se descarta silenciosamente). Añade "type": "logo" para dirigir el resultado como una marca. La referencia llega al modelo de forma idéntica al estudio.
curl https://genmagic.co/api/v1/images/generations \
-H "Authorization: Bearer $GENMAGIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "google/gemini-3.1-flash-image",
"prompt": "A cobalt prism refracting into a spectrum, dark studio, 3D render",
"size": "1024x1024"
}'
curl https://genmagic.co/api/v1/images/generations \
-H "Authorization: Bearer $GENMAGIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "the same character as a marble statue on a plinth",
"image": "https://your-cdn.com/green-frog-knight.png"
}'
from openai import OpenAI
client = OpenAI(base_url="https://genmagic.co/api/v1", api_key="YOUR_GENMAGIC_API_KEY")
img = client.images.generate(
model="google/gemini-3.1-flash-image",
prompt="A cobalt prism refracting into a spectrum, dark studio, 3D render",
size="1024x1024",
)
print(img.data[0].url)
Voz y música
POST /audio/speech convierte texto en audio hablado, en la forma de voz de OpenAI, por lo que client.audio.speech.create(...) funciona sin cambios. POST /audio/music genera una pista de música original a partir de una descripción. Ambos devuelven los bytes de audio crudos (el contenedor nativo del modelo, por ejemplo, audio/mpeg); la URL alojada duradera vuelve en el encabezado de respuesta X-Media-Url.
curl https://genmagic.co/api/v1/audio/speech \
-H "Authorization: Bearer $GENMAGIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": "Welcome to the future of on-brand generation.",
"voice": "alloy"
}' --output speech.mp3
from openai import OpenAI
client = OpenAI(base_url="https://genmagic.co/api/v1", api_key="YOUR_GENMAGIC_API_KEY")
with client.audio.speech.with_streaming_response.create(
model="openai/gpt-audio-mini",
voice="alloy",
input="Welcome to the future of on-brand generation.",
) as response:
response.stream_to_file("speech.mp3")
curl https://genmagic.co/api/v1/audio/music \
-H "Authorization: Bearer $GENMAGIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "warm lo-fi hip hop, mellow keys, soft vinyl crackle, 80 bpm"
}' --output track.wav
Con la personalización de marca activada, la música se ajusta automáticamente al estado de ánimo de tu marca. La voz se expresa textualmente, por lo que nunca se altera.
Generar
Video
El video es asíncrono (un clip tarda de segundos a minutos), por lo que es un flujo de dos pasos basado en sondeos. POST /videos inicia un trabajo y devuelve su id inmediatamente; luego sondea GET /videos/{id} hasta que status sea completed, momento en el que obtienes un url duradero. No se cobra nada hasta que el clip se completa, y un trabajo terminado se factura exactamente una vez sin importar cuántas veces lo sondees.
Los clips se crean a partir de tu aviso, así que elige un modelo cuyo capabilities.text_to_video sea true en GET /models?category=video (u omite model para el predeterminado). Los modelos que editan, mejoran la resolución o animan medios que tú proporcionas se enumeran con false y se rechazan con 400 model_not_supported.
curl https://genmagic.co/api/v1/videos \
-H "Authorization: Bearer $GENMAGIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "a paper boat sailing down a rain gutter, cinematic, slow motion",
"aspect_ratio": "16:9"
}'
# -> { "id": "vid_...", "status": "queued", "status_url": "/api/v1/videos/vid_..." }
curl https://genmagic.co/api/v1/videos/vid_... \
-H "Authorization: Bearer $GENMAGIC_API_KEY"
# -> { "status": "processing" } ... keep polling ...
# -> { "status": "completed", "url": "https://.../clip.mp4", "cost_cents": 25 }
import time, requests
base = "https://genmagic.co/api/v1"
headers = {"Authorization": "Bearer YOUR_GENMAGIC_API_KEY"}
job = requests.post(f"{base}/videos", headers=headers, json={
"prompt": "a paper boat sailing down a rain gutter, cinematic, slow motion",
"aspect_ratio": "16:9",
}).json()
while True:
s = requests.get(f"{base}/videos/{job['id']}", headers=headers).json()
if s["status"] in ("completed", "failed"):
break
time.sleep(3)
print(s.get("url") or s.get("error"))
Con la personalización de marca activada, el clip se dirige a tu marca (paleta y estética) automáticamente, exactamente como una imagen. Los estados son queued, processing, completed y failed.
Listado de modelos
GET /models devuelve todos los modelos disponibles en ese momento, en la forma de lista de OpenAI, con el detalle completo de cada modelo: nombre, descripción, longitud de contexto, modalidades de entrada/salida, capabilities (razonamiento, visión, herramientas, salida estructurada, voces), pricing en la unidad real de cada modelo (un unit de token, imagen, minuto o segundo, con usd_per_unit, y para video el rango por segundo más cada resolución admitida y longitud de clip), y puntuaciones de referencia donde se publican. El catálogo es en vivo: los modelos nuevos aparecen el día que se lanzan, sin necesidad de actualizar el SDK. Esta es una búsqueda pura: no necesita clave de API y gasta cero créditos. Una solicitud que sí envía una clave tiene la clave verificada y contada hacia su límite de velocidad por clave (consulta Errores), así que almacena en caché el catálogo y actualízalo periódicamente en lugar de sondear en un bucle cerrado.
Filtra con ?category= (texto, imagen, audio, video), ?capability= (razonamiento, visión, herramientas, estructurado) y ?search= (id o nombre). Recupera un modelo con GET /models/{id} (el id contiene una barra, por ejemplo, /models/openai/gpt-image-2).
# Every model, full detail
curl https://genmagic.co/api/v1/models \
-H "Authorization: Bearer $GENMAGIC_API_KEY"
# Only image models
curl "https://genmagic.co/api/v1/models?category=image" \
-H "Authorization: Bearer $GENMAGIC_API_KEY"
# One model's details
curl https://genmagic.co/api/v1/models/openai/gpt-image-2 \
-H "Authorization: Bearer $GENMAGIC_API_KEY"
La lista devuelve { "object": "list", "data": [ ... ] }; cada entrada (y la respuesta de recuperación) es un objeto de modelo. Los modelos de texto llevan pricing por token (prompt_usd_per_million, completion_usd_per_million y, donde el modelo los publica, cache_read_usd_per_million, cache_write_usd_per_million, reasoning_usd_per_million y tiers de contexto largo), los parámetros de solicitud que respetan en supported_parameters, y para modelos de razonamiento capabilities.reasoning_efforts y reasoning_mandatory (consulta Razonamiento); los de imagen, audio y video llevan una estimación por generación. Cada modelo también lleva un único est_per_generation_usd comparable.
{
"id": "openai/gpt-image-2",
"object": "model",
"created": 1751068800,
"owned_by": "openai",
"name": "OpenAI: GPT Image 2",
"description": "Image generation and editing model.",
"category": "image",
"input_modalities": ["text", "image"],
"output_modalities": ["image"],
"context_length": 0,
"capabilities": {
"reasoning": false,
"reasoning_by_default": false,
"vision": true,
"tools": false,
"structured_output": false
},
"pricing": {
"currency": "USD",
"unit": "generation",
"image_output_usd_per_token": 0.00003,
"est_per_generation_usd": 0.0387
}
}
Tu agente, a través de la API
POST /agent/turn es la cara API de tu agente GenMagic: envía una conversación y responde en carácter Y devuelve el conjunto de activos a crear entre modalidades, alineados con tu marca. Planifica, tú creas. La planificación no se factura; luego generas cada activo devuelto llamando al endpoint de su modalidad (/chat/completions para texto, /images/generations para imagen, /audio/speech o /audio/music para audio, /videos para video).
curl https://genmagic.co/api/v1/agent/turn \
-H "Authorization: Bearer $GENMAGIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{ "role": "user", "content": "Make a launch tweet and a logo for a cold brew brand called Northwind." }
]
}'
La respuesta es { reply, assets: [{ modality, title, prompt, aspect_ratio?, voice? }] }. Alimenta el prompt de cada activo al endpoint correspondiente para generarlo.
Agentes
Úsalo desde un agente (MCP)
GenMagic también es un servidor de Protocolo de Contexto de Modelo, por lo que un agente de IA puede generar a través de él directamente. Apunta cualquier cliente MCP (Claude Desktop, Cursor o el tuyo propio) al endpoint de abajo con tu clave, y el agente obtiene siete herramientas: generate_text, generate_image, generate_speech, generate_music, para video create_video + get_video (crear devuelve un id de trabajo, get_video lo sondea hasta que el clip esté listo), y list_models. Una llamada de herramienta se factura exactamente como cualquier otra llamada, y sale alineada con tu marca cuando la personalización está activada.
Cualquier modelo, por id. Cada herramienta de generación acepta un model opcional: los mismos ids que la API REST y la biblioteca de modelos. El agente los encuentra con list_models (filtra por category o search), que no necesita clave y devuelve el precio de cada modelo, las voces de los modelos de voz y las resoluciones, longitudes de clip y soporte de sonido de los modelos de video, además del predeterminado que cada herramienta ejecuta cuando no se nombra ningún modelo. create_video también acepta duration, resolution y generate_audio. Un id que una herramienta no ejecuta se rechaza con un puntero a list_models, nunca se cambia por otro modelo, y cada resultado nombra el modelo que se ejecutó.
https://genmagic.co/api/mcp
La mayoría de los clientes aceptan una pequeña configuración con la URL y un encabezado Authorization:
{
"mcpServers": {
"genmagic": {
"url": "https://genmagic.co/api/mcp",
"headers": { "Authorization": "Bearer $GENMAGIC_API_KEY" }
}
}
}
En el fondo es JSON-RPC simple, por lo que puedes llamarlo con cualquier cosa:
curl https://genmagic.co/api/mcp \
-H "Authorization: Bearer $GENMAGIC_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'
curl (lista modelos de video con sus precios y opciones; no se necesita clave)
curl https://genmagic.co/api/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"jsonrpc": "2.0", "id": 5, "method": "tools/call",
"params": { "name": "list_models", "arguments": { "category": "video", "limit": 10 } }
}'
curl (genera una imagen con un modelo elegido)
curl https://genmagic.co/api/mcp \
-H "Authorization: Bearer $GENMAGIC_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"jsonrpc": "2.0", "id": 2, "method": "tools/call",
"params": {
"name": "generate_image",
"arguments": {
"prompt": "a cobalt prism on black, 3D render",
"size": "1024x1024",
"model": "google/gemini-nano-banana-2.1"
}
}
}'
curl https://genmagic.co/api/mcp \
-H "Authorization: Bearer $GENMAGIC_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"jsonrpc": "2.0", "id": 3, "method": "tools/call",
"params": {
"name": "generate_music",
"arguments": { "prompt": "warm lo-fi hip hop, mellow keys, 80 bpm" }
}
}'
curl (inicia un video, luego sondea get_video)
curl https://genmagic.co/api/mcp \
-H "Authorization: Bearer $GENMAGIC_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"jsonrpc": "2.0", "id": 4, "method": "tools/call",
"params": {
"name": "create_video",
"arguments": {
"prompt": "a paper boat sailing down a rain gutter, cinematic",
"aspect_ratio": "16:9",
"model": "google/veo-3.1-fast",
"duration": 8,
"resolution": "720p"
}
}
}'
# then poll: params.name "get_video", arguments { "id": "<the returned job id>" }
Cada resultado de herramienta se autodescribe en su gasto. Un cuerpo JSON-RPC no tiene encabezados por llamada, por lo que cada resultado de herramienta lleva su medición en el campo MCP estándar _meta, bajo la clave genmagic.ai/usage: cost_cents (lo que costó la llamada), credits_remaining (tu saldo después) y un objeto rate (limit, remaining, reset). Es el espejo MCP de los encabezados de respuesta REST de abajo, por lo que un agente se regula y rastrea el gasto desde el resultado que ya tiene. Un envío de create_video y un sondeo de get_video que aún se está renderizando no cobran nada, por lo que reportan solo margen de velocidad; el costo del clip recae en el sondeo que lo completa. Los campos se omiten, nunca se falsifican, cuando un valor es desconocido.
Las llamadas visuales también informan sobre la adecuación a la marca. Cuando generas un logo, un svg con marca, o un website con marca y tu marca tiene un conjunto de colores definido, el _meta del resultado incluye un objeto brand_fit: label es on_brand, wrong_palette (la salida salió en un color fuera de la marca, vale la pena regenerarla), o monochrome (intencionalmente sin color, no es un problema), junto con una fracción presence y un indicador foreign_dominant_hue. Un agente puede leerlo y regenerar un artefacto que se desvió de la marca, sin necesidad de intervención humana. Solo está presente cuando la salida realmente se puede medir, por lo que simplemente está ausente en llamadas de prosa/código o en un formato que no decodificamos.
Integraciones
Úsalo con el Vercel AI SDK
GenMagic funciona con el Vercel AI SDK a través de su proveedor compatible con OpenAI, por lo que no hay ningún paquete de GenMagic que instalar. Crea el proveedor con tu URL base y clave de API, luego usa generateText, streamText, llamadas a herramientas y generateImage con cualquier ID de modelo del catálogo.
npm install ai @ai-sdk/openai-compatible
import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
import { generateText, streamText } from "ai";
const genmagic = createOpenAICompatible({
name: "genmagic",
apiKey: process.env.GENMAGIC_API_KEY,
baseURL: "https://genmagic.co/api/v1",
includeUsage: true, // token usage on streamed responses too
});
const { text } = await generateText({
model: genmagic("anthropic/claude-sonnet-5"),
prompt: "Write a haiku about shipping fast.",
});
const result = streamText({
model: genmagic("google/gemini-3.5-flash"),
prompt: "Count from 1 to 5, separated by spaces.",
});
for await (const part of result.textStream) process.stdout.write(part);
Las imágenes pasan por generateImage. El AI SDK lee las imágenes como base64, así que solicita b64_json con una opción de proveedor claveada por el nombre del proveedor que elegiste:
import { generateImage } from "ai";
const { image } = await generateImage({
model: genmagic.imageModel("recraft/recraft-v4.1-flash"),
prompt: "A watercolor fox reading a book under a tree",
providerOptions: { genmagic: { response_format: "b64_json" } },
});
// image.uint8Array, image.base64, image.mediaType
Los IDs de modelo provienen de GET /models, que no requiere clave (filtra con ?category=text o ?category=image). Las llamadas a herramientas funcionan con modelos cuyo capabilities.tools sea verdadero. Voz, música y video usan los endpoints REST anteriores. Probado el 2026-10-03 con ai 7.0.127 y @ai-sdk/openai-compatible 3.0.62, y con ai 6.0.300 y @ai-sdk/openai-compatible 2.0.81.
Integraciones
Úsalo en Dify
GenMagic es un plugin en el Dify Marketplace, por lo que los flujos de trabajo y agentes que construyas en Dify también pueden generar con él. Instala el plugin, pega tu clave de API en su configuración, y obtienes seis herramientas: Generate image, Generate video y Check video, Generate speech, Generate music y Generate text. Cada herramienta lista los modelos en vivo con sus precios (o permite que GenMagic elija uno) y devuelve el archivo generado al flujo de trabajo.
El plugin es gratuito; las generaciones consumen el mismo saldo de créditos que cualquier otra llamada. Su código fuente está en GitHub.
Úsalo en n8n
GenMagic es un nodo comunitario para n8n, publicado en npm como n8n-nodes-genmagic. En un n8n autoalojado, un propietario o administrador abre Configuración › Nodos comunitarios, selecciona Instalar e ingresa el nombre del paquete:
n8n-nodes-genmagic
Luego agrega una credencial GenMagic API con tu clave (n8n la verifica leyendo tu saldo, lo cual no cuesta nada). Un nodo cubre Image (generar, o editar una imagen de referencia, hasta 4 por ejecución), Video (generar, esperando el renderizado o devolviendo el ID del trabajo, y obtener), Audio (voz y música), Text, Model (el catálogo en vivo) y Account (tu saldo). Cada menú desplegable de modelos lista el catálogo en vivo con precios, o permite que GenMagic elija. Los archivos generados vuelven como datos binarios, listos para los nodos que los suben, publican o envían por correo, con el cost_usd de la generación y tu balance_usd restante. El Agente de IA de n8n también puede usar el nodo como herramienta.
El nodo es gratuito y tiene licencia MIT; las generaciones consumen el mismo saldo de créditos que cualquier otra llamada. Su código fuente está en GitHub.
Integraciones
Úsalo en Zapier
GenMagic tiene una integración con Zapier en beta. Hasta que Zapier la liste en su directorio de aplicaciones, la agregas a tu cuenta de Zapier con este enlace de invitación, luego la conectas con tu clave de API (Zapier verifica la clave leyendo tu saldo, lo cual no cuesta nada). Cualquier Zap puede usar entonces cinco pasos: Generate Image (una imagen o un logotipo, opcionalmente desde una imagen de referencia), Generate Text (escritura, código, un gráfico SVG o una página web), Generate Speech, Start Video y Find Video. Cada campo de modelo lista el catálogo en vivo con precios, o déjalo vacío para usar el predeterminado.
Zapier le da a cada paso 30 segundos, por lo que el video requiere dos pasos: Iniciar Video devuelve un ID de trabajo de inmediato, y Buscar Video, en un paso posterior o Zap, devuelve el clip una vez que esté terminado. Los pasos de imagen y voz devuelven una URL de archivo alojado y los pasos de texto devuelven el texto, cada uno con el cost_usd de la llamada; Buscar Video agrega el costo del clip cuando se completa. La integración es gratuita; las generaciones consumen el mismo saldo de créditos que cualquier otra llamada.
Integraciones
Pruébalo en Postman
Cada endpoint está listo para enviarse en el espacio de trabajo de Postman público de GenMagic, importado desde la especificación OpenAPI. Haz un fork de la colección GenMagic API en tu propio espacio de trabajo, configura su token Bearer con tu clave y envía cualquier solicitud. GET /models responde sin clave, por lo que puedes explorar el catálogo en vivo y sus precios primero.
Facturación
Créditos: una llamada es una llamada
No hay un medidor de API separado. Cada generación, desde el estudio o desde tu código, se factura de la misma manera: el costo real del proveedor se deduce de tu único saldo de créditos. Recarga o suscríbete desde tu cuenta, y el mismo saldo alimenta ambos.
Si una llamada dejaría tu saldo en negativo, se rechaza con HTTP 402 y un error insufficient_quota, exactamente como espera un SDK de OpenAI, por lo que tu reintento y manejo de errores funcionan sin cambios.
Errores
Cada error usa el formato de OpenAI, por lo que un SDK de OpenAI lo analiza sin cambios: { "error": { "message", "type", "code", "param" } }. Los códigos de estado:
400 invalid_request_error bad or missing parameter (e.g. no prompt, unknown model id)
401 authentication_error missing, invalid, or revoked API key
402 insufficient_quota balance would go negative; top up to continue
404 invalid_request_error model_not_found on GET /models/{id}
429 rate_limit_error too many requests for this key; back off and retry
5xx server_error transient upstream/provider issue; retry with backoff
Las llamadas de consulta (/models, /usage) no gastan créditos, por lo que nunca devuelven un 402: solo devuelven 401 (clave incorrecta), 429 (límite de velocidad alcanzado) o, para un modelo faltante, 404.
Límites de velocidad. Cada clave permite hasta 300 solicitudes por minuto (ventana fija). Excederlo devuelve 429 con un encabezado Retry-After (segundos hasta que se reinicie la ventana) junto con X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Respeta Retry-After y reintenta. Esto regula una clave filtrada; tu saldo de créditos es el límite real de gasto. ¿Necesitas un límite más alto para una carga de trabajo pesada? Pídenos que lo aumentemos en tu clave.
Encabezados de respuesta. Cada llamada exitosa informa su propia medición, por lo que un agente puede autorregularse y rastrear el gasto sin una segunda solicitud. El trío de límite de velocidad (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) está en cada respuesta autenticada, incluidas las consultas, y X-Credits-Remaining informa tu saldo después de cualquier llamada no transmitida que haya gastado créditos. Las generaciones de imagen, audio, video y /text tipadas también llevan X-Cost-Cents (lo que costó esa llamada); un video informa su costo en la consulta que lo completa, y /text además devuelve sus recuentos de tokens en el objeto usage de la respuesta. Los completados de chat, en cambio, se precian al estilo OpenAI sin X-Cost-Cents: los recuentos de tokens están en el objeto usage de la respuesta (en el marco SSE final al transmitir, por lo que una llamada transmitida solo lleva los encabezados de límite). Una generación logo (y un svg o website con marca de /text) también lleva X-Brand-Fit (on_brand, wrong_palette o monochrome), la forma compacta del objeto brand_fit de MCP anterior, presente solo cuando la salida se pudo medir. Los valores son sugerencias de mejor esfuerzo; GET /usage sigue siendo el saldo autoritativo.
Consulta tu saldo
GET /usage devuelve el saldo de créditos en vivo de tu clave y el gasto total de por vida, para que un programa o agente pueda verificar su presupuesto restante antes de una ejecución grande y nunca se sorprenda con un 402. Lee el mismo saldo del que dependen todas las demás llamadas.
curl https://genmagic.co/api/v1/usage \
-H "Authorization: Bearer $GENMAGIC_API_KEY"
# -> { "object": "usage", "currency": "usd",
# "balance_cents": 3812.5, "balance_usd": 38.125,
# "spent_cents": 2187.5, "spent_usd": 21.875, "generation_count": 148 }
Con marca
Personalización
Abre Personaliza tus salidas en la aplicación y conecta tu sitio web o LinkedIn una vez. GenMagic aprende tu voz, audiencia y colores. Mientras la personalización esté activada, cada generación de API se moldea automáticamente con ese perfil de marca: tus respuestas salen con la marca sin cambiar una línea de tu código.
Es un solo interruptor. Apágalo allí y las llamadas de API se ejecutan exactamente como están escritas, sin contexto de marca agregado. Tus indicaciones y mensajes de sistema siempre se conservan; el contexto de marca se antepone como un mensaje de sistema inicial solo mientras el interruptor esté activado.