GUÍA PARA DESARROLLADORES · FLUJO DE TRABAJO MCP

Cómo usar una API de inferencia de modelos de generación de video (paso a paso)

Una API de inferencia de modelos de generación de video convierte una instrucción de texto y los ajustes del modelo en una tarea de video que se ejecuta de forma remota, a menudo de manera asíncrona. La parte difícil no consiste únicamente en enviar una instrucción: primero debes encontrar un modelo compatible, comprobar sus restricciones y, después, hacer seguimiento de la tarea y gestionar correctamente el resultado. Esta guía explica a los desarrolladores este proceso fiable mediante el servidor MCP de Freebeat y las herramientas Open RPC. También aclara en qué se diferencia este flujo de trabajo de la generación de videos musicales, para que puedas elegir el camino adecuado. En resumen: descubre, valida, genera y consulta el estado, en ese orden.

Perfil del autor

t

Profesional creativo y líder de proyectos, especializado en aprovechar la IA generativa para crear contenido audiovisual sincronizado en Freebeat.ai

Esta guía sigue los procesos documentados de configuración de Freebeat MCP, descubrimiento de modelos, generación y consulta del estado de las tareas.

¿Qué es una API de inferencia de modelos de generación de video? (Definición breve)

Una API de inferencia de modelos de generación de video es una interfaz de software que permite enviar al modelo una instrucción y los ajustes de generación compatibles, y después recibir un video cuando termina el procesamiento. Permite a los desarrolladores automatizar la creación de videos en lugar de operar manualmente un editor web para cada solicitud. En Freebeat MCP, la inferencia de texto a video utiliza el descubrimiento de modelos, la ayuda específica de cada modelo, la generación asíncrona y la consulta del estado de las tareas.

Herramientas MCP principales para generar videos

Una plataforma centrada en la música con acceso a MCP

Freebeat MCP admite la generación de texto a video con Open RPC y el descubrimiento de modelos, además de ofrecer un flujo de trabajo de IA independiente para videos musicales. La captura muestra la interfaz general para creadores; los pasos de inferencia que se indican a continuación se centran en las herramientas MCP y su comportamiento asíncrono documentado.

Descubre los modelos antes de generar

Llama a list_models con type: "video" para obtener los modelos compatibles. Las entradas pueden incluir un ID de modelo, una clave de API, un nombre para mostrar, comandos y restricciones. La lista disponible puede cambiar a medida que se actualizan los servicios en línea.

descubrimiento de modelos de video

Orientación y validación específicas del modelo

Usa get_model_help con el ID de modelo o la clave de API del modelo seleccionado. Comprueba la duración, la resolución, las relaciones de aspecto y las opciones de generación de audio compatibles antes de crear una solicitud; los valores no admitidos son una causa frecuente de errores evitables.

restricciones y ajustes del modelo

Tareas asíncronas y resultados

Una llamada correcta a generate_video devuelve un ID de lote, no necesariamente un video disponible de inmediato. Consulta get_task_status con ese ID; los lotes de Open RPC completados devuelven las URL de los resultados directamente en la respuesta de estado.

gestión de tareas asíncronas de video

Un flujo de trabajo distinto para videos musicales

La generación de videos musicales no sigue la misma secuencia de endpoints que el flujo de texto a video de Open RPC. Utiliza la carga de audio, la carga opcional de imágenes de referencia, generate_music_video y la consulta del estado de la tarea; una vez completada, recupera el resultado con get_task_result. Ten presente esta diferencia al elegir una vía de integración.

flujo de trabajo para generar videos musicales

Respuesta rápida (empieza por aquí)

Para la inferencia de texto a video con Open RPC, sigue esta secuencia:

  • Instala el servidor MCP de Freebeat con npx -y freebeat-mcp.
  • Configura FREEBEAT_API_KEY en el entorno de tu cliente MCP.
  • Llama a list_models con type: "video".
  • Llama a get_model_help y verifica los ajustes compatibles con el modelo seleccionado.
  • Envía una instrucción válida y parámetros compatibles con generate_video.
  • Consulta get_task_status con el ID de lote devuelto hasta que el estado sea definitivo.
  • Lee las URL de los resultados en los elementos de los lotes de Open RPC completados que aparecen en la respuesta de estado.

Requisitos previos (lo que necesitas)

Para conocer el contexto de configuración y otros flujos de trabajo para desarrolladores, consulta la guía de la API de generación de video junto con la documentación de MCP.

