Erros

Descubra porque é que um pedido ou uma tarefa falhou, e o que fazer a seguir. Um pedido pode falhar de imediato com um erro HTTP, e uma tarefa pode falhar mais tarde com um task_error.

Request errors

A Meshy devolve estes erros de imediato, quando rejeita um pedido. Para descobrir o que correu mal, verifique o código de estado HTTP e o campo message.

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

Erros de tarefa

Uma tarefa que o Meshy criou ainda pode falhar durante a sua execução. O seu status passa a FAILED, o Meshy reembolsa os 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."
  }
}

Tipos de erro

type é a categoria ampla da falha. Use-a para decidir o que fazer a seguir.

Códigos de erro

Quando code está presente, identifica um dos seguintes problemas.

image_too_complex

A imagem de entrada ou o prompt descreve um motivo demasiado complexo em termos geométricos para a geração 3D.

Por exemplo:

• Pilhas densas de pequenos objetos, como um caixote cheio de fruta ou uma pilha de livros
• Padrões repetitivos intrincados, como estruturas em treliça, andaimes ou malhas de arame
• Edifícios complexos, como edifícios de vários pisos com muitas janelas e varandas
• Vários objetos distintos numa única imagem, em vez de um único motivo

Estas entradas são provavelmente demasiado complexas:

Para corrigir isto, experimente uma ou mais das seguintes sugestões:

• Utilize um objeto por imagem. O Meshy funciona melhor com um único motivo claro, pelo que não deve colocar vários objetos separados na mesma imagem ou prompt.
• Simplifique o seu motivo. Por exemplo, utilize um vaso simples em vez de um vaso cheio de dezenas de flores.
• Evite cenas. Edifícios inteiros, quarteirões urbanos, divisões mobiladas e paisagens são, provavelmente, demasiado. Concentre-se num único objeto.
• Evite estruturas repetitivas densas. Andaimes, malhas de arame, treliças e pilhas de pequenos itens são causas comuns.

model_missing_uv

Enviou 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 envolve a superfície 3D.

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

• Para manter a própria disposição UV do seu modelo, por exemplo para um posicionamento de costuras personalizado, adicione UVs ao modelo no seu software 3D. Verifique-as no respetivo editor de UV e, depois, volte a carregar o modelo. Os ficheiros STL não conseguem armazenar UVs, por isso utilize GLB, FBX ou OBJ.
• Se não precisar da sua própria disposição, ou não tiver a certeza, omita enable_original_uv ou defina-o como false. O Meshy cria então uma disposição UV para o modelo. As novas UVs cobrem bem o modelo, mas não é possível controlar onde ficam as costuras da textura.

model_insufficient_uv

O modelo tem coordenadas UV, mas estas cobrem muito pouco do espaço UV para permitir uma boa texturização. Isto acontece frequentemente com modelos cujo exportador escreveu UVs de marcador de posição ou colapsadas sem um desdobramento adequado.

Para corrigir, faça um dos seguintes:

• Para manter a sua própria disposição UV, desdobre novamente as UVs do modelo no seu software 3D. Distribua as ilhas pelo espaço UV em vez de as concentrar num pequeno canto do mesmo.
• Se não precisar da sua própria disposição, omita enable_original_uv ou defina-o como false. O Meshy cria então uma nova disposição UV. Perde o posicionamento das costuras, mas as novas UVs cobrem espaço suficiente para texturizar.

model_missing_texture

O modelo de entrada de uma tarefa de Multi-Color Print não tem nenhuma cor que a Meshy consiga dividir em cores de impressão. A Meshy constrói um 3MF multicor a partir das cores do modelo, pelo que uma malha branca simples não tem nada com que trabalhar. Por exemplo, uma pré-visualização de Texto para 3D ou Imagem para 3D que nunca foi texturizada não tem cor. O mesmo acontece com o resultado 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 obtém a amostra da textura de cor base através das UVs do modelo. Necessita de uma única textura de cor base e de 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 nem cores de vértice para ambos os estilos, em vez de permitir que cartoon o transforme numa impressão de cor única.

