Erros

Neste guia, vamos falar sobre o que acontece quando algo corre mal enquanto trabalha com a Meshy API.

Erros de Pedido

Estes erros são devolvidos imediatamente quando o seu pedido de API é rejeitado. Verifique o código de estado HTTP e o campo message para perceber o que correu mal.

{
  "message": "Invalid model file extension: .3dm"
}

Erros de Tarefa

Estes erros ocorrem após uma tarefa ter sido criada e estar em processamento. Verifique o objeto task_error na resposta da tarefa para obter detalhes sobre o erro.

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "FAILED",
  "task_error": {
    "type": "invalid_input",
    "code": "image_too_complex",
    "message": "The uploaded image is too complex for 3D generation.",
    "doc_url": "https://docs.meshy.ai/en/api/errors#image-too-complex"
  }
}

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "FAILED",
  "task_error": {
    "type": "server_error",
    "message": "An internal error occurred. Please retry."
  }
}

Tipos de Erro

O campo type indica a categoria geral da falha. Utilize-o para decidir a sua estratégia de repetição.

Códigos de Erro

Quando o campo code está presente, identifica um problema específico e acionável. Abaixo está a referência completa para cada código de erro.

image_too_complex

Este erro ocorre quando a imagem de entrada ou prompt descreve um sujeito que é demasiado complexo geometricamente para o modelo de geração 3D processar.

Exemplos comuns incluem:

• Pilhas densas de pequenos objetos (por exemplo, uma caixa cheia de frutas, uma pilha de livros)
• Padrões repetitivos intrincados (por exemplo, estruturas de treliça, andaimes, malhas de arame)
• Estruturas de edifícios complexas (por exemplo, edifícios de vários andares com muitas janelas e varandas)
• Múltiplos objetos distintos numa só imagem em vez de um único sujeito

Exemplos de entradas que são provavelmente demasiado complexas:

Resolução:

1. Use um único objeto por imagem. O modelo funciona melhor com um sujeito claro. Não inclua múltiplos objetos separados na mesma imagem ou prompt.
2. Simplifique o seu sujeito. Reduza o nível de detalhe. Por exemplo, um vaso simples em vez de um vaso cheio de dezenas de flores.
3. Evite prompts ao nível da cena. Edifícios inteiros, quarteirões, interiores cheios de mobília ou paisagens provavelmente excedem a capacidade do modelo. Foque-se num único objeto.
4. Evite estruturas repetitivas densas. Sujeitos como andaimes, malhas de arame, padrões de treliça ou pilhas de muitos pequenos itens são gatilhos comuns.

model_missing_uv

Este erro ocorre quando carrega um modelo para texturização com enable_original_uv definido como true, mas o modelo não tem coordenadas UV. As coordenadas UV definem como uma textura 2D se aplica à superfície 3D do seu modelo.

Resolução:

A correção adequada depende do motivo pelo qual definiu enable_original_uv como true:

• Se precisar de preservar a disposição UV original do seu modelo (por exemplo, colocação personalizada de costuras para mapeamento de textura preciso): o seu modelo deve ter coordenadas UV válidas. Verifique se as UVs existem no editor UV do seu software 3D antes de carregar. Note que os ficheiros STL não podem armazenar dados UV, por isso use GLB, FBX ou OBJ em vez disso.
• Se não precisar de controlo específico sobre as UVs (ou se não tiver a certeza): omita enable_original_uv ou defina-o como false. O sistema irá gerar automaticamente uma disposição UV para o seu modelo. As UVs geradas automaticamente são otimizadas para cobertura, mas não terá controlo sobre onde as costuras de textura são colocadas.

model_insufficient_uv

Este erro ocorre quando um modelo tem coordenadas UV, mas a cobertura UV é demasiado pequena para uma texturização de qualidade. Isto acontece frequentemente com modelos exportados de ferramentas 3D que geram UVs de marcador de posição ou colapsados sem uma descompactação adequada.

Resolução:

• Se precisar de preservar a sua disposição UV original: descompacte novamente as UVs do modelo no seu software 3D. Certifique-se de que as ilhas UV estão devidamente distribuídas pelo espaço UV em vez de colapsadas numa área pequena.
• Se não precisar de controlo específico sobre as UVs: omita enable_original_uv ou defina-o como false. O sistema irá gerar automaticamente uma nova disposição UV. A desvantagem é que perde a colocação original das costuras, mas as UVs geradas automaticamente terão uma cobertura adequada para texturização.

model_missing_texture

Este erro ocorre quando o modelo de entrada de uma tarefa de Multi-Color Print não tem informação de cor que o conversor consiga separar em cores de impressão. Uma 3MF multicor é construída a partir das cores do modelo, pelo que uma malha branca simples — por exemplo, uma pré-visualização de Texto para 3D ou Imagem para 3D que nunca foi texturizada, ou um resultado reparado / dividido automaticamente — não tem nada com que trabalhar.

O que conta como fonte de cor depende do style solicitado:

