Meshy API Webhooks vs Polling: quando os resultados estão prontos

As tarefas de geração da Meshy API (Text to 3D, Image to 3D, Rigging e muito mais) são executadas de forma assíncrona — submete uma tarefa e depois precisa de saber quando está concluída antes de obter 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 — e ainda como evitar o problema mais comum de "erros ao obter o modelo".

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

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

• IN_PROGRESS — a tarefa está a ser processada ativamente. O campo progress (0-100) aumenta à medida que o trabalho é concluído.

• SUCCEEDED — a tarefa terminou com êxito e progress está em 100. Os URLs dos resultados (ficheiros de modelo, texturas, pré-visualizações) estão agora disponíveis na resposta.

• FAILED — a tarefa não foi possível concluir. Os créditos das tarefas falhadas 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 obter ou utilizar os URLs dos resultados enquanto o status da tarefa não for SUCCEEDED. Ler resultados enquanto uma tarefa ainda está PENDING ou IN_PROGRESS é a causa mais comum dos relatos de "erros ao obter o modelo".

O polling consiste em chamar repetidamente o endpoint "get task" para o ID da sua tarefa até esta atingir um estado terminal (SUCCEEDED, FAILED ou CANCELED). Um ciclo de polling simples tem o seguinte aspeto:

• Submeta o pedido de geração e guarde o id da tarefa devolvido.

• Chame o endpoint "retrieve task" correspondente (por exemplo, o endpoint task-by-id de Text to 3D ou Image to 3D) num intervalo — alguns segundos é o habitual.

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

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

• Adicione ao seu cliente uma proteção razoável de timeout/número máximo de tentativas para que uma tarefa bloqueada não faça polling indefinidamente.

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

Em vez de perguntar repetidamente "já está pronto?", pode pedir ao Meshy que notifique o seu servidor no momento em que uma tarefa termina. Para usar webhooks:

• Configure um URL de webhook (callback) que o Meshy consiga alcançar — normalmente isto define-se ao nível das definições da conta/API ou é passado como parâmetro no pedido de geração, consoante o endpoint.

• Garanta que o seu endpoint é acessível publicamente por HTTPS e responde rapidamente (devolva um status 2xx de imediato e depois processe o payload de forma assíncrona).

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

• Ao recebê-lo, consulte os detalhes completos da tarefa por id através da API em vez de confiar apenas no corpo do webhook, para garantir que tem o resultado autoritativo e atualizado.

Os webhooks reduzem chamadas desnecessárias à API e dão-lhe uma notificação quase instantânea, mas deve ainda assim manter um polling periódico como alternativa para as tarefas em que a entrega de um webhook possa falhar ou atrasar-se (por exemplo, devido a um problema de rede transitório do seu lado).

Quer utilize polling ou webhooks, o código que processa os resultados deve ser idempotente — ou seja, deve ser seguro executá-lo mais do que uma vez para a mesma tarefa sem efeitos secundários. Isto é importante porque:

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

• Um ciclo de polling e um gestor de webhooks podem tentar ambos processar a mesma tarefa concluída, se ambos estiverem em execução.

Para manter a idempotência, baseie a sua lógica de processamento no id da tarefa — por exemplo, verifique se já armazenou/transferiu os resultados para esse id antes de o fazer novamente, e faça de "marcar como processado" um único passo atómico na sua própria base de dados.

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

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

• Não te baseies apenas no progress — verifica sempre também o status, uma vez que o progresso pode apresentar valores elevados brevemente antes de a tarefa estar totalmente concluída.

• Transfere os ficheiros de resultado atempadamente assim que o estado for SUCCEEDED — os recursos gerados só são mantidos nos servidores da Meshy durante um período limitado, após o qual os URLs deixarão de resolver.

A maioria dos relatos de «não consigo obter o meu modelo» remete para uma destas causas:

• Obter demasiado cedo. Chamar o URL do resultado, ou ler os campos do modelo, antes de status ser SUCCEEDED. Esta é, de longe, a causa mais frequente.

• Recursos expirados. Esperar demasiado tempo após SUCCEEDED para transferir — os URLs dos resultados deixam de funcionar depois de passar a janela de retenção para esse tipo de tarefa.

• Utilizar um ID de tarefa obsoleto ou errado — por exemplo, reutilizar um ID de um pedido anterior não relacionado.

• Tratar FAILED como um estado transitório e continuar a fazer polling de uma tarefa que já falhou, em vez de a submeter novamente.

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

Se uma geração não corresponder às suas expectativas, ou se um pedido falhar completamente, tenha em conta o seguinte:

• Atualmente, a Meshy API não suporta repetir uma tarefa existente no local — para tentar novamente, submeta um novo pedido 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 o pedido.

• No que diz respeito ao polling, repita a chamada "get task" em caso de erros de rede transitórios, mas não trate uma única consulta falhada como uma falha de geração — só confie no campo status depois de obter uma resposta bem-sucedida.

• Se precisar de funcionalidade de repetição integrada para gerações, contacte a equipa de vendas da Meshy para conhecer as opções do plano enterprise.

Isto acontece quase sempre porque o código está a tentar ler o resultado antes de a tarefa ter terminado. Confirme sempre que o status é SUCCEEDED (e que o progress é 100) antes de obter os URLs dos modelos.

O polling é mais simples de configurar e adequado para scripts de baixo volume ou pontuais. Os webhooks são melhores para integrações de produção com muitas tarefas simultâneas, uma vez que evitam pedidos repetidos desnecessários e notificam-no imediatamente quando uma tarefa termina.

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

Em alternativa, faça polling da tarefa diretamente por id. Confirme também que o seu endpoint está acessível publicamente através de HTTPS e devolve uma resposta 2xx rápida, uma vez que endpoints lentos ou inacessíveis podem causar problemas na entrega.

Atualmente, não — terá de submeter um novo pedido de geração, que consome créditos normalmente. Contacte a equipa de vendas sobre opções empresariais se precisar de suporte de tentativas repetidas integrado.

Os ficheiros de resultado só ficam retidos nos servidores da Meshy durante um período limitado após a conclusão de uma tarefa, por isso transfira os resultados para o seu próprio armazenamento assim que a tarefa for concluída, em vez de esperar.