Ciclo de vida da tarefa

Saiba como uma tarefa evolui desde o pedido até ao resultado, quanto tempo demora normalmente e quanto tempo o seu código deve esperar por ela.

Como uma tarefa é executada

Um pedido de criação devolve um ID de tarefa sem esperar que a tarefa seja executada. A tarefa é então executada em segundo plano, e pode acompanhá-la de uma de três formas: fazer polling ao seu endpoint GET, abrir o seu endpoint de stream, ou receber um webhook.

A tarefa regista cada etapa nos seus campos created_at, started_at e finished_at.

A tabela seguinte mostra o que o seu código deve fazer em cada estado.

SUCCEEDED, FAILED e CANCELED são finais. Depois de uma tarefa atingir um destes estados, o seu estado nunca mais muda.

A partir do seu código, é assim:

Tempos de processamento

As tabelas seguintes mostram tempos medianos no tráfego de produção da API em setembro de 2026.

Um tempo decorre desde a criação da tarefa até ao estado final. Quase todo esse tempo é processamento, porque uma tarefa normalmente permanece em PENDING apenas durante alguns segundos. Quando a fila está ocupada, as tarefas podem esperar mais tempo antes de iniciarem, e as tarefas em planos com uma prioridade mais elevada normalmente iniciam mais depressa.

Os tempos inferiores a 2 minutos estão em segundos (s), e os tempos mais longos estão em minutos (min). Não suportado significa que a API não oferece essa opção com esse modelo.

Geração 3D

Para Imagem para 3D e Multi-imagem para 3D, "Apenas malha" significa should_texture: false. Estas opções e entradas alteram o tempo:

• Os mapas PBR (enable_pbr) acrescentam 30 a 60 segundos.
• A geometria ultra (geometry_resolution: "2k" ou "4k") acrescenta até 1 minuto.
• Com as mesmas definições, imagens de entrada mais complexas demoram mais tempo.

Texturização

Geração de imagens

Rigging e Animação

Pós-processamento

Impressão 3D

Na v2, Reparar imprimibilidade e Analisar imprimibilidade executam sempre a verificação de paredes finas. Na v1, executam-na quando envia um tipo de impressora ou um tamanho de impressão.

Quanto tempo esperar

A tarefa continua a ser executada mesmo que o seu código deixe de esperar. Se o seu pedido atingir o timeout, a sua ligação cair ou o seu stream fechar, a tarefa não falha nem é cancelada.

• Espere pelo menos 60 minutos, contados a partir do created_at da tarefa, antes de deixar de esperar. Se parar mais cedo, pode perder uma tarefa que seja bem-sucedida mais tarde. Isto acontece sobretudo durante períodos de maior procura.
• Guarde o ID da tarefa. Pode obter a tarefa novamente a qualquer momento. Se ainda não estiver num estado final após 60 minutos, verifique-a novamente mais tarde. Se se mantiver assim, contacte o suporte.
• Apenas FAILED significa que a tarefa falhou. A Meshy reembolsa automaticamente as tarefas falhadas.

Use estes valores no seu código:

Para muitas tarefas em simultâneo, use webhooks em vez de fazer polling a cada uma. Se o evento final de uma tarefa não tiver chegado após aproximadamente o dobro do seu tempo típico, obtenha a tarefa a partir do seu endpoint GET.