Erros

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

Erros de Solicitação

Esses 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

Esses 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 informa a categoria geral 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 prompt descreve um assunto que é muito geometricamente complexo 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 em uma imagem em vez de um único assunto

Exemplos de entradas que provavelmente são muito complexas:

Resolução:

1. Use um único objeto por imagem. O modelo funciona melhor com um assunto claro. Não inclua múltiplos objetos separados na mesma imagem ou prompt.
2. Simplifique seu assunto. 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 excedem a capacidade do modelo. Foque em um único objeto.
4. Evite estruturas repetitivas densas. Assuntos como andaimes, malhas de arame, padrões de treliça ou pilhas de muitos itens pequenos são gatilhos comuns.

model_missing_uv

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

Resolução:

A correção correta 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, colocação personalizada de costuras para mapeamento de textura preciso): seu modelo deve ter coordenadas UV válidas. Verifique se as UVs existem no editor UV do seu software 3D antes de fazer o upload. Note 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 específico sobre UVs (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 colocadas.

model_insufficient_uv

Este erro ocorre quando um modelo possui coordenadas UV, mas a cobertura UV é muito pequena para uma texturização de qualidade. Isso geralmente acontece com modelos exportados de ferramentas 3D que geram UVs de espaço reservado ou colapsados sem um desdobramento adequado.

Resolução:

• Se você precisa preservar seu layout UV original: redesenhe as UVs do modelo no seu software 3D. Certifique-se de que as ilhas UV estejam devidamente distribuídas pelo espaço UV em vez de colapsadas em uma área pequena.
• Se você não precisa de controle específico sobre UVs: omita enable_original_uv ou defina como false. O sistema gerará automaticamente um novo layout UV. A desvantagem é que você perde 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 padrão quando a validação da entrada falha, 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 suportadas (por exemplo, arquivos FBX ASCII, GLB comprimidos com meshopt)
• Nenhum objeto 3D válido encontrado no modelo enviado (por exemplo, o arquivo contém apenas armaduras, 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. Confirme 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 é muito complexa para ser processada dentro do limite de tempo.

Resolução:

1. Tente novamente a solicitação. Timeouts são frequentemente transitórios e uma nova tentativa pode ser bem-sucedida.
2. Simplifique sua entrada. Se as tentativas continuarem falhando, sua entrada pode ser muito complexa. Tente reduzir o nível de detalhe na sua imagem ou prompt. Veja 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 novamente a solicitação.
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 nova tentativa. Para erros de timeout e service_unavailable, implemente lógica de nova tentativa com recuo 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.