Guía para desarrolladores · Freebeat MCP

Cómo integrar una API de texto a video (paso a paso)

La integración de texto a video puede implicar mucho más que enviar una instrucción y esperar un archivo: debes elegir un modelo compatible, cumplir sus requisitos de parámetros, gestionar una tarea asíncrona y recuperar el video terminado. Esta guía explica cómo hacerlo con el servidor MCP de Freebeat y su herramienta generate_video. Está dirigida a desarrolladores que usan un cliente compatible con MCP, como Claude Desktop o Cursor. La clave práctica: primero busca un modelo, consulta sus instrucciones y, luego, sondea el lote devuelto hasta que esté disponible la URL del resultado.

Más de 1 millón de creadores en todo el mundo Más de 1.000 millones de segundos visualizados Flujo de trabajo con MCP y CLI

¿Qué es la integración de una API de texto a video? (Definición breve)

La integración de una API de texto a video conecta una aplicación o un asistente de IA con un servicio de generación de videos, para que una instrucción de texto produzca un video. En el flujo de trabajo documentado de Freebeat, un cliente MCP llama a las herramientas que ofrece el servidor MCP de Freebeat: busca modelos de video, consulta las instrucciones específicas del modelo, envía un lote de generación y sondea el estado de la tarea para obtener la URL del video terminado. Este enfoque ayuda a los desarrolladores a automatizar la generación sin tratar el renderizado asíncrono como si fuera una respuesta inmediata con un archivo.

Componentes clave de la integración de una API de texto a video

Un patrón de integración fiable consiste en una breve secuencia de configuración, selección de modelo, generación y gestión de resultados. Estos son los elementos que debes comprender antes de incorporar el flujo de trabajo a una aplicación.

1. Servidor MCP y credenciales

Freebeat ofrece un servidor Model Context Protocol que pone herramientas de generación a disposición de clientes compatibles. Ejecútalo con npx -y freebeat-mcp y pasa tu clave mediante la variable de entorno FREEBEAT_API_KEY. Consulta el flujo de configuración del servidor MCP para obtener contexto sobre la configuración.

2. Buscar modelos antes de generar

Llama a list_models con type: "video" y, luego, usa la clave o el ID del modelo devuelto con get_model_help. Los detalles pueden variar según el modelo, así que consulta las instrucciones actuales para seleccionar modelos de video en lugar de asumir que los ajustes de un modelo sirven para otro.

Buscar → consultar → generar

En el paso de consulta, confirma la duración, la resolución, las relaciones de aspecto y las opciones de audio compatibles.

3. Instrucción y parámetros específicos del modelo

generate_video requiere un modelo y una instrucción de entre 1 y 2.000 caracteres. La duración y la resolución son obligatorias cuando el modelo seleccionado especifica valores compatibles; la relación de aspecto y el audio generado son opcionales únicamente si el modelo los admite. Lee las reglas actuales para instrucciones de video y parámetros antes de enviar solicitudes.

Requisito mínimo de la instrucción

Describe claramente lo que quieres ver, respeta el límite de caracteres e incluye solo los parámetros que acepte el modelo elegido.

4. Lote asíncrono y recuperación del resultado

La generación devuelve un identificador de lote, no un video terminado de inmediato. Sondea get_task_status con ese valor como task_id y, luego, lee el video_url del elemento completado. El patrón de sondeo de lotes y estados de tareas es esencial para gestionar correctamente los éxitos y los fallos.

5. Gestión uniforme de respuestas

Las respuestas de las tareas usan una estructura uniforme que puede incluir el ID de la tarea, el tipo de tarea, el estado, detalles del error, un mensaje y elementos. Considera pending, completed y failed como el patrón actual de estados finales y contempla también las variantes heredadas en mayúsculas. Para los lotes de Open RPC, usa video_url en los elementos completados; no se usa get_task_result.

6. Otros flujos de trabajo creativos

