Erros

Descubra por que uma solicitação ou uma tarefa falhou, e o que fazer a seguir. Uma solicitação pode falhar imediatamente com um erro HTTP, e uma tarefa pode falhar mais tarde com um task_error.

Erros de requisição

Meshy retorna esses erros imediatamente, quando rejeita uma requisição. Para descobrir o que deu errado, verifique o código de status HTTP e o campo message.

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

Erros de tarefa

Uma tarefa criada pela Meshy ainda pode falhar durante a execução. Seu status se torna FAILED, a Meshy reembolsa seus créditos, e task_error explica o motivo.

{
  "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."
  }
}

Error types

type é a categoria geral da falha. Use-o para decidir o que fazer em seguida.

Códigos de erro

Quando code está presente, ele indica um dos seguintes problemas.

image_too_complex

A imagem de entrada ou o prompt descreve um assunto geometricamente complexo demais para a geração 3D.

Por exemplo:

• Pilhas densas de objetos pequenos, como uma caixa cheia de frutas ou uma pilha de livros
• Padrões repetitivos intrincados, como estruturas em treliça, andaimes ou telas de arame
• Edifícios complexos, como prédios de vários andares com muitas janelas e varandas
• Vários objetos distintos em uma única imagem, em vez de um único assunto

Estas entradas são provavelmente complexas demais:

Para corrigir isso, tente um ou mais dos seguintes passos:

• Use um objeto por imagem. O Meshy funciona melhor com um único assunto claro, então não coloque vários objetos separados na mesma imagem ou prompt.
• Simplifique seu assunto. Por exemplo, use um vaso simples em vez de um vaso cheio de dezenas de flores.
• Evite cenas. Prédios inteiros, quarteirões, cômodos mobiliados e paisagens provavelmente são complexos demais. Concentre-se em um único objeto.
• Evite estruturas repetitivas densas. Andaimes, telas de arame, treliças e pilhas de itens pequenos são causas comuns.

model_missing_uv

Você enviou 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 envolve na superfície 3D.

Para corrigir, faça uma das seguintes opções:

• Para manter o layout UV do seu próprio modelo, por exemplo, para posicionamento personalizado de costuras, adicione UVs ao modelo no seu software 3D. Confira-as no editor UV do software e, em seguida, envie o modelo novamente. Arquivos STL não conseguem armazenar UVs, então use GLB, FBX ou OBJ.
• Se você não precisa do seu próprio layout, ou não tem certeza, deixe de fora enable_original_uv ou defina-o como false. O Meshy então cria um layout UV para o modelo. As novas UVs cobrem bem o modelo, mas você não pode controlar onde ficam as costuras da textura.

model_insufficient_uv

O modelo possui coordenadas UV, mas elas cobrem muito pouco do espaço UV para permitir uma boa texturização. Isso costuma acontecer com modelos cujo exportador gravou UVs de espaço reservado ou colapsadas, sem um desdobramento adequado.

Para corrigir isso, faça uma das seguintes opções:

• Para manter seu próprio layout UV, desdobre novamente as UVs do modelo no seu software 3D. Distribua as ilhas pelo espaço UV, em vez de concentrá-las em um pequeno canto dele.
• Se você não precisa do seu próprio layout, omita enable_original_uv ou defina-o como false. O Meshy então cria um novo layout UV. Você perde o posicionamento das suas costuras, mas as novas UVs cobrem espaço suficiente para texturização.

model_missing_texture

O modelo de entrada de uma tarefa de Multi-Color Print não possui nenhuma cor que a Meshy consiga dividir em cores de impressão. A Meshy cria um 3MF multicolorido a partir das cores do modelo, então uma malha branca simples não oferece nada para trabalhar. Por exemplo, uma prévia de Texto para 3D ou Imagem para 3D que nunca foi texturizada não tem cor. O mesmo vale para a saída de Reparar imprimibilidade, ou uma tarefa de Auto Split que não manteve a textura.

O que conta como cor depende do style solicitado:

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

A Meshy rejeita um modelo sem textura de cor base e sem cores de vértice para ambos os estilos, em vez de permitir que cartoon o transforme em uma impressão de cor única.

A Meshy recusa a maioria dessas solicitações antes de criar a tarefa, com um 400 e a mesma explicação. Normalmente, você só recebe esse código quando a Meshy não consegue verificar a entrada antecipadamente. Por exemplo, a Meshy verifica um upload .fbx somente após a tarefa convertê-lo.

Para corrigir isso, use a opção que se adequa ao seu modelo:

