Errores

En esta guía, hablaremos sobre lo que sucede cuando algo sale mal mientras trabajas con el Meshy API.

Errores de Solicitud

Estos errores se devuelven inmediatamente cuando su solicitud de API es rechazada. Verifique el código de estado HTTP y el campo message para entender qué salió mal.

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

Errores de Tareas

Estos errores ocurren después de que se ha creado una tarea y está en proceso. Verifique el objeto task_error en la respuesta de la tarea para obtener detalles del error.

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

El campo type te indica la categoría general del fallo. Úsalo para decidir tu estrategia de reintento.

Códigos de Error

Cuando el campo code está presente, identifica un problema específico y accionable. A continuación se presenta la referencia completa para cada código de error.

image_too_complex

Este error ocurre cuando la imagen de entrada o el prompt describe un sujeto que es demasiado geométricamente complejo para que el modelo de generación 3D lo procese.

Ejemplos comunes incluyen:

• Montones densos de objetos pequeños (por ejemplo, una caja llena de frutas, una pila de libros)
• Patrones repetitivos intrincados (por ejemplo, estructuras de celosía, andamios, mallas de alambre)
• Estructuras de edificios complejas (por ejemplo, edificios de varios pisos con muchas ventanas y balcones)
• Múltiples objetos distintos en una imagen en lugar de un solo sujeto

Ejemplos de entradas que probablemente son demasiado complejas:

Resolución:

1. Usa un solo objeto por imagen. El modelo funciona mejor con un sujeto claro. No incluyas múltiples objetos separados en la misma imagen o prompt.
2. Simplifica tu sujeto. Reduce el nivel de detalle. Por ejemplo, un jarrón simple en lugar de un jarrón lleno de docenas de flores.
3. Evita prompts a nivel de escena. Edificios enteros, bloques de ciudad, interiores llenos de muebles o paisajes probablemente excederán la capacidad del modelo. Enfócate en un solo objeto.
4. Evita estructuras repetitivas densas. Sujetos como andamios, mallas de alambre, patrones de celosía o montones de muchos objetos pequeños son desencadenantes comunes.

model_missing_uv

Este error ocurre cuando subes un modelo para texturizar con enable_original_uv configurado en true, pero el modelo no tiene coordenadas UV. Las coordenadas UV definen cómo una textura 2D se envuelve sobre la superficie 3D de tu modelo.

Resolución:

La solución correcta depende de por qué configuraste enable_original_uv en true:

• Si necesitas preservar la distribución UV original de tu modelo (por ejemplo, colocación de costuras personalizadas para un mapeo de texturas preciso): tu modelo debe tener coordenadas UV válidas. Verifica que existan UVs en el editor UV de tu software 3D antes de subirlo. Ten en cuenta que los archivos STL no pueden almacenar datos UV, por lo que utiliza GLB, FBX o OBJ en su lugar.
• Si no necesitas un control específico de UV (o no estás seguro): omite enable_original_uv o configúralo en false. El sistema generará automáticamente una distribución UV para tu modelo. Los UVs generados automáticamente están optimizados para la cobertura, pero no tendrás control sobre dónde se colocan las costuras de la textura.

model_insufficient_uv

Este error ocurre cuando un modelo tiene coordenadas UV, pero la cobertura UV es demasiado pequeña para un texturizado de calidad. Esto ocurre comúnmente con modelos exportados desde herramientas 3D que generan UVs de marcador de posición o colapsados sin un desdoblamiento adecuado.

Resolución:

• Si necesitas preservar tu distribución UV original: vuelve a desdoblar las UVs del modelo en tu software 3D. Asegúrate de que las islas UV estén adecuadamente distribuidas a lo largo del espacio UV en lugar de estar colapsadas en un área pequeña.
• Si no necesitas un control específico de UV: omite enable_original_uv o configúralo en false. El sistema generará automáticamente una nueva distribución UV. La desventaja es que perderás la colocación original de las costuras, pero las UVs generadas automáticamente tendrán una cobertura adecuada para el texturizado.

invalid_input

Este es el código de error de reserva cuando la entrada falla en la validación pero no se aplica un código más específico. El campo message contiene la razón específica del fallo.

Las causas comunes incluyen:

• Archivos de modelo vacíos o corruptos
• Variaciones de formato de archivo no compatibles (por ejemplo, archivos FBX en ASCII, GLB comprimidos con meshopt)
• No se encontraron objetos 3D válidos en el modelo cargado (por ejemplo, el archivo contiene solo armaduras, cámaras o luces)
• Contenido que no pasa los filtros de seguridad

Resolución: Verifique el campo message para obtener detalles sobre lo que salió mal. Asegúrese de que sus archivos de entrada y parámetros coincidan con los requisitos del endpoint.

moderation_blocked

Este error ocurre cuando tu prompt o las imágenes de referencia son rechazadas por los filtros de seguridad de IA. El filtro evalúa tanto el prompt de texto como cualquier imagen de referencia en conjunto.

Resolución:

• Reformula tu prompt de texto para eliminar descripciones sugestivas o sensibles.
• Ajusta las imágenes de referencia si representan contenido que pueda activar los filtros de seguridad.

timeout

Este error significa que el tiempo de procesamiento de tu tarea excedió el límite permitido. Esto puede suceder debido a una alta carga del sistema o porque la entrada es demasiado compleja para procesarse dentro del límite de tiempo.

Resolución:

1. Vuelve a intentar la solicitud. Los timeouts a menudo son transitorios y un reintento puede tener éxito.
2. Simplifica tu entrada. Si los reintentos siguen fallando, tu entrada puede ser demasiado compleja. Intenta reducir el nivel de detalle en tu imagen o prompt. Consulta image_too_complex para obtener orientación sobre qué tipos de entradas son más difíciles de procesar.

format_conversion_failed

Este error ocurre cuando el modelo 3D generado no pudo ser convertido al formato de salida solicitado. El modelo fue generado con éxito, pero el paso de conversión falló.

Resolución:

1. Vuelva a intentar la solicitud.
2. Pruebe un formato de salida diferente. Si un formato específico sigue fallando, cambie a otro formato que se adapte a sus necesidades.

Mejores Prácticas

1. Implemente lógica de reintento. Para los errores de timeout y service_unavailable, implemente lógica de reintento con retroceso exponencial.
2. Registre los IDs de tareas. Siempre registre el ID de la tarea para fines de depuración. Inclúyalo al contactar al soporte.
3. Valide las entradas. Asegúrese de que sus imágenes y modelos de entrada cumplan con los requisitos de formato antes de enviarlos.