motionvid

¿Qué hace motionvid?

Motionvid crea videos completos a partir de un brief: guion, escenas animadas, narración, música y efectos de sonido, renderizados a MP4, desde 5 segundos hasta 20 minutos. Lo controlas a través de su servidor MCP. Actúa como un diseñador de motion graphics tomando un brief, no como un formulario: obtén los pocos datos importantes, toma decisiones sensatas para el resto, muestra el resultado y luego itera.

DETENTE: si las herramientas MCP de Motionvid (create_video, get_video_status, …) están disponibles, úsalas. No implementes llamadas REST manualmente ni escribas código de renderizado (Remotion, FFmpeg) tú mismo. Nunca le pidas al usuario que pegue una clave API en el chat.

1. Detecta lo que está conectado

1. Llama a whoami. Si responde, estás conectado: ve al paso 2.
2. Si faltan las herramientas, agrega el servidor y deja que el usuario inicie sesión:
   • Endpoint MCP: https://motionvid.ai/mcp (HTTP Streamable, OAuth 2.1 con descubrimiento)
   • Claude Code: claude mcp add --transport http motionvid https://motionvid.ai/mcp, luego claude mcp login motionvid
   • Codex: codex mcp add motionvid --url https://motionvid.ai/mcp, luego codex mcp login motionvid
   • Cursor, VS Code, Claude, ChatGPT y otros: https://motionvid.ai/agents Pregunta una vez ("¿Debo agregar Motionvid a tu configuración?") y hazlo si responde que sí.
3. Sin interfaz gráfica (CI, servidores): el usuario crea una clave mvk_ en https://motionvid.ai/account/api-keys y la expone como variable de entorno; envíala como Authorization: Bearer <key>.
4. Una respuesta "prohibido" o de actualización significa que la cuenta no tiene un plan de pago: informa al usuario que el conector está incluido en todos los planes de pago (https://motionvid.ai/pricing) y detente.

2. Brief

Obtén, o decide tú mismo cuando al usuario no le importe:

• De qué trata y para quién es. Pasa URLs, PDFs, imágenes y audio como entradas: el planificador lee páginas, colores de marca y documentos por sí mismo.
• Duración (duration, segundos) y formato (aspect_ratio: 16:9, 9:16, 1:1, 4:5).
• Sonido: narration (y narration_language, narration_voice), music, sfx. Si el usuario escribió la narración, póngala en el prompt palabra por palabra y dígalo.
• Aspecto: animation_style (list_animation_styles o suggest_animation_styles para que el usuario elija) y brand_kit_id (list_brand_kits).
• Modo: gráficos animados por defecto. Para una historia, película de marca o anuncio con personas o un personaje recurrente, usa Director IA: ai_video: "full" (guion, un elenco consistente, escenas cinematográficas, voz y música). Agrega storyboard: true cuando el usuario quiera aprobar primero el elenco y el storyboard. ai_video: "auto" mezcla imágenes reales solo donde la historia lo necesita.

Opcional: enhance_prompt convierte una idea aproximada en un brief completo.

3. Muestra el costo antes de gastar

Llama a get_credit_balance (y list_models para conocer los costos por modelo). Un video de gráficos animados de 30 segundos en el modelo rápido suele tomar alrededor de 33 créditos, uno de un minuto alrededor de 45. Las películas del Director IA cuestan más porque cada escena es metraje. Para cualquier cosa larga (más de 2 minutos) o Director IA, informa al usuario el costo aproximado desde list_models y espera una confirmación.

4. Crea y sigue

1. create_video con el brief. Devuelve un ID de trabajo de inmediato; la compilación se ejecuta en segundo plano.
2. Consulta get_video_status cada 15 a 30 segundos. Estados: queued → processing → rendering → completed, o failed / canceled. Una compilación generalmente toma unos minutos; la lentitud es normal. Nunca canceles ni reinicies porque parezca inactivo.
3. awaiting_approval solo ocurre cuando solicitaste storyboard: true: llama a preview_video, muéstrale al usuario el storyboard y llama a approve_video con su decisión (o changes). Nunca apruebes en su nombre.

5. Entrega e itera

1. preview_video muestra un fotograma por escena: muéstralos al usuario.
2. Cambios: edit_video con el cambio en palabras claras ("haz la escena 3 más impactante", "usa nuestro logo al final"). Solo se rehace esa parte.
3. render_video para el MP4 (720p por defecto; 1080p y 4K en planes que los incluyan). Luego get_video_status da download_url: caduca después de unos 15 minutos, así que descarga el archivo donde el usuario pidió (por ejemplo, ./media/) u obtén un enlace nuevo en lugar de almacenar uno.
4. El usuario también puede abrir y editar el video en la aplicación Motionvid (app_url en el estado).

Reglas

• Un video por solicitud. No inicies un segundo trabajo mientras el primero aún se esté ejecutando a menos que te lo pidan.
• Informa honestamente sobre el estado: si un trabajo falló, dilo y cita su error; no pretendas que fue exitoso.
• Mantén las palabras exactas del usuario para guiones, nombres, precios y afirmaciones.
• cancel_video solo cuando el usuario lo pida.

Cuando algo falla

Síntoma	Qué hacer
Faltan herramientas / 401	Vuelve a ejecutar el paso de inicio de sesión (claude mcp login motionvid, codex mcp login motionvid, o reconecta el conector).
Mensaje de prohibido / actualización	La cuenta necesita un plan de pago: https://motionvid.ai/pricing
No hay suficientes créditos	Informa al usuario el saldo desde get_credit_balance; sugiere un video más corto o una recarga.
failed con "timed out"	Las escenas que construyó se guardaron: edit_video con "termina las escenas restantes".
429 / límite de tasa	Espera un minuto, luego reintenta una vez.

Referencias

• Resumen para agentes (markdown): https://motionvid.ai/agents.md
• Configuración MCP por cliente: https://motionvid.ai/mcp
• API REST: https://motionvid.ai/api-docs
• Índice: https://motionvid.ai/llms.txt