• Texturize o modelo primeiro. Execute Retexturizar nele, ou gere-o com uma tarefa de refine do Texto para 3D ou uma tarefa de Imagem para 3D com should_texture: true. Em seguida, envie essa tarefa como input_task_id.
• Para um modelo colorido por vértice, como uma digitalização por fotogrametria ou uma malha pintada à mão, use style: "cartoon", que lê COLOR_0.
• Para um modelo parcialmente texturizado ou com múltiplas texturas usando realistic, dê a todas as partes da malha UVs e a mesma textura de cor base única. Para isso, texturize as partes restantes, ou combine as texturas em um único atlas. Você também pode mudar para style: "cartoon".

textured_split_refused

Uma tarefa de Auto Split com keep_texture: true não consegue manter a textura do modelo de entrada nas partes. Por exemplo, o modelo não tem UVs, ou sua textura não tem espaço para as novas faces criadas pelos cortes. A Meshy reembolsa os créditos.

Para corrigir isso, envie a solicitação novamente sem keep_texture, ou com keep_texture: false. As partes então retornam cada uma com uma cor sólida.

invalid_input

A entrada falhou em uma verificação, e nenhum código mais específico se aplica. message fornece o motivo.

Por exemplo:

• Um arquivo de modelo vazio ou corrompido
• Uma variante não suportada de um formato de arquivo, como um arquivo FBX em ASCII ou um arquivo GLB comprimido com meshopt
• Um modelo enviado sem objetos 3D válidos, por exemplo, um arquivo que contém apenas armaduras, câmeras ou luzes
• Conteúdo que não passa nos filtros de segurança

Para corrigir isso, leia message para identificar o problema específico. Verifique se seus arquivos de entrada e parâmetros atendem aos requisitos do endpoint.

moderation_blocked

Os filtros de segurança rejeitaram seu prompt ou as imagens de referência. Os filtros verificam o texto e as imagens em conjunto.

Para corrigir, faça uma ou ambas as seguintes ações:

• Reformule o prompt para remover descrições sugestivas ou sensíveis.
• Altere as imagens de referência que mostrem conteúdo que os filtros possam bloquear.

moderation_unavailable

Tipo: server_error. A moderation de conteúdo ficou temporariamente indisponível, então o Meshy falhou a tarefa em vez de pular a verificação. Não há nada de errado com seu conteúdo.

Para corrigir, crie a tarefa novamente.

timeout

A tarefa ultrapassou um limite de tempo do lado do servidor, seja para processamento ou para espera na fila, então o Meshy a marcou como falha e reembolsou seus créditos. Alta carga, ou uma entrada complexa demais para ser concluída a tempo, pode causar isso.

Isso é diferente de um timeout no seu próprio código. Se o seu cliente parou de esperar, a tarefa ainda está em execução. Veja Quanto tempo esperar.

Para corrigir isso, siga estes passos:

1. Crie a tarefa novamente. Timeouts costumam ser temporários, e uma nova tarefa pode ter sucesso.
2. Se continuar falhando, simplifique sua entrada, por exemplo, reduzindo o nível de detalhe da sua imagem ou prompt. Para entradas mais difíceis de processar, veja image_too_complex.

queue_timeout

Tipo: timeout. A tarefa aguardou muito tempo na fila sem iniciar, então a Meshy falhou a tarefa e devolveu quaisquer créditos cobrados por ela. A sua entrada não causou este erro.

Para corrigir isso, crie a tarefa novamente.

format_conversion_failed

A Meshy gerou o modelo, mas a conversão dele para um formato solicitado falhou.

Para corrigir isso, siga estas etapas:

1. Crie a tarefa novamente.
2. Se um formato continuar falhando, solicite um formato diferente que atenda às suas necessidades.

Boas práticas

• Repita tarefas com falha. Para uma tarefa com falha com timeout, service_unavailable ou server_error, crie uma nova tarefa com backoff exponencial.
• Não crie uma nova tarefa quando sua própria solicitação atingir o tempo limite. A primeira tarefa ainda pode estar em execução, então verifique se ela existe antes de criar outra. Veja Quanto tempo esperar.
• Registre os IDs das tarefas. Inclua o ID ao entrar em contato com o suporte.
• Verifique as entradas antes de enviá-las. Certifique-se de que as imagens e os modelos atendam aos requisitos de formato do endpoint.
• Chame a API a partir do seu servidor. Código executado em um navegador expõe sua chave de API para qualquer pessoa que abrir a página.