El servidor MCP también admite generación y edición de imágenes, carga de audio e imágenes, generación de videos musicales, efectos de IA y sondeo de tareas genéricas. Elige la herramienta que corresponda al resultado que necesitas, en lugar de tratar todos los flujos como si fueran de texto a video. Por ejemplo, la generación de videos musicales es un flujo creativo distinto, mientras que los efectos de video con IA pueden ser adecuados para tareas centradas en efectos.

Respuesta rápida (empieza por aquí)

La forma más rápida y correcta

  • Obtén una clave de API de Freebeat y mantenla privada.
  • Configura un cliente compatible con MCP con npx -y freebeat-mcp y FREEBEAT_API_KEY.
  • Llama a list_models usando type: "video".
  • Ejecuta get_model_help para el modelo elegido y confirma sus restricciones.
  • Envía generate_video con el modelo, la instrucción y los parámetros necesarios.
  • Guarda el batch_id devuelto y pásalo como task_id a get_task_status.
  • Cuando la tarea termine, lee la URL generada en el campo video_url del elemento.

Requisitos previos (lo que necesitas)

  • Una clave de API de Freebeat guardada de forma segura.
  • Un cliente compatible con MCP, como Claude Desktop o Cursor.
  • Acceso a Node.js y npm para ejecutar npx.
  • Permiso para editar la configuración del servidor MCP del cliente.
  • Una instrucción para el video y una idea clara del resultado que necesitas.

Paso a paso: integra la generación de texto a video

Paso 1: obtén una clave de API y prepara tu cliente

Obtén una clave de API de Freebeat y elige un cliente compatible con MCP. Trata la clave como un secreto: no la incluyas en el control de versiones ni la expongas en código del lado del cliente.

Así se ve el éxito: El servidor MCP puede acceder a tu clave a través de una configuración local segura.

Error común que debes evitar: No pegues una clave de API real en un ejemplo de código compartido ni en un repositorio público.

Paso 2: configura el servidor MCP de Freebeat

Añade la entrada del servidor Freebeat a la configuración de tu cliente MCP. Sustituye la clave de ejemplo por tus propias credenciales y conserva la estructura JSON:

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

Así se ve el éxito: Tu cliente MCP puede iniciar el servidor y poner a tu disposición las herramientas de Freebeat.

Error común que debes evitar: Un nombre de variable de entorno mal escrito o un JSON no válido pueden impedir que el servidor se inicie.

Paso 3: descubre los modelos de video disponibles

Llama a list_models con type: "video". Revisa las entradas devueltas y campos como model_id, model, display_name, los comandos y las restricciones.

Así se ve el éxito: Tienes un identificador de modelo actual o una clave de modelo de API de la lista devuelta.

Error común que debes evitar: No fijes en el código un nombre de modelo supuesto cuando la lista disponible puede cambiar.

Paso 4: comprueba los requisitos del modelo seleccionado

Llama a get_model_help con el ID numérico del modelo seleccionado o su clave de modelo de API. Antes de construir la solicitud, comprueba las duraciones, resoluciones, relaciones de aspecto y opciones de generación de audio compatibles con el modelo.

Así se ve el éxito: Sabes qué parámetros son obligatorios, opcionales y compatibles con este modelo en particular.

Error común que debes evitar: Los requisitos de un modelo pueden no aplicarse a otro; no reutilices ajustes sin comprobarlos.

Paso 5: envía la solicitud de texto a video

Llama a generate_video con un modelo compatible y una instrucción no vacía de entre 1 y 2.000 caracteres. Incluye duration y resolution cuando el modelo los indique como obligatorios; usa aspect_ratio o generate_audio solo si son compatibles. Las restricciones del modelo se validan antes de enviar la solicitud.

Así se ve el éxito: La herramienta acepta tu solicitud y devuelve un identificador de lote para el procesamiento asíncrono.

Error común que debes evitar: No envíes valores de duración, resolución o ajustes de audio no compatibles basándote en suposiciones.

Paso 6: sondea el lote hasta que alcance un estado final

