Erros

Neste guia, falaremos 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 compreender o que correu mal.

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

Erros de tarefa

Estes erros ocorrem depois de uma tarefa ter sido criada e estar em processamento. Verifique o objeto task_error na resposta da tarefa para obter detalhes do 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 nova tentativa.

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 o 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 fruta, uma pilha de livros)
• Padrões repetitivos intrincados (por exemplo, estruturas reticuladas, andaimes, malhas de arame)
• Estruturas de edifícios complexas (por exemplo, edifícios de vários andares com muitas janelas e varandas)
• Vários objetos distintos numa imagem em vez de um único sujeito

Exemplos de entradas que provavelmente são demasiado complexas:

Resolução:

1. Utilize um único objeto por imagem. O modelo funciona melhor com um sujeito claro. Não inclua vários objetos separados na mesma imagem ou prompt.
2. Simplifique o seu sujeito. Reduza o nível de detalhe. Por exemplo, uma jarra simples em vez de uma jarra cheia com dezenas de flores.
3. Evite prompts ao nível da cena. Edifícios inteiros, quarteirões, interiores cheios de mobiliário ou paisagens provavelmente excedem a capacidade do modelo. Em vez disso, foque-se num único objeto.
4. Evite estruturas repetitivas densas. Sujeitos como andaimes, malhas de arame, padrões reticulados ou pilhas de muitos itens pequenos são gatilhos comuns.

model_missing_uv

Este erro ocorre quando carrega um modelo para aplicação de texturas com enable_original_uv definido como true, mas o modelo não tem coordenadas UV. As coordenadas UV definem como uma textura 2D envolve a 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, posicionamento personalizado de costuras para mapeamento preciso de textura): o seu modelo tem de ter coordenadas UV válidas. Verifique se existem UVs no editor UV do seu software 3D antes de carregar. Tenha em atenção que os ficheiros STL não conseguem armazenar dados UV, por isso utilize GLB, FBX ou OBJ.
• Se não precisar de controlo UV específico (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. Os UVs gerados automaticamente são otimizados para cobertura, mas não terá controlo sobre onde são colocadas as costuras da textura.

model_insufficient_uv

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

Resolução:

• Se precisar de preservar a sua disposição UV original: volte a desembrulhar 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 pequena área.
• Se não precisar de controlo UV específico: omita enable_original_uv ou defina-o como false. O sistema irá gerar automaticamente uma nova disposição UV. A contrapartida é perder o posicionamento original das costuras, mas as UVs geradas automaticamente terão cobertura adequada para texturização.

invalid_input

Este é o código de erro de recurso quando a entrada falha na validação, mas não se aplica nenhum código mais específico. O campo message contém o motivo específico da falha.

As causas comuns incluem:

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

Resolução: Consulte o campo message para obter detalhes sobre o que correu mal. Verifique se os seus ficheiros de entrada 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 da IA. O filtro avalia em conjunto tanto o prompt de texto como quaisquer imagens de referência.

Resolução:

• Reformule o seu prompt de texto para remover descrições sugestivas ou sensíveis.
• Ajuste as imagens de referência se 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 repetir o pedido. Os timeout são frequentemente transitórios e uma nova tentativa pode ser bem-sucedida.
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. Consulte image_too_complex para obter 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 êxito, mas o passo de conversão falhou.

Resolução:

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

Melhores práticas

1. Implemente lógica de repetição. Para erros timeout e service_unavailable, implemente lógica de repetição com recuo exponencial.
2. Registe IDs de 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 cumprem os requisitos de formato antes da submissão.