• realistic amostra a textura de cor base através das UVs do modelo, pelo que requer uma única textura de cor base com coordenadas UV em todas as partes da malha.
• cartoon achata as cores por face e aceita uma textura de cor base em qualquer parte ou cores por vértice (COLOR_0).

Um modelo sem textura de cor base nem cores de vértice é rejeitado em ambos os estilos; com cartoon seria de outro modo "bem-sucedido" como uma impressão de cor única.

A maioria dos pedidos é recusada antes de a tarefa ser criada (400 Bad Request com a mesma explicação), pelo que normalmente só verá este código quando a entrada não pôde ser inspecionada antecipadamente — por exemplo, um carregamento .fbx é verificado assim que a tarefa o normalizou.

Resolução:

• Texturize o modelo primeiro. Execute uma tarefa de Retexturizar sobre ele, ou gere-o com a texturização ativada (uma tarefa refine de Texto para 3D, ou uma tarefa de Imagem para 3D com should_texture: true), e passe essa tarefa como input_task_id.
• Modelos com cores por vértice (digitalizações por fotogrametria, malhas pintadas à mão): solicite style: "cartoon", que lê COLOR_0.
• Modelos parcialmente texturizados ou com múltiplas texturas em realistic: cada parte da malha precisa de UVs e da mesma textura de cor base única. Texturize as partes restantes ou junte as texturas num único atlas, ou mude para style: "cartoon".

invalid_input

Este é o código de erro de recurso quando a validação do input falha, mas não se aplica nenhum código mais específico. O campo message contém a razão específica para a falha.

Causas comuns incluem:

• Ficheiros de modelo vazios ou corrompidos
• Variações de formatos de ficheiro não suportadas (por exemplo, ficheiros FBX ASCII, GLB comprimidos com meshopt)
• Nenhum objeto 3D válido encontrado no modelo carregado (por exemplo, o ficheiro contém apenas armaduras, câmaras ou luzes)
• Conteúdo que não passa nos filtros de segurança

Resolução: Verifique o campo message para obter detalhes sobre o que correu mal. Confirme que os seus ficheiros de input e parâmetros correspondem aos requisitos do endpoint.

moderation_blocked

Este erro ocorre quando o seu prompt ou as imagens de referência são rejeitados pelos filtros de segurança de IA. O filtro avalia tanto o prompt de texto como quaisquer imagens de referência em conjunto.

Resolução:

• Reformule o seu prompt de texto para remover descrições sugestivas ou sensíveis.
• Ajuste as imagens de referência caso representem conteúdo que possa acionar os filtros de segurança.

moderation_unavailable

Este erro ocorre quando a moderation de conteúdo esteve temporariamente indisponível, pelo que a tarefa falhou em vez de ser executada sem a verificação. Não há nada de errado com o seu conteúdo. O seu type é server_error.

Resolução: Crie a tarefa novamente.

timeout

Este erro significa que a tarefa excedeu um limite de tempo definido no servidor, seja para processamento ou para espera na fila, pelo que a tarefa falhou e os seus créditos foram reembolsados. Isto pode acontecer devido a uma carga elevada do sistema ou porque o input é demasiado complexo para ser processado dentro do limite de tempo.

Isto é diferente de um timeout no seu próprio código. Se o seu cliente deixou de esperar, a tarefa continua em execução; consulte Ciclo de Vida da Tarefa.

Resolução:

1. Crie a tarefa novamente. Os timeouts são muitas vezes transitórios e uma nova tarefa pode ser bem-sucedida.
2. Simplifique o seu input. Se as novas tentativas continuarem a falhar, o seu input pode ser demasiado complexo. Tente reduzir o nível de detalhe na sua imagem ou prompt. Consulte image_too_complex para orientações sobre que tipos de inputs são mais difíceis de processar.

queue_timeout

Este erro significa que a tarefa esperou demasiado tempo na fila sem ser iniciada, pelo que falhou e quaisquer créditos cobrados por ela foram devolvidos. A sua entrada não foi a causa. O seu type é timeout.

Resolução: Crie a tarefa novamente.

format_conversion_failed

Este erro ocorre quando o modelo 3D gerado não pôde ser convertido para o formato de saída solicitado. O modelo foi gerado com sucesso, mas o passo de conversão falhou.

Resolução:

1. Repita o pedido.
2. Experimente um formato de saída diferente. Se um formato específico continuar a falhar, mude para outro formato que satisfaça as suas necessidades.

Best Practices

1. Implemente lógica de nova tentativa. Quando uma tarefa falhar com um erro timeout, service_unavailable ou server_error, crie-a novamente com espera exponencial (exponential backoff). Se, em vez disso, for o seu próprio pedido que atingir o timeout, não crie uma nova tarefa: verifique primeiro a existente (consulte Task Lifecycle).
2. Registe os IDs das tarefas. Registe sempre o ID da tarefa para fins de depuração. Inclua-o ao contactar o suporte.
3. Valide os dados de entrada. Certifique-se de que as suas imagens e modelos de entrada cumprem os requisitos de formato antes do envio.
4. Chame a API a partir do seu servidor. Código que é executado num browser exporia a sua chave de API a qualquer pessoa que abra a página.