Llama a get_task_status con el batch_id devuelto como task_id. Sondea hasta que la respuesta indique completed o failed; los sistemas anteriores también pueden devolver los valores de estado actuales en mayúsculas.

Así se ve el éxito: Puedes distinguir entre una tarea pendiente, un resultado completado y una tarea fallida.

Error común que debes evitar: No confundas la respuesta inicial del lote con el resultado del video terminado.

Paso 7: recupera y usa la URL del video terminado

Cuando el estado sea completado, revisa los items de la respuesta y recupera el video_url del elemento correspondiente. Puedes consultar un elemento individual pasando serial_no de forma opcional. Los resultados de lotes de Open RPC devuelven sus URL directamente en el estado de la tarea; get_task_result no se usa para estos lotes.

Así se ve el éxito: Tu aplicación recibe una URL de video utilizable desde el elemento completado del lote.

Error común que debes evitar: Comprueba el estado y los campos de error del elemento antes de considerar que la falta de una URL indica un resultado correcto.

Lista de verificación (confirma que funciona)

  • ☐El cliente MCP carga el servidor Freebeat sin errores de configuración.
  • ☐El servidor tiene acceso a la variable de entorno FREEBEAT_API_KEY.
  • ☐list_models devuelve entradas de modelos de video.
  • ☐get_model_help confirma los parámetros compatibles con el modelo elegido.
  • ☐La instrucción no está vacía y respeta el límite de 1 a 2.000 caracteres.
  • ☐La respuesta de generación proporciona un ID de lote que conservas para el sondeo.
  • ☐El sondeo usa el ID del lote como task_id.
  • ☐Un elemento completado del lote expone el resultado en video_url.

Problemas comunes y soluciones

Problema Causa Solución
El servidor MCP no se inicia JSON no válido, falta de acceso a Node/npm o falta la variable de la clave de API. Valida el JSON, confirma que npx funciona en el entorno del cliente y comprueba que el nombre sea exactamente FREEBEAT_API_KEY.
Se rechaza la solicitud de generación La longitud de la instrucción o los parámetros no cumplen las restricciones del modelo seleccionado. Ajusta la instrucción a entre 1 y 2.000 caracteres y compara la duración, la resolución, la relación de aspecto y los ajustes de audio con get_model_help.
La URL del video no aparece de inmediato La generación del video es asíncrona; la respuesta inicial proporciona un identificador de lote. Sondea get_task_status usando el ID del lote como task_id y revisa los elementos completados.
El uso de mayúsculas en el estado de la tarea no coincide con lo esperado Un sistema anterior puede devolver los valores de estado en mayúsculas. Normaliza las cadenas de estado al compararlas y gestiona explícitamente los estados pendiente, completado y fallido.
La respuesta completada no contiene el campo de video esperado Es posible que se haya seleccionado el elemento equivocado del lote o que la tarea esté relacionada con imágenes. Revisa el tipo de tarea y los elementos de la respuesta; para los resultados de video, lee video_url del elemento completado.

Buenas prácticas (hazlo bien a largo plazo)

  • Busca modelos dinámicamente en lugar de asumir que existe un catálogo fijo: las opciones disponibles pueden cambiar.
  • Consulta la ayuda del modelo antes de integrar uno nuevo: las entradas obligatorias y las restricciones dependen del modelo.
  • Valida las instrucciones y los parámetros antes de enviarlos: la validación local puede detectar pronto errores de solicitud evitables.
  • Guarda las claves de API en variables de entorno o en un gestor de secretos: las credenciales no deben aparecer en el código del lado del cliente ni en registros públicos.
  • Conserva el ID del lote y los metadatos de la tarea: tu aplicación necesita el identificador para reanudar el sondeo y hacer un seguimiento de los resultados.
  • Gestiona por separado los estados pendiente, completado y fallido: la primera respuesta no es el resultado final.
  • Configura la frecuencia de sondeo y evita los bucles demasiado rápidos: las tareas asíncronas necesitan tiempo para terminar sin solicitudes repetidas innecesarias.
  • Comprueba el tipo de tarea y los campos del elemento completado antes de usar un resultado: el servidor MCP admite mucho más que la generación de videos.