A Meshy recusa a maioria destes pedidos antes de criar a tarefa, com um 400 e a mesma explicação. Normalmente, só obtém este código quando a Meshy não consegue verificar a entrada antecipadamente. Por exemplo, a Meshy só verifica um carregamento .fbx depois de a tarefa o converter.

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

• Texturize primeiro o modelo. Execute Retexturizar sobre ele, ou gere-o com uma tarefa de refine de Texto para 3D ou uma tarefa de Imagem para 3D com should_texture: true. Depois envie essa tarefa como input_task_id.
• Para um modelo com cores 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 com realistic, dê UVs a todas as partes da malha e a mesma textura de cor base única. Para isso, texturize as partes restantes, ou junte as texturas num único atlas. 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 peças. Por exemplo, o modelo não tem UVs, ou a sua textura não tem espaço para as novas faces que os cortes criam. A Meshy reembolsa os créditos.

Para corrigir, envie o pedido novamente sem keep_texture, ou com keep_texture: false. As peças voltam então cada uma com uma cor plana.

invalid_input

A entrada falhou numa verificação, e não se aplica nenhum código mais específico. message indica o motivo.

Por exemplo:

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

Para corrigir, leia message para saber o problema específico. Verifique se os seus ficheiros de entrada e parâmetros cumprem os requisitos do endpoint.

moderation_blocked

Os filtros de segurança rejeitaram o 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 esteve temporariamente indisponível, pelo que a Meshy falhou a tarefa em vez de ignorar a verificação. Não há nada de errado com o seu conteúdo.

Para corrigir, crie a tarefa novamente.

timeout

A tarefa ultrapassou um limite de tempo definido no servidor, seja no processamento ou na espera na fila, pelo que a Meshy falhou a tarefa e reembolsou os créditos. Uma carga elevada, ou uma entrada demasiado complexa para terminar a tempo, pode causar isto.

Isto é diferente de um timeout no seu próprio código. Se o seu cliente parou de esperar, a tarefa continua em execução. Consulte Quanto tempo esperar.

Para resolver, siga estes passos:

1. Crie a tarefa novamente. Os timeouts são muitas vezes temporários, e uma nova tarefa pode ter sucesso.
2. Se continuar a falhar, simplifique a sua entrada, por exemplo reduzindo o detalhe na sua imagem ou prompt. Para entradas mais difíceis de processar, consulte image_too_complex.

queue_timeout

Tipo: timeout. A tarefa esperou demasiado tempo na fila sem ser iniciada, pelo que o Meshy falhou a tarefa e devolveu quaisquer créditos cobrados por ela. O seu input não causou este erro.

Para corrigir, crie a tarefa novamente.

format_conversion_failed

O Meshy gerou o modelo, mas a conversão para um formato que solicitou falhou.

Para corrigir, siga estes passos:

1. Crie a tarefa novamente.
2. Se um formato continuar a falhar, solicite um formato diferente que se adeque às suas necessidades.

Best practices

• Repita as tarefas que falharem. Para uma tarefa com falha com timeout, service_unavailable ou server_error, crie uma nova tarefa com espera exponencial (exponential backoff).
• Não crie uma nova tarefa quando o seu próprio pedido expirar. É possível que a primeira tarefa ainda esteja em execução, por isso verifique se esta existe antes de criar outra. Consulte Quanto tempo esperar.
• Registe os IDs das tarefas. Inclua o ID quando contactar o suporte.
• Verifique as entradas antes de as enviar. Certifique-se de que as imagens e os modelos cumprem os requisitos de formato do endpoint.
• Chame a API a partir do seu servidor. O código executado num navegador expõe a sua chave de API a qualquer pessoa que abra a página.