# Meshy API Webhooks vs Polling: Quando os Resultados Estão Prontos > URL: https://help.meshy.ai/pt-PT/articles/16102100-meshy-api-webhooks-vs-polling-when-results-are-ready > Language: pt-PT > Last updated: 2026-09-09T10:14:44Z 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". ## Ciclo de vida das tarefas 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". ## Exemplo de polling 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. ## Configuração de webhooks 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). ## Idempotência 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. ### status = SUCCEEDED 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. ## Erros comuns 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. ## Novas tentativas 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. ## FAQ ### 1. Porque recebo consistentemente erros ao obter modelos de um resultado de geração através da API? 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. ### 2. Devo usar polling ou webhooks? 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. ### 3. O que deve o meu servidor fazer se receber o mesmo webhook duas vezes? Trate-o de forma idempotente — verifique o `id` da tarefa contra o que já processou, e ignore o reprocessamento se já tiver sido tratado. ### 4. O meu webhook nunca chegou — o que devo fazer? 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. ### 5. Posso repetir uma geração falhada ou insatisfatória diretamente através da API? 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. ### 6. Quanto tempo tenho para descarregar os meus resultados após o estado ser SUCCEEDED? 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.