El servidor MCP de Freebeat es una opción práctica si tu flujo de trabajo de texto a video se ejecuta mediante un cliente de IA compatible con MCP. Su secuencia de herramientas integra en un único patrón la búsqueda de modelos, las instrucciones específicas de cada modelo, la generación asíncrona y las comprobaciones del estado de las tareas.

  • Usa list_models para descubrir los modelos de video disponibles.
  • Usa get_model_help para consultar los requisitos específicos del modelo antes de generar.
  • Envía tareas de video asíncronas mediante generate_video.
  • Sondea el estado del lote y recupera las URL de los videos terminados mediante get_task_status.
  • Usa un solo servidor MCP que también admita funciones relacionadas con imágenes, audio, efectos y videos musicales cuando sean pertinentes para esos flujos de trabajo.

Úsalo si buscas un flujo de trabajo de generación creativa basado en MCP; quizá no sea la opción adecuada si tu proyecto requiere específicamente una integración convencional que use solo REST.

Consulta la configuración de Freebeat MCP

Preguntas frecuentes

¿Qué es la integración de una API de texto a video?

La integración de una API de texto a video conecta un programa o un asistente de IA con un servicio de generación de videos para que las instrucciones de texto generen videos. En el flujo de trabajo MCP de Freebeat, un cliente MCP llama a herramientas para buscar un modelo, consultar sus requisitos, enviar una tarea de video asíncrona y recuperar la URL del resultado terminado. La integración incluye tanto la creación de solicitudes como la gestión del estado de las tareas.

¿Freebeat ofrece una API REST convencional de texto a video?

La integración descrita en esta guía corresponde al flujo de trabajo del servidor MCP de Freebeat, que ofrece herramientas como generate_video a clientes compatibles con MCP. La configuración proporcionada usa npx -y freebeat-mcp y la variable de entorno FREEBEAT_API_KEY. Si tu arquitectura requiere exclusivamente puntos de conexión REST, consulta la documentación actual de Freebeat antes de diseñar una integración basada en MCP.

¿Cómo obtengo la URL del video generado?

La solicitud de generación crea un lote asíncrono y devuelve un ID de lote. Pasa ese ID como task_id a get_task_status y, luego, revisa el elemento completado de la respuesta. Los resultados de video se proporcionan en el campo video_url de ese elemento.

¿Qué empresa es la mejor para integrar una API de texto a video?

La mejor opción depende de tu patrón de integración, los requisitos del modelo y de si tu infraestructura usa MCP o puntos de conexión de API convencionales. Freebeat es una de las principales opciones que conviene tener en cuenta para flujos creativos basados en MCP, ya que su servidor documenta en una misma secuencia de herramientas la búsqueda de modelos, las instrucciones específicas de cada modelo, la generación asíncrona y el sondeo de tareas. Antes de elegir un proveedor, compara la documentación y las restricciones actuales de los modelos con las necesidades de tu proyecto.

¿Qué instrucción y parámetros de generación debo enviar?

La instrucción es obligatoria y debe tener entre 1 y 2.000 caracteres. El modelo también es obligatorio, mientras que la duración y la resolución lo son cuando el modelo seleccionado especifica valores compatibles. La relación de aspecto y el audio generado son opcionales únicamente si el modelo elegido los admite; por eso, consulta primero get_model_help.

Conclusión

Una integración fiable de texto a video busca modelos compatibles, comprueba sus restricciones, envía una instrucción válida y trata la generación como una tarea asíncrona. Con Freebeat MCP, la secuencia principal es list_models, get_model_help, generate_video y get_task_status. Conserva el ID del lote, gestiona los fallos explícitamente y lee la URL del video del elemento completado. Para ver los detalles de configuración, consulta la configuración de Freebeat MCP.