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

Ciclo de vida da tarefa

Saiba como uma tarefa evolui desde a solicitação até o resultado, quanto tempo ela costuma levar e quanto tempo seu código deve esperar por ela.


Como uma tarefa é executada

Uma solicitação de criação retorna um ID de tarefa sem esperar a tarefa ser executada. A tarefa então é executada em segundo plano, e você a acompanha de uma de três formas: fazendo polling do seu endpoint GET, abrindo seu endpoint de stream ou recebendo um webhook.

Uma solicitação de criação inicia uma tarefa em PENDING. Um worker a pega e ela passa para IN_PROGRESS, onde passa a maior parte do tempo. Ela termina em SUCCEEDED ou FAILED, e um status final nunca muda.
Solicitação de criação
PENDING
Aguardando na fila
IN_PROGRESS
Gerando o resultado
SUCCEEDED
Baixe o resultado
FAILED
Créditos reembolsados

A tarefa registra cada etapa em seus campos created_at, started_at e finished_at.

A tabela a seguir mostra o que seu código deve fazer em cada status.

StatusO que seu código deve fazer
PENDINGContinue esperando.
IN_PROGRESSAcompanhe progress: a porcentagem do trabalho concluído, de 0 a 100.
SUCCEEDEDBaixe o resultado. A Meshy mantém os arquivos por um tempo limitado. Veja Retenção de recursos.
FAILEDLeia task_error e, em seguida, corrija a entrada ou crie uma nova tarefa. Veja Erros.
CANCELEDPare de esperar. A tarefa não produzirá um resultado. Apenas tarefas do Creative Lab usam esse status.

SUCCEEDED, FAILED e CANCELED são finais. Depois que uma tarefa atinge um desses status, ele nunca muda novamente.

No seu código, isso se parece assim:

Crie uma tarefa e, em seguida, faça polling dela até que termine.
  1. Solicitação: POST/image-to-3d

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

  3. Repita a cada poucos segundos
    1. Solicitação: GET/image-to-3d/<task_id>

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

  4. Solicitação: GET/image-to-3d/<task_id>

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

Se seu aplicativo parar de esperar, a tarefa continua em execução. Faça um GET dela depois, com o mesmo ID de tarefa.

Tempos de processamento

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

Um tempo é contado da criação da tarefa até o status final. Quase todo esse tempo é processamento, pois uma tarefa geralmente fica em PENDING por apenas alguns segundos. Quando a fila está ocupada, as tarefas podem esperar mais antes de começar, e tarefas em planos com prioridade mais alta geralmente começam mais cedo.

Tempos abaixo de 2 minutos estão em segundos (s), e 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:

  • Mapas PBR (enable_pbr) adicionam de 30 a 60 segundos.
  • Geometria ultra (geometry_resolution: "2k" ou "4k") adiciona até 1 minuto.
  • Com as mesmas configurações, imagens de entrada mais complexas levam mais tempo.

Texturização

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

Geração de imagem

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 solicitação15 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 solicitação30 s
Reparar imprimibilidadeApenas reparo de malha10 s
Verificação de paredes finas, paredes mantidas20 s
Verificação de paredes finas, paredes espessadas100 s
Auto SplitPeças de cor sólida70 s
Peças texturizadas (keep_texture: true)170 s

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


Quanto tempo esperar

A tarefa continua em execução mesmo se seu código parar de esperar. Se sua solicitação atingir o timeout, sua conexão cair ou seu stream fechar, a tarefa não falha e não é cancelada.

  • Espere pelo menos 60 minutos, contados a partir do created_at da tarefa, antes de parar de esperar. Se você parar antes disso, pode perder uma tarefa que tenha sucesso mais tarde. Isso acontece principalmente durante períodos de alta demanda.
  • Guarde o ID da tarefa. Você pode obter a tarefa novamente a qualquer momento. Se ela ainda não estiver finalizada após 60 minutos, verifique novamente mais tarde. Se continuar assim, entre em contato com o suporte.
  • Apenas FAILED significa que a tarefa falhou. A Meshy reembolsa tarefas com falha automaticamente.

Use estes valores no seu código:

ConfiguraçãoValor recomendado
Timeout da solicitação de criação (POST)60 segundos
Timeout da solicitação de criação (POST) com um arquivo model_url acima de 100 MB120 segundos. A Meshy baixa o arquivo antes de responder.
Timeout da solicitação de status (GET)30 segundos
Intervalo de pollingO cabeçalho Retry-After, ou 5 segundos se estiver ausente. Os pollings contam para seu limite de taxa.
Solicitação de status com falha (timeout, 429 ou 5xx)Tente novamente no próximo polling. Isso não significa que a tarefa falhou.
Espera total por tarefaPelo menos 60 minutos a partir de created_at. Não reinicie essa contagem ao reconectar um stream.
StreamUm stream pode fechar antes que a tarefa termine. Se ele fechar sem um status final, reconecte-se ou mude para polling.

Para muitas tarefas ao mesmo tempo, use webhooks em vez de fazer polling de cada uma. Se o evento final de uma tarefa não chegar após cerca do dobro do seu tempo típico, obtenha a tarefa pelo seu endpoint GET.