Errores

Descubra por qué falló una solicitud o una tarea, y qué hacer a continuación. Una solicitud puede fallar de inmediato con un error HTTP, y una tarea puede fallar más tarde con un task_error.

Errores de solicitud

Meshy devuelve estos errores de inmediato, cuando rechaza una solicitud. Para averiguar qué salió mal, revisa el código de estado HTTP y el campo message.

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

Errores de tarea

Una tarea que Meshy creó aún puede fallar mientras se ejecuta. Su status pasa a ser FAILED, Meshy reembolsa sus créditos, y task_error explica el 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 error

type es la categoría general del fallo. Úsala para decidir qué hacer a continuación.

Códigos de error

Cuando code está presente, indica uno de los siguientes problemas.

image_too_complex

La imagen de entrada o el prompt describe un sujeto demasiado complejo geométricamente para la generación 3D.

Por ejemplo:

• Montones densos de objetos pequeños, como una caja llena de fruta o una pila de libros
• Patrones repetitivos intrincados, como estructuras de celosía, andamios o mallas de alambre
• Edificios complejos, como edificios de varios pisos con muchas ventanas y balcones
• Varios objetos distintos en una sola imagen, en lugar de un único sujeto

Es probable que estas entradas sean demasiado complejas:

Para solucionarlo, prueba una o más de las siguientes opciones:

• Usa un objeto por imagen. Meshy funciona mejor con un único sujeto claro, así que no incluyas varios objetos separados en la misma imagen o prompt.
• Simplifica tu sujeto. Por ejemplo, usa un jarrón sencillo en lugar de un jarrón lleno de docenas de flores.
• Evita las escenas. Edificios enteros, manzanas de ciudad, habitaciones amuebladas y paisajes probablemente sean demasiado. Concéntrate en un solo objeto.
• Evita las estructuras repetitivas densas. Los andamios, las mallas de alambre, las celosías y los montones de objetos pequeños son desencadenantes comunes.

model_missing_uv

Enviaste un modelo para texturizar con enable_original_uv establecido en true, pero el modelo no tiene coordenadas UV. Las coordenadas UV definen cómo una textura 2D se envuelve sobre la superficie 3D.

Para solucionarlo, haz una de las siguientes acciones:

• Para conservar la distribución UV propia de tu modelo, por ejemplo para una colocación de costuras personalizada, agrega UVs al modelo en tu software 3D. Compruébalas en su editor de UV y, luego, vuelve a subir el modelo. Los archivos STL no pueden almacenar UVs, así que usa GLB, FBX u OBJ.
• Si no necesitas tu propia distribución, o no estás seguro, omite enable_original_uv o establécelo en false. Meshy entonces crea una distribución UV para el modelo. Las nuevas UVs cubren bien el modelo, pero no puedes controlar dónde van las costuras de la textura.

model_insufficient_uv

El modelo tiene coordenadas UV, pero cubren muy poco del espacio UV para texturizar bien. Esto suele ocurrir con modelos cuyo exportador escribió UV de marcador de posición o colapsadas sin un desenvolvimiento adecuado.

Para solucionarlo, haz una de las siguientes acciones:

• Para conservar tu propia distribución UV, vuelve a desenvolver las UV del modelo en tu software 3D. Distribuye las islas por todo el espacio UV en lugar de concentrarlas en una pequeña esquina de este.
• Si no necesitas tu propia distribución, omite enable_original_uv o configúralo en false. Meshy entonces crea una nueva distribución UV. Perderás la ubicación de tus costuras, pero las nuevas UV cubrirán suficiente espacio para texturizar.

model_missing_texture

El modelo de entrada de una tarea de Multi-Color Print no tiene ningún color que Meshy pueda dividir en colores de impresión. Meshy construye un 3MF multicolor a partir de los colores del modelo, así que una malla blanca lisa no tiene con qué trabajar. Por ejemplo, una vista previa de Texto a 3D o Imagen a 3D que nunca se texturizó no tiene color. Tampoco lo tiene la salida de Reparar imprimibilidad, ni una tarea de Auto Split que no conservó la textura.

Lo que cuenta como color depende del style que hayas solicitado:

• realistic muestrea la textura de color base a través de las UV del modelo. Necesita una única textura de color base y UV en cada parte de la malla.
• cartoon aplana los colores por cara. Acepta una textura de color base en cualquier parte, o colores por vértice (COLOR_0).

Meshy rechaza un modelo que no tiene ni textura de color base ni colores de vértice para ambos estilos, en lugar de dejar que cartoon lo convierta en una impresión de un solo color.

