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 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 das tarefas 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 obter o modelo".

Cada tarefa de geração passa por um pequeno conjunto 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 avança.

• SUCCEEDED — a tarefa foi concluída com sucesso e progress é 100. Os URLs dos resultados (ficheiros de modelos, texturas, pré-visualizações) estão agora disponíveis na resposta.

• FAILED — a tarefa não pôde ser concluída. 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 usar os URLs dos resultados até que o status da tarefa seja SUCCEEDED. Ler resultados enquanto a tarefa ainda está PENDING ou IN_PROGRESS é a causa mais comum de relatórios de "erros ao obter o modelo".

Polling significa chamar repetidamente o endpoint "get task" do seu ID de tarefa até que esta atinja um estado terminal (SUCCEEDED, FAILED ou CANCELED). Um ciclo de polling simples tem este aspeto:

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

• Chame o endpoint correspondente "retrieve task" (por exemplo, o endpoint Text to 3D ou Image to 3D por id de tarefa) em intervalos — 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 dos resultados), FAILED ou CANCELED.

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

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 é geralmente mais adequado.

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

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

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

• Quando a tarefa atinge um estado terminal, a Meshy envia um payload para o seu endpoint contendo 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 notificação quase instantânea, mas deve ainda manter uma solução de polling periódico para tarefas em que a entrega do webhook possa falhar ou atrasar-se (por exemplo, devido a um problema de rede transitório do seu lado).

Quer use polling ou webhooks, o seu código de tratamento de resultados deve ser idempotente — seguro para ser executado 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 (novas tentativas no lado do remetente, duplicação de rede, etc.).

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

Para se manter idempotente, baseie a sua lógica de processamento no id da tarefa — por exemplo, verifique se já armazenou/descarregou os resultados para esse id antes de o fazer novamente, e torne "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 de modelos, texturas, miniaturas) está completo e é seguro usar. Concretamente, no seu código:

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

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

• Descarregue os ficheiros de resultado prontamente após SUCCEEDED — os ativos gerados são retidos nos servidores da Meshy apenas por tempo limitado, após o qual os URLs deixarão de resolver.

A maioria dos relatórios de "não consigo obter o meu modelo" tem origem numa destas causas:

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

• Ativos expirados. Esperar demasiado tempo após SUCCEEDED para descarregar — os URLs dos resultados deixam de funcionar após a janela de retenção desse tipo de tarefa.

• Usar um ID de tarefa desatualizado 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 resubmeter.

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

Se uma geração não corresponde às suas expectativas, ou um pedido falha totalmente, tenha em mente o seguinte:

• A Meshy API atualmente 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), uma breve espera com retrocesso exponencial antes de resubmeter o pedido é razoável.

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

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

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

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 concorrentes, pois evitam pedidos repetidos desnecessários e notificam-no imediatamente quando uma tarefa é concluída.

Trate-o de forma idempotente — verifique o id da tarefa contra o que já processou, e ignore o reprocessamento se já tiver sido tratado.

Volte ao polling da tarefa por id diretamente. Confirme também que o seu endpoint é publicamente acessível por HTTPS e devolve rapidamente uma resposta 2xx, já que endpoints lentos ou inacessíveis podem causar problemas de entrega.

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

Os ficheiros de resultado são retidos nos servidores da Meshy apenas por tempo limitado após a conclusão de uma tarefa, por isso descarregue os resultados para o seu próprio armazenamento assim que a tarefa for bem-sucedida, em vez de esperar.

• Porque encontro consistentemente erros ao obter os modelos do resultado de geração usando a API?