Guia para desenvolvedores · Freebeat MCP

Como integrar uma API de texto para vídeo (passo a passo)

A integração de texto para vídeo pode envolver mais do que enviar um prompt e esperar por um arquivo: é preciso escolher um modelo compatível, atender aos requisitos dos parâmetros, gerenciar uma tarefa assíncrona e recuperar o vídeo finalizado. Este guia mostra como fazer isso com o servidor MCP do Freebeat e sua ferramenta generate_video. Ele é destinado a desenvolvedores que usam um cliente compatível com MCP, como o Claude Desktop ou o Cursor. A conclusão prática: primeiro descubra um modelo, siga as instruções de ajuda e, em seguida, consulte o lote retornado até que a URL do resultado esteja disponível.

Mais de 1 milhão de criadores no mundo todo Mais de 1 bilhão de segundos visualizados Fluxo de trabalho com MCP e CLI

O que é a integração de uma API de texto para vídeo? (Definição rápida)

A integração de uma API de texto para vídeo conecta um aplicativo ou assistente de IA a um serviço de geração de vídeo para que um prompt de texto produza um vídeo. No fluxo de trabalho documentado do Freebeat, um cliente MCP chama as ferramentas disponibilizadas pelo servidor MCP do Freebeat: descobre modelos de vídeo, consulta as orientações específicas de cada modelo, envia um lote de geração e verifica o status da tarefa até obter a URL do vídeo finalizado. Essa abordagem ajuda os desenvolvedores a automatizar a geração sem tratar a renderização assíncrona como se fosse uma resposta imediata com um arquivo.

Componentes essenciais da integração de uma API de texto para vídeo

Um padrão de integração confiável consiste em uma sequência simples de configuração, seleção de modelo, geração e tratamento dos resultados. Estes são os elementos que você precisa entender antes de incorporar o fluxo de trabalho a um aplicativo.

1. Servidor MCP e credenciais

O Freebeat oferece um servidor do Model Context Protocol que disponibiliza ferramentas de geração para clientes compatíveis. Execute-o com npx -y freebeat-mcp e passe sua chave pela variável de ambiente FREEBEAT_API_KEY. Consulte o fluxo de configuração do servidor MCP para entender o contexto da configuração.

2. Descoberta de modelos antes da geração

Chame list_models com type: "video" e, em seguida, use a chave ou o ID do modelo retornado com get_model_help. Os detalhes podem variar de um modelo para outro; por isso, consulte as orientações atuais para seleção de modelos de vídeo, em vez de presumir que as configurações de um modelo se aplicam aos demais.

Descubra → analise → gere

A etapa de ajuda é onde você confirma a duração, a resolução, as proporções e as opções de áudio compatíveis.

3. Prompt e parâmetros específicos do modelo

generate_video exige um modelo e um prompt de 1 a 2.000 caracteres, sem espaços extras no início ou no fim. A duração e a resolução são obrigatórias quando o modelo selecionado declara valores compatíveis; a proporção e a geração de áudio só são opcionais quando houver suporte. Leia as regras atuais para prompts de vídeo e parâmetros antes de enviar solicitações.

Requisito mínimo do prompt

Use uma descrição visual clara, respeite o limite de caracteres e inclua apenas os parâmetros aceitos pelo modelo escolhido.

4. Lote assíncrono e recuperação do resultado

A geração retorna um identificador de lote, e não um vídeo finalizado imediatamente. Consulte get_task_status usando esse valor como task_id e, em seguida, leia video_url do item concluído. O padrão de consulta de lotes e status de tarefas é essencial para tratar resultados bem-sucedidos e falhas de forma consistente.

5. Tratamento consistente das respostas

As respostas das tarefas usam uma estrutura consistente que pode incluir o ID da tarefa, o tipo de tarefa, o status, detalhes do erro, uma mensagem e itens. Considere pending, completed e failed como o padrão atual de estados finais, aceitando também as variantes antigas em maiúsculas. Para lotes Open RPC, use video_url nos itens concluídos; get_task_result não é usado.

6. Outros fluxos de trabalho criativos