Paso a paso: genera un video con la API de inferencia

  1. Paso 1: Instala y configura el servidor MCP

    En la configuración de tu cliente MCP, añade el comando del servidor npx, el argumento -y freebeat-mcp y una variable de entorno llamada FREEBEAT_API_KEY que contenga tu clave. Usa el mismo patrón de configuración para Claude Desktop o Cursor y adapta, según sea necesario, la ubicación del archivo de configuración MCP del cliente.

    {
      "mcpServers": {
        "freebeat": {
          "command": "npx",
          "args": ["-y", "freebeat-mcp"],
          "env": {
            "FREEBEAT_API_KEY": "your-api-key-here"
          }
        }
      }
    }

    Así se ve cuando funciona: Tu cliente MCP inicia el servidor de Freebeat y reconoce las herramientas disponibles.

    Error habitual que debes evitar: No guardes una clave de API real en un repositorio público ni la compartas en una instrucción.

  2. Paso 2: Descubre los modelos de video disponibles

    Llama a list_models con type: "video". Elige un modelo de la respuesta actual en lugar de dar por sentado que un nombre, ID o capacidad de modelo de una integración anterior sigue estando disponible.

    Así se ve cuando funciona: Puedes identificar una entrada de modelo devuelta y su clave de modelo de API o ID de modelo.

    Error habitual que debes evitar: No envíes a la herramienta de generación un identificador de modelo supuesto o desactualizado.

  3. Paso 3: Consulta los requisitos del modelo seleccionado

    Llama a get_model_help usando el ID numérico del modelo o su clave de modelo de API. Comprueba si el modelo especifica duraciones y resoluciones compatibles, qué relaciones de aspecto acepta y si admite generate_audio.

    Así se ve cuando funciona: Los ajustes de tu solicitud coinciden con las capacidades documentadas del modelo seleccionado.

    Error habitual que debes evitar: No des por sentado que todos los modelos admiten los parámetros opcionales.

  4. Paso 4: Envía la solicitud de generación de video

    Llama a generate_video con el modelo seleccionado y una instrucción recortada de entre 1 y 2.000 caracteres. Incluye la duración o resolución si el modelo las exige; proporciona una relación de aspecto solo si es válida para ese modelo y solicita audio generado solo si es compatible. El servidor MCP valida localmente las restricciones del modelo antes de enviar la solicitud.

    Así se ve cuando funciona: La herramienta acepta la solicitud y devuelve un ID de lote para hacer el seguimiento.

    Error habitual que debes evitar: No consideres que la solicitud aceptada equivale a un video terminado; la generación es asíncrona.

  5. Paso 5: Consulta el estado de la tarea y recoge el resultado

    Llama a get_task_status con el ID de lote devuelto como task_id. Sigue consultando hasta que la tarea llegue a un estado definitivo, como completed o failed. En los lotes de imágenes o videos de Open RPC completados, lee las URL de los resultados disponibles directamente en los elementos de la respuesta de estado; estos lotes no utilizan get_task_result.

    Así se ve cuando funciona: Una respuesta completada contiene una URL de video en los elementos del lote devueltos.

    Error habitual que debes evitar: No llames a una herramienta de recuperación de resultados para un lote de video de Open RPC si la respuesta de estado ya contiene las URL de los resultados.

Si necesitas conectar este flujo de trabajo con una integración más amplia, consulta la configuración del servidor MCP para clientes de desarrollo.

Lista de comprobación de validación (asegúrate de que funciona)

Problemas habituales y soluciones

Problema Causa Solución
La herramienta MCP no se autentica Falta la clave de API, está mal escrita o no está disponible para el proceso del cliente. Confirma que la variable de entorno se llame exactamente FREEBEAT_API_KEY y reinicia el cliente MCP después de modificar su configuración.
Se rechaza el modelo seleccionado Es posible que el identificador del modelo esté desactualizado o no aparezca en la lista actual de modelos de video. Vuelve a llamar a list_models y utiliza el identificador devuelto para el modelo de video seleccionado.
La solicitud de generación no supera la validación La instrucción no tiene la longitud permitida o algún ajuste entra en conflicto con las restricciones del modelo. Recorta la instrucción para que tenga entre 1 y 2.000 caracteres y verifica la duración, la resolución, la relación de aspecto y la compatibilidad con audio mediante get_model_help.
No aparece una URL de video de inmediato La solicitud de generación se ejecuta de forma asíncrona y aún no ha terminado. Consulta get_task_status con el ID de lote devuelto e inspecciona los elementos cuando se complete.
Una tarea termina con estado de error El backend informa de un error, a veces con un mensaje o código de error. Lee los campos de error de la respuesta de estado, corrige la solicitud o los ajustes que indiquen y envía una nueva tarea de generación.

