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.