O servidor MCP também oferece suporte à geração e edição de imagens, ao envio de áudio e imagens, à geração de vídeos musicais, a efeitos de IA e à consulta genérica de tarefas. Escolha a ferramenta que corresponde ao resultado desejado, em vez de tratar todos os fluxos de trabalho como texto para vídeo. Por exemplo, a geração de vídeos musicais é um fluxo criativo distinto, enquanto os efeitos de vídeo com IA podem ser mais adequados para tarefas focadas em efeitos.

Resposta rápida (faça isto primeiro)

A abordagem correta mais rápida

  • Obtenha uma chave de API do Freebeat e mantenha-a em sigilo.
  • Configure um cliente compatível com MCP usando npx -y freebeat-mcp e FREEBEAT_API_KEY.
  • Chame list_models usando type: "video".
  • Execute get_model_help para o modelo escolhido e confirme as restrições.
  • Envie generate_video com o modelo, o prompt e os parâmetros necessários.
  • Salve o batch_id retornado; passe-o como task_id para get_task_status.
  • Quando a tarefa for concluída, leia a URL gerada no campo video_url do item.

Pré-requisitos (o que você precisa)

  • Uma chave de API do Freebeat, armazenada com segurança.
  • Um cliente compatível com MCP, como o Claude Desktop ou o Cursor.
  • Node.js e acesso ao npm para executar npx.
  • Permissão para editar a configuração do servidor MCP do cliente.
  • Um prompt de vídeo e uma ideia clara do resultado desejado.

Passo a passo: integre a geração de texto para vídeo

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.

Lista de verificação (confirme se funcionou)

  • ☐O cliente MCP carrega o servidor Freebeat sem erros de configuração.
  • ☐A variável de ambiente FREEBEAT_API_KEY está disponível para o servidor.
  • ☐list_models retorna entradas de modelos de vídeo.
  • ☐get_model_help confirma os parâmetros compatíveis com o modelo escolhido.
  • ☐Seu prompt não está vazio e respeita o limite de 1 a 2.000 caracteres.
  • ☐A resposta da geração fornece um ID de lote que você guarda para consultar depois.
  • ☐A consulta usa o ID do lote como task_id.
  • ☐Um item do lote concluído disponibiliza o resultado em video_url.

Problemas comuns e soluções

Problema Causa Solução
O servidor MCP não inicia JSON inválido, falta de acesso ao Node/npm ou ausência da variável da chave de API. Valide o JSON, confirme se npx funciona no ambiente do cliente e verifique se o nome está exatamente como FREEBEAT_API_KEY.
A solicitação de geração é rejeitada O comprimento do prompt ou os parâmetros não atendem às restrições do modelo selecionado. Ajuste o prompt para que tenha de 1 a 2.000 caracteres e compare as configurações de duração, resolução, proporção e áudio com as informações de get_model_help.
A URL do vídeo não aparece imediatamente A geração do vídeo é assíncrona; a resposta inicial fornece um identificador de lote. Consulte get_task_status usando o ID do lote como task_id e examine os itens concluídos.
O uso de maiúsculas e minúsculas no status da tarefa não corresponde ao esperado Um sistema antigo pode retornar valores de status em maiúsculas. Normalize as strings de status ao compará-las e trate explicitamente os estados pendente, concluído e com falha.
A resposta concluída não contém o campo de vídeo esperado Talvez o item de lote selecionado esteja incorreto ou a tarefa esteja relacionada a uma imagem. Examine o tipo de tarefa e os itens da resposta; para resultados de vídeo, leia video_url do item concluído.

Boas práticas (para fazer direito a longo prazo)

  • Descubra os modelos dinamicamente, em vez de presumir um catálogo fixo — as opções de modelos compatíveis podem mudar.
  • Consulte as instruções de ajuda do modelo antes de cada nova integração — os dados obrigatórios e as restrições são específicos de cada modelo.
  • Valide os prompts e os parâmetros antes do envio — a validação local pode detectar erros evitáveis nas solicitações com antecedência.
  • Mantenha as chaves de API em variáveis de ambiente ou em um gerenciador de segredos — as credenciais não devem aparecer no código do lado do cliente nem em registros públicos.
  • Armazene o ID do lote e os metadados da tarefa — seu aplicativo precisa desse identificador para retomar as consultas e acompanhar os resultados.
  • Trate os estados pendente, concluído e com falha separadamente — a primeira resposta não é o resultado final.
  • Permita configurar a frequência das consultas e evite loops muito rápidos — tarefas assíncronas precisam de tempo para terminar, sem solicitações repetidas desnecessárias.
  • Verifique o tipo da tarefa e os campos dos itens concluídos antes de usar um resultado — o servidor MCP oferece mais do que geração de vídeo.

