Erros

Neste guia, falaremos sobre o que acontece quando algo dá errado enquanto você trabalha com a Meshy API.

Erros de solicitação

Estes erros são retornados imediatamente quando sua solicitação de API é rejeitada. Verifique o código de status HTTP e o campo message para entender o que deu errado.

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

Erros de tarefa

Estes erros ocorrem depois que uma tarefa foi criada e está 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 informa a categoria ampla da falha. Use-o para decidir sua estratégia de nova tentativa.

Códigos de erro

Quando o campo code está presente, ele 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 elemento que é geometricamente complexo demais para o modelo de geração 3D processar.

Exemplos comuns incluem:

• Pilhas densas de objetos pequenos (por exemplo, uma caixa cheia de frutas, uma pilha de livros)
• Padrões repetitivos intrincados (por exemplo, estruturas treliçadas, 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 em uma imagem em vez de um único elemento

Exemplos de entradas que provavelmente são complexas demais:

Resolução:

1. Use um único objeto por imagem. O modelo funciona melhor com um elemento claro. Não inclua vários objetos separados na mesma imagem ou prompt.
2. Simplifique seu elemento. Reduza o nível de detalhe. Por exemplo, um vaso simples em vez de um vaso cheio de dezenas de flores.
3. Evite prompts em nível de cena. Edifícios inteiros, quarteirões, interiores cheios de móveis ou paisagens provavelmente excederão a capacidade do modelo. Em vez disso, concentre-se em um único objeto.
4. Evite estruturas repetitivas densas. Elementos como andaimes, malhas de arame, padrões treliçados ou pilhas de muitos itens pequenos são acionadores comuns.

model_missing_uv

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

Resolução:

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

• Se você precisa preservar o layout UV original do seu modelo (por exemplo, posicionamento personalizado de costuras para mapeamento preciso de textura): seu modelo deve ter coordenadas UV válidas. Verifique se as UVs existem no editor de UV do seu software 3D antes de enviar. Observe que arquivos STL não podem armazenar dados UV, então use GLB, FBX ou OBJ em vez disso.
• Se você não precisa de controle UV específico (ou não tem certeza): omita enable_original_uv ou defina-o como false. O sistema gerará automaticamente um layout UV para o seu modelo. As UVs geradas automaticamente são otimizadas para cobertura, mas você não terá controle sobre onde as costuras da textura são posicionadas.

model_insufficient_uv

Este erro ocorre quando um modelo tem coordenadas UV, mas a cobertura UV é pequena demais para uma texturização de qualidade. Isso geralmente acontece com modelos exportados de ferramentas 3D que geram UVs de placeholder ou colapsados sem uma abertura adequada.

Resolução:

• Se você precisar preservar seu layout UV original: refaça a abertura dos UVs do modelo no seu software 3D. Garanta que as ilhas UV estejam distribuídas corretamente pelo espaço UV, em vez de colapsadas em uma área pequena.
• Se você não precisar de controle UV específico: omita enable_original_uv ou defina-o como false. O sistema gerará automaticamente um novo layout UV. A desvantagem é que você perde o posicionamento original das costuras, mas os UVs gerados automaticamente terão cobertura adequada para texturização.

invalid_input

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

Causas comuns incluem:

• Arquivos de modelo vazios ou corrompidos
• Variações de formato de arquivo não compatíveis (por exemplo, arquivos FBX ASCII, GLB comprimido com meshopt)
• Nenhum objeto 3D válido encontrado no modelo enviado (por exemplo, o arquivo contém apenas armatures, câmeras ou luzes)
• Conteúdo que não passa nos filtros de segurança

Resolução: Verifique o campo message para detalhes sobre o que deu errado. Verifique se seus arquivos de entrada e parâmetros correspondem aos requisitos do endpoint.

moderation_blocked

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

Resolução:

• Reformule seu prompt de texto para remover descrições sugestivas ou sensíveis.
• Ajuste as imagens de referência se elas retratarem 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. Isso pode acontecer devido a uma alta carga do sistema ou porque a entrada é complexa demais para ser processada dentro do limite de tempo.

Resolução:

1. Tente a solicitação novamente. Timeouts geralmente são transitórios, e uma nova tentativa pode ser bem-sucedida.
2. Simplifique sua entrada. Se as novas tentativas continuarem falhando, sua entrada pode ser complexa demais. Tente reduzir o nível de detalhe na sua imagem ou prompt. Consulte image_too_complex para orientações sobre quais 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 a solicitação novamente.
2. Experimente um formato de saída diferente. Se um formato específico continuar falhando, mude para outro formato que atenda às suas necessidades.

Melhores práticas

1. Implemente lógica de novas tentativas. Para erros timeout e service_unavailable, implemente lógica de novas tentativas com backoff exponencial.
2. Registre IDs de tarefas. Sempre registre o ID da tarefa para fins de depuração. Inclua-o ao entrar em contato com o suporte.
3. Valide as entradas. Certifique-se de que suas imagens e modelos de entrada atendam aos requisitos de formato antes do envio.