lowpoly será descontinuado em 30 de out. de 2026. meshy-7 como modelo de geração 3D será descontinuado em 31 de dez. de 2026; como modelo de textura continua disponível. Troque de modelo antes dessas datas para evitar erros nas solicitações. Ver todas as descontinuações

Webhooks

Faça o Meshy enviar uma requisição POST ao seu servidor quando uma tarefa da API avançar ou terminar, para que você não precise fazer polling.


Por que usar webhooks

Webhooks dão menos trabalho e custam menos do que fazer polling da API para verificar o status de cada tarefa. O Meshy envia cada atualização assim que ela acontece, então você a recebe mais rápido, e webhooks escalam melhor do que polling. Você também envia menos requisições, o que o mantém mais longe dos seus limites de taxa.


Configurar um webhook

Para adicionar um webhook, siga estes passos:

  1. Abra a página de Webhooks na Plataforma do Desenvolvedor e clique em Create Webhook.
  2. Em Payload URL, informe a URL que receberá as entregas. O Meshy entrega apenas via https://.
  3. Guarde uma cópia do Webhook Secret que a caixa de diálogo preenche. Toda entrega o carrega, para que seu servidor possa verificar que a requisição veio do Meshy. Para um webhook que você já tem, clique no ícone de olho na coluna Secret para vê-lo.
  4. Selecione Active e clique em Confirm.

Cada conta pode ter 5 webhooks ativos, e 10 no total. Todo webhook ativo recebe as atualizações de status de todas as suas tarefas da API.

Para testar um webhook com um servidor no seu computador, veja Testar no seu computador.


Processar uma entrega

Para aceitar uma entrega, responda com um status abaixo de 400, como 200 ou 202. O Meshy aguarda cerca de 25 segundos pela resposta, então armazene a entrega e responda primeiro. Faça o trabalho mais demorado depois disso, como baixar o modelo.

Um status 400 ou acima, ou a ausência de resposta, conta como uma entrega falha. O Meshy tenta novamente com esperas cada vez maiores entre as tentativas, até 4 vezes para uma atualização IN_PROGRESS e até 9 vezes para um status final. Se 20 atualizações seguidas falharem em todas as tentativas, o Meshy pode desativar o webhook. Para reativá-lo, edite-o na página de Webhooks e selecione Active.

Escreva seu código para estes casos:

  • As entregas podem chegar fora de ordem. Uma entrega IN_PROGRESS pode chegar depois da final, então não deixe que ela substitua um status final.
  • A mesma atualização pode chegar mais de uma vez. Processe cada par de id e status uma única vez.
  • Qualquer pessoa que souber sua URL pode enviar uma requisição a ela. Compare X-MESHY-API-WEBHOOK-SECRET-KEY com a sua cópia do secret e rejeite uma requisição que não corresponda.

Se a entrega final de uma tarefa não chegou depois de aproximadamente o dobro do tempo típico da tarefa, obtenha a tarefa pelo seu endpoint GET. Para tempos típicos e quanto esperar, veja Ciclo de vida da tarefa.


Testar no seu computador

O Meshy entrega apenas para uma URL pública https://, então ele não consegue alcançar diretamente um servidor no seu computador. Para testar código no seu computador, encaminhe uma URL pública para ele com um proxy de webhook. Estes passos usam o smee.io, e qualquer serviço de proxy de webhook funciona da mesma forma.

  1. Abra o smee.io e clique em Start a new channel. Copie a URL em Webhook Proxy URL.

  2. Se você ainda não tem o cliente smee, instale-o:

    npm install --global smee-client
    
  3. Encaminhe o canal para o seu servidor. Substitua WEBHOOK_PROXY_URL pela sua URL de proxy de webhook:

    smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000
    

    A saída será parecida com esta, em que WEBHOOK_PROXY_URL é a sua URL de proxy de webhook:

    Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
    Connected WEBHOOK_PROXY_URL
    

    Mantenha-o em execução enquanto testa. Para parar o encaminhamento, pressione Ctrl+C. Seu servidor recebe as entregas na porta 3000 no caminho /webhook, então configure seu código para escutar ali.

  4. Na página de Webhooks, crie um webhook com a URL de proxy de webhook como sua Payload URL.


Payload de entrega

O Meshy envia uma entrega enquanto uma tarefa está IN_PROGRESS, e outra quando a tarefa chega a um status final. Uma tarefa pode chegar ao seu status final sem uma entrega IN_PROGRESS.

Cada entrega é um POST para a sua URL de payload com estes cabeçalhos:

CabeçalhoValor
X-MESHY-API-WEBHOOK-SECRET-KEYO secret do webhook
X-MESHY-API-WEBHOOK-USER-IDO ID do usuário do Meshy dono do webhook
Meshy-Webhook-Versionv1, o formato do corpo
Content-Typeapplication/json
User-AgentMeshyAPIWebhook/1.0.0

O corpo JSON é o objeto da tarefa. É o mesmo objeto que o endpoint GET da tarefa retorna, exceto progress. Uma entrega envia progress como um destes valores:

  • 50 enquanto a tarefa está IN_PROGRESS
  • 100 quando a tarefa é bem-sucedida
  • 0 quando a tarefa falha ou é cancelada

Para os campos de cada objeto de tarefa, com um exemplo, veja as seções a seguir: