lowpoly será descontinuado a 30/10/2026. meshy-7 como modelo de geração 3D será descontinuado a 31/12/2026; como modelo de textura continua disponível. Mude de modelo antes destas datas para evitar erros nos pedidos. Ver todas as descontinuações

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 aguardar por ela.


Como é executada uma tarefa

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 três formas: fazer polling ao seu endpoint GET, abrir o seu endpoint de stream, ou receber um webhook.

Um pedido de criação inicia uma tarefa em PENDING. Um worker recebe-a e esta passa para IN_PROGRESS, onde passa a maior parte do tempo. Termina em SUCCEEDED ou FAILED, e um estado final nunca é alterado.
Pedido de criação
PENDING
Em espera na fila
IN_PROGRESS
A gerar o resultado
SUCCEEDED
Transferir o resultado
FAILED
Créditos reembolsados

A tarefa regista cada passo 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.

EstadoO que o seu código deve fazer
PENDINGContinuar à espera.
IN_PROGRESSAcompanhar progress: a percentagem do trabalho concluído, de 0 a 100.
SUCCEEDEDTransferir o resultado. A Meshy mantém os ficheiros durante um período limitado. Consulte Retenção de recursos.
FAILEDLer task_error e, em seguida, corrigir a entrada ou criar uma nova tarefa. Consulte Erros.
CANCELEDDeixar de esperar. A tarefa não produzirá um resultado. Apenas as tarefas do Creative Lab utilizam este estado.

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

No seu código, é assim:

Crie uma tarefa e, em seguida, faça polling até esta terminar.
  1. Pedido: POST/image-to-3d

  2. Resposta: 202{ "result": "<task_id>" }tarefa criada

  3. Repetir a cada poucos segundos
    1. Pedido: GET/image-to-3d/<task_id>

    2. Resposta: 200{ "status": "IN_PROGRESS","progress": 45 }Retry-After: 5

  4. Pedido: GET/image-to-3d/<task_id>

  5. Resposta: 200{ "status": "SUCCEEDED","model_urls": { "glb": "…" } }

Se a sua aplicação deixar de esperar, a tarefa continua em execução. Faça GET mais tarde com o mesmo ID de tarefa.

Tempos de processamento

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

Um tempo decorre desde a criação da tarefa até ao estado final. Quase todo esse tempo é de 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 começarem, e as tarefas em planos com prioridade mais elevada normalmente começam mais cedo.

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

APIConfiguraçãomeshy-7.1 (latest)meshy-6meshy-6-litemeshy-t2
Texto para 3D (Preview)Apenas malha75 s90 s45 s10 s
Imagem para 3DApenas malha75 s90 s40 s4 s
Malha com texturas 2K2 min3 min75 s60 s
Malha com texturas 4K2,5 min3,5 minNão suportado80 s
Malha com texturas 8K3,5 min4 minNão suportado2,5 min
Multi-imagem para 3DApenas malha65 s2 min30 sNão suportado
Malha com texturas 2K2,5 min3,5 min85 sNão suportado
Malha com texturas 4K3 min4 minNão suportadoNão suportado
Malha com texturas 8K3,5 min4,5 minNão suportadoNão suportado

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) adicionam 30 a 60 segundos.
  • A geometria Ultra (geometry_resolution: "2k" ou "4k") adiciona até 1 minuto.
  • Com as mesmas definições, imagens de entrada mais complexas demoram mais tempo.

Texturização

APIResolução de texturaTempo típico
Texto para 3D (Refine)2K ou 4K80 s
8K3,5 min
Retexturizar2K55 s
4K90 s
8K2,5 min

Geração de imagens

APInano-banananano-banana-2nano-banana-proModelos GPT Image
Texto para imagem20 s15 s25 s20 a 35 s
Imagem para imagem40 s20 s30 s20 a 40 s

Rigging e Animação

APIConfiguraçãoTempo típico
Auto-RiggingRigging automático40 s
AnimaçãoPor pedido15 s
Texto para Movimentomode prime15 s
mode swift10 s

Pós-processamento

APITempo típico
Remesh2 min
Desdobramento UV35 s
Converter7 s
Redimensionar15 s

Impressão 3D

APIConfiguraçãoTempo típico
Analisar imprimibilidadeApenas verificações de malha1 s
Verificações de malha e de paredes finas10 s
Multi-ColorPor pedido30 s
Reparar imprimibilidadeApenas reparação de malha10 s
Verificação de paredes finas, paredes mantidas20 s
Verificação de paredes finas, paredes espessadas100 s
Auto SplitPeças de cor lisa70 s
Peças texturizadas (keep_texture: true)170 s

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


Quanto tempo esperar

A tarefa continua em execução 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 voltar a obter a tarefa a qualquer momento. Se ainda não estiver num estado final após 60 minutos, verifique novamente mais tarde. Se continuar assim, contacte o suporte.
  • Apenas FAILED significa que a tarefa falhou. A Meshy reembolsa automaticamente as tarefas falhadas.

Utilize estes valores no seu código:

DefiniçãoValor recomendado
Timeout do pedido de criação (POST)60 segundos
Timeout do pedido de criação (POST) com um ficheiro model_url superior a 100 MB120 segundos. A Meshy transfere o ficheiro antes de responder.
Timeout do pedido de estado (GET)30 segundos
Intervalo de pollingO cabeçalho Retry-After, ou 5 segundos se estiver ausente. Os pedidos de polling contam para o seu limite de taxa.
Pedido de estado falhado (timeout, 429 ou 5xx)Tente novamente no polling seguinte. Não significa que a tarefa falhou.
Espera total por tarefaPelo menos 60 minutos a partir de created_at. Não reinicie esta contagem ao reconectar um stream.
StreamUm stream pode fechar antes de a tarefa terminar. Se fechar sem um estado final, reconecte ou mude para polling.

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