Webhooks vs Polling na API da Meshy: Quando os Resultados Estão Prontos

As tarefas de geração da API da Meshy (Text to 3D, Image to 3D, Rigging e mais) são executadas de forma assíncrona — você envia uma tarefa e depois precisa descobrir quando ela foi concluída antes de buscar o resultado. Este artigo explica o ciclo de vida da tarefa e as duas formas suportadas de saber quando uma tarefa terminou: polling e webhooks — além de como evitar o problema mais comum de "erros ao recuperar o modelo".

Cada tarefa de geração passa por um pequeno conjunto de estados, retornados no campo status do objeto da tarefa:

• PENDING — a tarefa foi colocada na fila, mas o processamento ainda não começou.

• IN_PROGRESS — a tarefa está sendo processada ativamente. O campo progress (0-100) aumenta conforme o trabalho avança.

• SUCCEEDED — a tarefa foi concluída com sucesso e progress está em 100. As URLs de resultado (arquivos de modelo, texturas, prévias) já estão disponíveis na resposta.

• FAILED — a tarefa não pôde ser concluída. Os créditos de tarefas com falha são reembolsados automaticamente.

• CANCELED — a tarefa foi cancelada antes de ser concluída.

A regra mais importante ao integrar com a API: nunca tente buscar ou usar as URLs de resultado antes que o status da tarefa seja SUCCEEDED. Ler resultados enquanto a tarefa ainda está PENDING ou IN_PROGRESS é a causa mais comum de relatos de "erros ao recuperar o modelo".

Polling significa chamar repetidamente o endpoint de "obter tarefa" para o ID da sua tarefa até que ela atinja um estado terminal (SUCCEEDED, FAILED ou CANCELED). Um loop de polling simples se parece com isto:

• Envie a solicitação de geração e armazene o id da tarefa retornado.

• Chame o endpoint correspondente de "recuperar tarefa" (por exemplo, o endpoint de tarefa por ID do Text to 3D ou Image to 3D) em intervalos — alguns segundos é o típico.

• Verifique o campo status em cada resposta. Continue fazendo polling enquanto ele estiver PENDING ou IN_PROGRESS.

• Interrompa o polling assim que status for SUCCEEDED (leia as URLs de resultado), FAILED ou CANCELED.

• Adicione um limite razoável de timeout/número máximo de tentativas no seu cliente para que uma tarefa travada não faça polling para sempre.

O polling é simples e funciona bem para scripts, jobs em lote e integrações de baixo volume. Para integrações de alto volume ou sensíveis à latência, um webhook geralmente é uma opção melhor.

Em vez de perguntar repetidamente "já terminou?", você pode pedir à Meshy que notifique seu servidor no momento em que uma tarefa terminar. Para usar webhooks:

• Configure uma URL de webhook (callback) que a Meshy possa acessar — isso normalmente é definido no nível das configurações da conta/API ou passado como um parâmetro na solicitação de geração, dependendo do endpoint.

• Garanta que seu endpoint seja publicamente acessível via HTTPS e responda rapidamente (retorne um status 2xx imediatamente e processe o payload de forma assíncrona).

• Quando a tarefa atingir um estado terminal, a Meshy envia um payload para o seu endpoint contendo o id da tarefa e seu status final.

• Ao recebê-lo, consulte os detalhes completos da tarefa pelo id via API em vez de confiar apenas no corpo do webhook, para garantir que você tenha o resultado autoritativo e atualizado.

Os webhooks reduzem chamadas desnecessárias à API e oferecem notificação quase instantânea, mas você ainda deve manter um fallback de polling periódico para tarefas em que a entrega do webhook possa ser perdida ou atrasada (por exemplo, devido a um problema transitório de rede do seu lado).

Quer você use polling ou webhooks, seu código de manipulação de resultados deve ser idempotente — seguro para ser executado mais de uma vez para a mesma tarefa sem efeitos colaterais. Isso importa porque:

• Um webhook pode ser entregue mais de uma vez para a mesma tarefa (novas tentativas no lado do remetente, duplicação de rede, etc.).

