# Webhooks vs Polling na API da Meshy: Quando os Resultados Estão Prontos > URL: https://help.meshy.ai/pt-BR/articles/16102100-meshy-api-webhooks-vs-polling-when-results-are-ready > Language: pt-BR > Last updated: 2026-09-09T10:03:50Z 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". ## Ciclo de vida da tarefa 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". ## Exemplo de polling 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. ## Configuração de webhook 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). ## Idempotência 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. ### status = SUCCEEDED 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. ## Erros comuns 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. ## Novas tentativas 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. ## FAQ ### 1. Por que consistentemente recebo erros ao recuperar modelos de um resultado de geração via API? 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. ### 2. Devo usar polling ou webhooks? 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. ### 3. O que meu servidor deve fazer se receber o mesmo webhook duas vezes? 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. ### 4. Meu webhook nunca chegou — o que devo fazer? 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. ### 5. Posso repetir uma geração com falha ou insatisfatória diretamente pela API? 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. ### 6. Por quanto tempo posso baixar meus resultados depois que o status for SUCCEEDED? 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.