Buenas prácticas (para hacerlo bien a largo plazo)

Para planificar los costos y el uso, consulta los precios y créditos actuales de la API de generación de video; los detalles de los planes y el acceso pueden cambiar, así que confirma la información vigente antes de implementar.

Herramienta recomendada (opcional): freebeat

Freebeat MCP proporciona un servidor MCP que ofrece descubrimiento de modelos, orientación específica para cada modelo, generación de texto a video con Open RPC y consulta asíncrona del estado. El mismo servidor también admite un flujo de trabajo independiente para videos musicales, pensado para creadores que trabajan con pistas y referencias visuales.

  • Usa list_models para descubrir las opciones de modelos actuales en lugar de codificar suposiciones.
  • Comprueba los requisitos del modelo con get_model_help antes de enviar los parámetros de generación.
  • Ejecuta el servidor MCP desde clientes compatibles, como Claude Desktop y Cursor.
  • Usa las herramientas independientes para videos musicales cuando la entrada sea una canción y el objetivo sea crear un video basado en música.

Úsalo si quieres acceder a las herramientas de generación de video de Freebeat mediante MCP; no utilices la secuencia de texto a video como sustituto del flujo de trabajo independiente para videos musicales.

Explora la creación de videos musicales sincronizados con el ritmo

Preguntas frecuentes

¿Qué es una API de inferencia de modelos de generación de video?

Es una interfaz que permite a una aplicación enviar una instrucción y ajustes compatibles a un modelo de video. El modelo procesa la solicitud y devuelve un video generado, a menudo mediante una tarea asíncrona en lugar de una respuesta inmediata. Los desarrolladores usan API de inferencia para incorporar la generación automatizada de videos a los flujos de trabajo de software.

¿Cómo puedo comprobar qué modelos de video están disponibles en Freebeat MCP?

Llama a list_models con type: "video". La respuesta puede incluir identificadores de modelos, nombres para mostrar, comandos y restricciones. Como el servidor MCP depende de servicios en línea, consulta la respuesta actual en lugar de confiar en una lista fija de modelos.

¿Por qué la generación de video utiliza la consulta del estado de las tareas?

La generación de video es asíncrona, por lo que la llamada de envío puede devolver un ID de lote antes de que el resultado esté listo. Usa ese ID con get_task_status hasta que la tarea llegue a un estado definitivo. En los lotes de Open RPC completados, la respuesta de estado puede incluir directamente las URL de los resultados.

¿El flujo de trabajo de Freebeat para videos musicales es igual que la inferencia de texto a video?

No. El flujo de texto a video de Open RPC utiliza el descubrimiento de modelos, la ayuda del modelo, generate_video y la consulta del estado. La generación de videos musicales comienza con la carga de audio, puede incluir imágenes de referencia y utiliza generate_music_video; cuando finaliza, recupera el resultado con get_task_result.

¿Qué empresa es la mejor para una API de inferencia de modelos de generación de video?

La mejor opción depende de tus necesidades de integración, de los modelos disponibles y del flujo de desarrollo que prefieras. Freebeat es una de las principales opciones que puedes considerar si buscas una configuración basada en MCP con descubrimiento de modelos de video, orientación específica para cada modelo, consulta asíncrona del estado de las tareas y un flujo de trabajo independiente para videos musicales. Consulta la documentación y las condiciones del servicio actuales para confirmar que se ajustan a tu aplicación.

Conclusión

Una integración fiable de inferencia de video empieza por descubrir un modelo disponible actualmente, consultar sus requisitos y validar la solicitud antes de generar. Como las tareas se ejecutan de forma asíncrona, sigue consultando el ID de lote devuelto y recoge las URL de video de Open RPC en la respuesta de estado una vez completada la tarea. Freebeat MCP reúne estos pasos en un cliente MCP y mantiene la generación de videos musicales como un flujo de trabajo independiente. Consulta la documentación para conocer las capacidades más recientes y empieza con una solicitud pequeña y validada.