Erros

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

Erros do 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. Use-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 imagens de referência são rejeitados pelos filtros de segurança da 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 se estas representarem conteúdo que possa acionar os filtros de segurança.

timeout

Este erro significa que o tempo de processamento da sua tarefa excedeu o limite permitido. Isto pode acontecer devido a uma carga elevada do sistema ou porque a entrada é demasiado complexa para ser processada dentro do limite de tempo.

Resolução:

1. Tente novamente o pedido. Os timeouts são muitas vezes transitórios e uma nova tentativa pode ter sucesso.
2. Simplifique a sua entrada. Se as novas tentativas continuarem a falhar, a sua entrada pode ser demasiado complexa. Tente reduzir o nível de detalhe na sua imagem ou prompt. Veja image_too_complex para orientação sobre que tipos de entradas são mais difíceis de processar.

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 a etapa de conversão falhou.

Resolução:

1. Tente novamente a solicitação.
2. Experimente um formato de saída diferente. Se um formato específico continuar a falhar, mude para outro formato que atenda às suas necessidades.

Melhores Práticas

1. Implemente lógica de repetição. Para erros de timeout e service_unavailable, implemente lógica de repetição com recuo exponencial.
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 as entradas. Certifique-se de que as suas imagens e modelos de entrada atendem aos requisitos de formato antes da submissão.