Meshy rechaza la mayoría de estas solicitudes antes de crear la tarea, con un 400 y la misma explicación. Normalmente solo obtienes este código cuando Meshy no puede comprobar la entrada de antemano. Por ejemplo, Meshy solo comprueba una carga .fbx después de que la tarea la convierte.

Para solucionarlo, usa la opción que se ajuste a tu modelo:

• Texturiza primero el modelo. Ejecuta Retexturizar sobre él, o genéralo con una tarea refine de Texto a 3D o una tarea de Imagen a 3D con should_texture: true. Luego envía esa tarea como input_task_id.
• Para un modelo con colores por vértice, como un escaneo por fotogrametría o una malla pintada a mano, usa style: "cartoon", que lee COLOR_0.
• Para un modelo parcialmente texturizado o con múltiples texturas con realistic, dale a cada parte de la malla UV y la misma única textura de color base. Para ello, texturiza las partes restantes o fusiona las texturas en un solo atlas. También puedes cambiar a style: "cartoon".

textured_split_refused

Una tarea de Auto Split con keep_texture: true no puede conservar la textura del modelo de entrada en las partes. Por ejemplo, el modelo no tiene UVs, o su textura no tiene espacio para las nuevas caras que crean los cortes. Meshy reembolsa los créditos.

Para solucionarlo, envía la solicitud de nuevo sin keep_texture, o con keep_texture: false. Las partes entonces se devuelven con un color plano cada una.

invalid_input

La entrada falló una verificación, y no se aplica ningún código más específico. message indica el motivo.

Por ejemplo:

• Un archivo de modelo vacío o dañado
• Una variante no compatible de un formato de archivo, como un archivo FBX ASCII o un archivo GLB comprimido con meshopt
• Un modelo subido sin objetos 3D válidos, por ejemplo un archivo que solo contiene armaduras, cámaras o luces
• Contenido que no pasa los filtros de seguridad

Para solucionarlo, lee message para conocer el problema específico. Comprueba que tus archivos de entrada y parámetros cumplan los requisitos del endpoint.

moderation_blocked

Los filtros de seguridad rechazaron tu prompt o las imágenes de referencia. Los filtros verifican el texto y las imágenes en conjunto.

Para solucionarlo, haz una o ambas de las siguientes acciones:

• Reformula el prompt para eliminar descripciones sugerentes o sensibles.
• Cambia las imágenes de referencia que muestren contenido que los filtros puedan bloquear.

moderation_unavailable

Tipo: server_error. La moderation de contenido no estuvo disponible temporalmente, por lo que Meshy hizo fallar la tarea en lugar de omitir la verificación. No hay nada incorrecto con tu contenido.

Para solucionarlo, crea la tarea de nuevo.

timeout

La tarea superó un límite de tiempo del lado del servidor, ya sea de procesamiento o de espera en la cola, por lo que Meshy la marcó como fallida y reembolsó sus créditos. Una carga alta, o una entrada demasiado compleja para finalizar a tiempo, puede provocarlo.

Esto es distinto de un timeout en tu propio código. Si tu cliente dejó de esperar, la tarea sigue ejecutándose. Consulta Cuánto tiempo esperar.

Para solucionarlo, sigue estos pasos:

1. Crea la tarea de nuevo. Los timeouts suelen ser temporales, y una nueva tarea podría tener éxito.
2. Si sigue fallando, simplifica tu entrada, por ejemplo reduciendo el detalle en tu imagen o prompt. Para entradas más difíciles de procesar, consulta image_too_complex.

queue_timeout

Tipo: timeout. La tarea esperó demasiado tiempo en la cola sin comenzar, por lo que Meshy la marcó como fallida y devolvió los créditos cobrados por ella. Tu entrada no causó este error.

Para solucionarlo, crea la tarea de nuevo.

format_conversion_failed

Meshy generó el modelo, pero la conversión a un formato que solicitaste falló.

Para solucionarlo, sigue estos pasos:

1. Crea la tarea de nuevo.
2. Si un formato sigue fallando, solicita un formato diferente que se ajuste a tus necesidades.

Buenas prácticas

• Reintenta las tareas fallidas. Para una tarea fallida con timeout, service_unavailable o server_error, crea una nueva tarea con retroceso exponencial.
• No crees una nueva tarea cuando tu propia solicitud agote el tiempo de espera. Es posible que la primera tarea siga en ejecución, así que comprueba si existe antes de crear otra. Consulta Cuánto tiempo esperar.
• Registra los ID de tarea. Incluye el ID cuando te pongas en contacto con soporte.
• Comprueba las entradas antes de enviarlas. Asegúrate de que las imágenes y los modelos cumplan los requisitos de formato del endpoint.
• Llama a la API desde tu servidor. El código que se ejecuta en un navegador expone tu clave de API a cualquiera que abra la página.