• Um loop de polling e um manipulador de webhook podem tentar processar a mesma tarefa concluída se ambos estiverem em execução.

Para se manter idempotente, baseie sua lógica de processamento no id da tarefa — por exemplo, verifique se você já armazenou/baixou os resultados desse id antes de fazê-lo novamente, e torne "marcar como processado" uma única etapa atômica no seu próprio banco de dados.

Uma resposta com "status": "SUCCEEDED" e "progress": 100 é o único sinal que garante que o payload de resultado (URLs do modelo, texturas, miniaturas) está completo e é seguro de usar. Concretamente, no seu código:

• Verifique status === "SUCCEEDED" antes de ler qualquer coisa dos campos result/URL do modelo.

• Não confie apenas no progress — sempre verifique também o status, já que o progresso pode brevemente mostrar valores altos antes que a tarefa esteja totalmente finalizada.

• Baixe os arquivos de resultado prontamente após SUCCEEDED — os assets gerados são retidos nos servidores da Meshy apenas por tempo limitado, após o qual as URLs não resolverão mais.

A maioria dos relatos de "não consigo recuperar meu modelo" se deve a uma destas causas:

• Buscar cedo demais. Chamar a URL de resultado, ou ler os campos do modelo, antes que status seja SUCCEEDED. Esta é de longe a causa mais frequente.

• Assets expirados. Esperar tempo demais após SUCCEEDED para baixar — as URLs de resultado param de funcionar após o período de retenção daquele tipo de tarefa.

• Usar um ID de tarefa desatualizado ou errado — por exemplo, reutilizar um ID de uma solicitação anterior não relacionada.

• Tratar FAILED como um estado transitório e continuar fazendo polling de uma tarefa que já falhou em vez de reenviá-la.

• Problemas de rede/timeout entre seu servidor e a Meshy que são mal interpretados como um problema de geração.

Se uma geração não atender às suas expectativas, ou uma solicitação falhar por completo, tenha em mente o seguinte:

• A API da Meshy atualmente não suporta repetir uma tarefa existente no lugar — para tentar novamente, envie uma nova solicitação de geração, que consumirá créditos normalmente.

• Para falhas transitórias de rede ao chamar a API (timeouts, respostas 5xx), uma breve espera com backoff exponencial antes de reenviar a solicitação é razoável.

• Para o polling em si, repita a chamada de "obter tarefa" em erros transitórios de rede, mas não trate uma única falha de polling como uma falha de geração — confie apenas no campo status quando obtiver uma resposta bem-sucedida.

• Se você precisar de funcionalidade integrada de novas tentativas para gerações, entre em contato com a equipe de vendas da Meshy sobre opções de plano enterprise.

Isso quase sempre acontece porque o código está tentando ler o resultado antes de a tarefa ter terminado. Sempre confirme que status é SUCCEEDED (e progress é 100) antes de recuperar as URLs do modelo.

O polling é mais simples de configurar e adequado para scripts de baixo volume ou uso único. Os webhooks são melhores para integrações de produção com muitas tarefas concorrentes, pois evitam solicitações repetidas desnecessárias e notificam você imediatamente quando uma tarefa é concluída.

Trate-o de forma idempotente — verifique o id da tarefa em relação ao que você já processou e pule o reprocessamento se já tiver sido tratado.

Recorra ao polling da tarefa pelo id diretamente. Também confirme que seu endpoint é publicamente acessível via HTTPS e retorna uma resposta 2xx rápida, já que endpoints lentos ou inacessíveis podem causar problemas de entrega.

Atualmente não — você precisará enviar uma nova solicitação de geração, que consome créditos normalmente. Entre em contato com as vendas sobre opções enterprise se precisar de suporte integrado de novas tentativas.

Os arquivos de resultado são retidos nos servidores da Meshy apenas por tempo limitado após a conclusão de uma tarefa, então baixe as saídas para seu próprio armazenamento assim que a tarefa for bem-sucedida, em vez de esperar.

• Por que consistentemente encontro erros ao recuperar os modelos do resultado de geração usando a API?