Webhooks vs. polling na API Meshy: quando os resultados estão prontos

As tarefas de geração da API 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 foi concluída: polling e webhooks — além de como evitar o problema mais comum de "erros ao recuperar o modelo".

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

• PENDING — a tarefa foi enfileirada, 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 é concluído.

• SUCCEEDED — a tarefa foi concluída com sucesso e progress é 100. As URLs dos resultados (arquivos de modelo, texturas, pré-visualizações) agora 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 da conclusão.

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

Polling significa chamar repetidamente o endpoint "get task" para o ID da sua tarefa até que ela atinja um estado terminal (SUCCEEDED, FAILED ou CANCELED). Um loop de polling simples funciona assim:

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

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

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

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

• Adicione uma proteção 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 é mais adequado.

Em vez de perguntar repetidamente "já terminou?", você pode pedir ao Meshy para notificar seu servidor no momento em que uma tarefa for concluída. Para usar webhooks:

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

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

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

• Ao receber, 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.

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

Independentemente de você usar polling ou webhooks, seu código de tratamento de resultados deve ser idempotente — ou seja, seguro para ser executado mais de uma vez para a mesma tarefa, sem efeitos colaterais. Isso é importante 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 manter a idempotência, baseie sua lógica de processamento no id da tarefa — por exemplo, verifique se você já armazenou/baixou os resultados para esse id antes de fazer isso novamente, e torne o "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 do resultado (URLs de modelo, texturas, miniaturas) está completo e seguro para uso. Concretamente, no seu código:

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

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

• Baixe os arquivos de resultado prontamente assim que SUCCEEDED — os ativos gerados são mantidos nos servidores da Meshy apenas por um tempo limitado, após o qual as URLs não serão mais resolvidas.

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

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

• Recursos expirados. Esperar muito tempo após SUCCEEDED para baixar — as URLs de resultado param de funcionar depois que a janela de retenção para aquele tipo de tarefa passa.

• Usar um ID de tarefa obsoleto ou incorreto — por exemplo, reutilizar um ID de uma solicitação anterior e 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/tempo limite entre seu servidor e a Meshy que são interpretados erroneamente como um problema de geração.

Se uma geração não atender às suas expectativas, ou se uma solicitação falhar completamente, lembre-se do seguinte:

• A API Meshy atualmente não oferece suporte para tentar novamente uma tarefa existente no mesmo local — para tentar de novo, envie uma nova solicitação de geração, que consumirá créditos normalmente.

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

• Para o polling em si, tente novamente a chamada de "get task" em caso de erros de rede transitórios, mas não trate um único polling com falha como falha de geração — só confie no campo status depois de obter uma resposta bem-sucedida.

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

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

O polling é mais simples de configurar e adequado para scripts de baixo volume ou pontuais. Webhooks são melhores para integrações de produção com muitas tarefas simultâneas, pois evitam requisiçõ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 ignore o reprocessamento se ele já tiver sido tratado.

Recorra ao polling da tarefa por id diretamente. Também confirme se seu endpoint é acessível publicamente via HTTPS e retorna uma resposta 2xx rapidamente, pois endpoints lentos ou inacessíveis podem causar problemas de entrega.

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

Os arquivos de resultado são mantidos nos servidores da Meshy apenas por tempo limitado após a conclusão de uma tarefa, portanto, baixe os resultados para o seu próprio armazenamento assim que a tarefa for concluída com sucesso, em vez de esperar.