Passo 1: obtenha uma chave de API e prepare seu cliente
Obtenha uma chave de API do Freebeat e escolha um cliente compatível com MCP. Trate a chave como um segredo: não a inclua no controle de versão nem a exponha em código do lado do cliente.
O que indica que deu certo: você tem uma chave disponível para o servidor MCP por meio de uma configuração local segura.
Erro comum a evitar: não cole uma chave de API real em um exemplo de código compartilhado ou repositório público.
Passo 2: configure o servidor MCP do Freebeat
Adicione a entrada do servidor Freebeat à configuração do cliente MCP. Substitua a chave de exemplo pela sua própria credencial e mantenha a estrutura JSON:
{
"mcpServers": {
"freebeat": {
"command": "npx",
"args": ["-y", "freebeat-mcp"],
"env": {
"FREEBEAT_API_KEY": "your-api-key-here"
}
}
}
}
O que indica que deu certo: seu cliente MCP consegue iniciar o servidor e disponibilizar as ferramentas do Freebeat.
Erro comum a evitar: uma variável de ambiente escrita incorretamente ou um JSON inválido pode impedir a inicialização do servidor.
Passo 3: descubra os modelos de vídeo disponíveis
Chame list_models com type: "video". Analise os campos das entradas retornadas, como model_id, model, display_name, comandos e restrições.
O que indica que deu certo: você tem um identificador de modelo atual ou uma chave de modelo da API obtida na lista retornada.
Erro comum a evitar: não fixe um nome de modelo presumido no código quando a lista disponível pode mudar.
Passo 4: verifique os requisitos do modelo selecionado
Chame get_model_help com o ID numérico ou a chave de modelo da API do modelo selecionado. Antes de construir a solicitação, verifique as durações, resoluções, proporções e opções de geração de áudio compatíveis com o modelo.
O que indica que deu certo: você sabe quais parâmetros são obrigatórios, opcionais e aceitos por esse modelo específico.
Erro comum a evitar: os requisitos de um modelo podem não se aplicar a outro; portanto, não reutilize configurações sem verificá-las.
Passo 5: envie a solicitação de texto para vídeo
Chame generate_video com um modelo compatível e um prompt não vazio, de 1 a 2.000 caracteres, sem espaços extras no início ou no fim. Inclua duration e resolution quando o modelo os declarar obrigatórios; use aspect_ratio ou generate_audio somente quando houver suporte. As restrições do modelo são validadas antes do envio da solicitação.
O que indica que deu certo: a ferramenta aceita sua solicitação e retorna um identificador de lote para processamento assíncrono.
Erro comum a evitar: não envie configurações de duração, resolução ou áudio sem suporte com base em suposições.
Passo 6: consulte o lote até que ele atinja um status final
Chame get_task_status com o batch_id retornado como task_id. Continue consultando até que a resposta indique completed ou failed; em sistemas antigos, os valores de status atuais também podem aparecer em maiúsculas.
O que indica que deu certo: você consegue distinguir um processamento pendente de um resultado concluído ou de uma tarefa com falha.
Erro comum a evitar: não confunda a resposta inicial do lote com o resultado final do vídeo.
Passo 7: recupere e use a URL do vídeo concluído
Quando o status for concluído, examine os items da resposta e recupere o video_url do item relevante. É possível consultar um item individual passando o parâmetro opcional serial_no. Os resultados de lotes Open RPC retornam suas URLs diretamente no status da tarefa; get_task_result não é usado para esses lotes.
O que indica que deu certo: seu aplicativo recebe uma URL de vídeo utilizável do item do lote concluído.
Erro comum a evitar: verifique o status e os campos de erro do item antes de considerar que a ausência de uma URL representa um resultado bem-sucedido.