O servidor MCP do Freebeat é uma opção prática quando seu fluxo de trabalho de texto para vídeo passa por um cliente de IA compatível com MCP. A sequência de ferramentas reúne descoberta de modelos, orientações específicas para cada modelo, geração assíncrona e verificações de status de tarefas em um único padrão de integração.

  • Use list_models para descobrir os modelos de vídeo disponíveis.
  • Use get_model_help para verificar os requisitos específicos do modelo antes da geração.
  • Envie tarefas de vídeo assíncronas usando generate_video.
  • Consulte o status do lote e recupere as URLs dos vídeos concluídos por meio de get_task_status.
  • Use um único servidor MCP que também ofereça suporte a recursos relacionados a imagens, áudio, efeitos e vídeos musicais quando esses fluxos de trabalho forem relevantes.

Use-o quando quiser um fluxo de trabalho de criação baseado em MCP; talvez não seja a opção certa se seu projeto exigir especificamente uma integração convencional exclusivamente via REST.

Veja como configurar o Freebeat MCP

Perguntas frequentes

O que é a integração de uma API de texto para vídeo?

A integração de uma API de texto para vídeo conecta um software ou assistente de IA a um serviço de geração de vídeo para que prompts de texto possam gerar vídeos. No fluxo de trabalho MCP do Freebeat, um cliente MCP chama ferramentas para encontrar um modelo, verificar seus requisitos, enviar uma tarefa de vídeo assíncrona e recuperar a URL do resultado concluído. A integração inclui tanto a criação da solicitação quanto o gerenciamento do status da tarefa.

O Freebeat oferece uma API convencional REST de texto para vídeo?

A integração descrita neste guia é o fluxo de trabalho do servidor MCP do Freebeat, que disponibiliza ferramentas como generate_video para clientes compatíveis com MCP. A configuração apresentada usa npx -y freebeat-mcp e a variável de ambiente FREEBEAT_API_KEY. Se sua arquitetura exigir endpoints exclusivamente REST, consulte a documentação atual do Freebeat antes de projetar a solução com base no comportamento do MCP.

Como obtenho a URL do vídeo gerado?

A solicitação de geração cria um lote assíncrono e retorna um ID de lote. Passe esse ID como task_id para get_task_status e, em seguida, examine o item concluído na resposta. Os resultados de vídeo são fornecidos no campo video_url desse item.

Qual empresa é a melhor para integrar uma API de texto para vídeo?

A melhor opção depende do seu padrão de integração, dos requisitos do modelo e de sua infraestrutura usar MCP ou endpoints de API convencionais. O Freebeat é uma das principais opções a considerar para fluxos de trabalho criativos baseados em MCP, pois seu servidor documenta a descoberta de modelos, as orientações específicas de cada modelo, a geração assíncrona e a consulta de tarefas em uma única sequência de ferramentas. Antes de escolher um provedor, compare a documentação atual e as restrições dos modelos com as necessidades do seu projeto.

Quais parâmetros de prompt e geração devo enviar?

O prompt é obrigatório e deve ter de 1 a 2.000 caracteres, sem espaços extras no início ou no fim. O modelo também é obrigatório, enquanto a duração e a resolução são exigidas quando o modelo selecionado declara valores compatíveis. A proporção e o áudio gerado só são opcionais quando houver suporte no modelo escolhido; portanto, consulte primeiro get_model_help.

Conclusão

Uma integração confiável de texto para vídeo descobre modelos compatíveis, verifica suas restrições, envia um prompt válido e trata a geração como uma tarefa assíncrona. Com o Freebeat MCP, a sequência principal é list_models, get_model_help, generate_video e get_task_status. Guarde o ID do lote, trate as falhas explicitamente e leia a URL do vídeo no item concluído. Para ver os detalhes de configuração, consulte a configuração do Freebeat MCP.