Ciclo de vida da tarefa
Saiba como uma tarefa evolui desde a solicitação até o resultado, quanto tempo isso costuma levar e por quanto tempo seu código deve aguardar.
Como uma tarefa é executada
Uma solicitação de criação retorna um ID de tarefa sem aguardar a execução da tarefa. A tarefa então é executada em segundo plano, e você pode acompanhá-la de três maneiras: fazer polling do endpoint GET dela, abrir o endpoint de stream dela, ou receber um webhook.
PENDING. Um worker a captura e ela passa para IN_PROGRESS, onde permanece a maior parte do tempo. Ela termina em SUCCEEDED ou FAILED, e um status final nunca muda.PENDINGIN_PROGRESSSUCCEEDEDFAILEDA 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.
| Status | O que seu código deve fazer |
|---|---|
PENDING | Continue aguardando. |
IN_PROGRESS | Acompanhe o progress: a porcentagem do trabalho concluído, de 0 a 100. |
SUCCEEDED | Baixe o resultado. A Meshy mantém os arquivos por um tempo limitado. Veja Retenção de recursos. |
FAILED | Leia task_error, depois corrija a entrada ou crie uma nova tarefa. Veja Erros. |
CANCELED | Pare de aguardar. A tarefa não produzirá um resultado. Somente tarefas do Creative Lab usam esse status. |
SUCCEEDED, FAILED e CANCELED são finais. Depois que uma tarefa atinge um desses status, ele nunca mais muda.
No seu código, isso se parece com o seguinte:
Solicitação: POST/image-to-3d
Resposta: 202{ "result": "<task_id>" }tarefa criada
- Repita a cada poucos segundos
Solicitação: GET/image-to-3d/<task_id>
Resposta: 200{ "status": "IN_PROGRESS","progress": 45 }Retry-After: 5
Solicitação: GET/image-to-3d/<task_id>
Resposta: 200{ "status": "SUCCEEDED","model_urls": { "glb": "…" } }
GET dela mais tarde com o mesmo ID de tarefa.Tempos de processamento
As tabelas a seguir mostram tempos medianos no tráfego de produção da API em setembro de 2026.
Um tempo é contado desde a criação da tarefa até o status final. Quase todo esse tempo é processamento, pois uma tarefa geralmente permanece 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.
Esses são tempos típicos, não tempos de conclusão garantidos. Durante períodos de alta demanda, algumas tarefas demoram mais e ainda assim são concluídas com sucesso. Para verificar o status da Meshy, veja a página de status. Não use esses tempos como timeouts no seu código. Para valores de timeout, veja Por quanto tempo aguardar.
Geração de 3D
| API | Configuração | meshy-7.1 (latest) | meshy-6 | meshy-6-lite | meshy-t2 |
|---|---|---|---|---|---|
| Text to 3D (Preview) | Somente malha | 75 s | 90 s | 45 s | 10 s |
| Imagem para 3D | Somente malha | 75 s | 90 s | 40 s | 4 s |
| Malha com texturas de 2K | 2 min | 3 min | 75 s | 60 s | |
| Malha com texturas de 4K | 2,5 min | 3,5 min | Não suportado | 80 s | |
| Malha com texturas de 8K | 3,5 min | 4 min | Não suportado | 2,5 min | |
| Multi-imagem para 3D | Somente malha | 65 s | 2 min | 30 s | Não suportado |
| Malha com texturas de 2K | 2,5 min | 3,5 min | 85 s | Não suportado | |
| Malha com texturas de 4K | 3 min | 4 min | Não suportado | Não suportado | |
| Malha com texturas de 8K | 3,5 min | 4,5 min | Não suportado | Não suportado |
Para Imagem para 3D e Multi-imagem para 3D, "Somente 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
| API | Resolução da textura | Tempo típico |
|---|---|---|
| Text to 3D (Refine) | 2K ou 4K | 80 s |
| 8K | 3,5 min | |
| Retexturizar | 2K | 55 s |
| 4K | 90 s | |
| 8K | 2,5 min |
Geração de imagem
| API | nano-banana | nano-banana-2 | nano-banana-pro | Modelos GPT Image |
|---|---|---|---|---|
| Texto para imagem | 20 s | 15 s | 25 s | 20 a 35 s |
| Imagem para imagem | 40 s | 20 s | 30 s | 20 a 40 s |
Rigging e Animação
| API | Configuração | Tempo típico |
|---|---|---|
| Auto-Rigging | Rigging automático | 40 s |
| Animação | Por solicitação | 15 s |
| Text to Motion | mode prime | 15 s |
mode swift | 10 s |
Pós-processamento
| API | Tempo típico |
|---|---|
| Remesh | 2 min |
| Desdobramento UV | 35 s |
| Converter | 7 s |
| Redimensionar | 15 s |
Impressão 3D
| API | Configuração | Tempo típico |
|---|---|---|
| Analisar imprimibilidade | Somente verificações de malha | 1 s |
| Verificações de malha e de paredes finas | 10 s | |
| Multi-Color | Por solicitação | 30 s |
| Reparar imprimibilidade | Somente reparo de malha | 10 s |
| Verificação de paredes finas, paredes mantidas | 20 s | |
| Verificação de paredes finas, paredes espessadas | 100 s | |
| Auto Split | Por solicitação | 70 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.
Por quanto tempo aguardar
A tarefa continua em execução mesmo se o seu código parar de aguardar. Se a sua solicitação atingir o timeout, sua conexão cair, ou seu stream fechar, a tarefa não falha e não é cancelada.
- Aguarde pelo menos 60 minutos, contados a partir do
created_atda tarefa, antes de parar de aguardar. Se você parar antes disso, pode perder uma tarefa que é concluída com sucesso mais tarde. Isso acontece principalmente durante períodos de alta demanda. - Mantenha 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-a novamente mais tarde. Se continuar assim, entre em contato com o suporte.
- Somente
FAILEDsignifica que a tarefa falhou. A Meshy reembolsa tarefas com falha automaticamente.
Use estes valores no seu código:
| Configuração | Valor 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 MB | 120 segundos. A Meshy baixa o arquivo antes de responder. |
Timeout da solicitação de status (GET) | 30 segundos |
| Intervalo de polling | O cabeçalho Retry-After, ou 5 segundos se estiver ausente. Os pollings contam para o 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 tarefa | Pelo menos 60 minutos a partir de created_at. Não reinicie essa contagem ao reconectar um stream. |
| Stream | Um stream pode fechar antes que a tarefa termine. Se fechar sem um status final, reconecte 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 a partir do endpoint GET dela.