API de Analizar imprimibilidad

Analiza un modelo 3D para determinar su imprimibilidad: estanqueidad, volumen, agujeros, aristas non-manifold y caras degeneradas. Opcionalmente, también se puede comprobar el grosor de pared en el tamaño en el que planeas imprimir.

POST/openapi/v1/print/analyze

Crear una tarea de análisis de imprimibilidad

Este endpoint crea una nueva tarea de análisis de imprimibilidad. La tarea evalúa un modelo 3D e informa sus métricas de imprimibilidad.

La tarea se ejecuta en segundo plano. Para saber cuánto tiempo suele tardar, consulta Tiempos de procesamiento.

Si la tarea de entrada ya tiene imprimibilidad en caché, la tarea devuelta está lista de inmediato y la primera solicitud GET sobre ella devolverá el resultado del análisis sin pasar por el worker.

Para comprobar también el grosor de pared en el tamaño en el que planeas imprimir, envía printer_type, un tamaño de impresión, o ambos. El resultado se devuelve en printability.thin_walls. Comprobar el grosor de pared tarda más, por lo que la tarea normalmente no está lista de inmediato, aunque el modelo ya se haya analizado antes.

Parámetros

Solo se requiere uno de input_task_id o model_url. Si se proporcionan ambos, input_task_id tiene prioridad.

Name
input_task_id
Type
string
Requerido
Description
El ID de una tarea exitosa que te pertenece. Tipos de tarea admitidos: Imagen a 3D, Multi-imagen a 3D, Texto a 3D, Remallado y Retexturizar. La tarea debe usar Meshy 6 o una versión más reciente (incluyendo Meshy 7) y debe tener un estado SUCCEEDED. También se aceptan tareas de Reparar imprimibilidad.

Name
model_url
Type
string
Requerido
Description
URL de un modelo 3D para analizar. Formatos admitidos: .glb, .gltf, .obj, .fbx, .stl. Tamaño máximo de archivo: 100 MB. Debe usar http, https, o una URL data: (las URL de datos omiten las comprobaciones de extensión).
Las URL de descarga de Meshy (assets.meshy.ai/…?Expires=…&Signature=…) están firmadas y dejan de funcionar al llegar a expires_at de la tarea; volver a consultar la tarea no las renueva. Para un modelo generado con Meshy, envía input_task_id en su lugar. Funciona mientras la tarea de origen se conserve (consulta Retención de recursos). Para reutilizar un modelo después de eso, descárgalo antes de expires_at y envía tu propia copia.

Envía como máximo uno de los dos campos de tamaño de impresión. Si envías printer_type sin un tamaño, el tamaño predeterminado es:

.glb y cualquier input_task_id: 150 mm de alto.
.stl: el lado más largo del propio archivo, interpretado en milímetros. Para un STL en otras unidades, envía intended_print_longest_side_mm.
.obj, .fbx, .gltf: 150 mm en el lado más largo.

Name
printer_type
Type
string
Description
La impresora que planeas usar. Establece el grosor mínimo de pared para la comprobación de grosor de pared. Por defecto es fdm cuando envías un tamaño de impresión sin especificarlo.
Valores disponibles:
- fdm: filamento, 1.0 mm de pared mínima.
- sla: resina, 0.8 mm de pared mínima.
- full_color: a todo color, 2.0 mm de pared mínima.
Name
intended_print_height_mm
Type
number
Description
Altura de la impresión, en milímetros. Rango: [1, 1000]. Redondeado al milímetro más cercano. Solo para entrada GLB.
Name
intended_print_longest_side_mm
Type
number
Description
Longitud del lado más largo de la impresión, en milímetros. Rango: [1, 1000]. Redondeado al milímetro más cercano. Funciona con todos los formatos de entrada.

Devuelve

La propiedad result de la respuesta contiene el id de la tarea de análisis de imprimibilidad recién creada.

Modos de fallo

Name
400 - Bad Request
Description
La solicitud no fue aceptable. Causas comunes:
- Parámetro faltante: no se proporcionó input_task_id ni model_url.
- UUID inválido: input_task_id no es un UUID válido.
- URL de modelo inválida: model_url tiene un formato incorrecto, usa un esquema no admitido o tiene una extensión de archivo no admitida.
- Archivo de modelo demasiado grande: el cuerpo de model_url superó los 100 MB.
- No se pudo descargar el archivo del modelo: model_url devolvió un error, generalmente porque una URL de descarga firmada de Meshy ha expirado. Volver a consultar la tarea devuelve la misma URL con la misma expiración, así que envía tu propia copia del archivo, o usa input_task_id mientras la tarea de origen aún se conserve.
- Tarea no exitosa: la tarea referenciada aún está pendiente, en progreso o falló.
- Tamaño de impresión inválido: intended_print_height_mm o intended_print_longest_side_mm está fuera de [1, 1000], o se enviaron ambos.
- Tipo de impresora desconocido: printer_type no es fdm, sla ni full_color.
- Altura en un modelo que no es GLB: se envió intended_print_height_mm con un model_url que no es .glb. Usa intended_print_longest_side_mm en su lugar.
- No se puede dimensionar este modelo por altura: con la altura solicitada (o los 150 mm predeterminados), el lado más largo del modelo quedaría fuera de [1, 1000] mm, el modelo es plano, o su tamaño no se puede determinar. Usa intended_print_longest_side_mm en su lugar. Para un model_url .glb y algunas tareas con input_task_id, esto solo se detecta después de que la tarea comienza, y la tarea termina en FAILED en su lugar.
- Tamaño de STL inutilizable: se envió printer_type sin un tamaño, y el lado más largo propio del .stl no se puede leer o está fuera de [1, 1000] mm. Envía intended_print_longest_side_mm.
Name
401 - Unauthorized
Description
Falló la autenticación. Por favor, comprueba tu clave de API.
Name
403 - Forbidden
Description
La tarea existe pero pertenece a otro usuario.
Name
404 - Not Found
Description
Causas comunes:
- La tarea no existe o ha sido eliminada.
- La tarea usa un modelo anterior a Meshy 6, o su mode no produce un recurso 3D.
- El archivo de modelo subyacente ya no está disponible en el almacenamiento.
Name
429 - Too Many Requests
Description
Has superado tu cuota de tareas pendientes o tu límite de tasa.

Request

POST

/openapi/v1/print/analyze

# Analyze an existing task
curl https://api.meshy.ai/openapi/v1/print/analyze \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
  }'

# Or analyze a model URL directly
curl https://api.meshy.ai/openapi/v1/print/analyze \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "model_url": "https://example.com/model.glb"
  }'

# Also check wall thickness for a 100 mm tall SLA print
curl https://api.meshy.ai/openapi/v1/print/analyze \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "printer_type": "sla",
    "intended_print_height_mm": 100
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

GET/openapi/v1/print/analyze/:id

Recuperar una tarea de Analizar imprimibilidad

Este endpoint recupera una tarea de analizar imprimibilidad por su ID.

Parámetros

Name
id
Type
path
Description
El ID de la tarea de analizar imprimibilidad que se desea recuperar.

Devuelve

El objeto de tarea de Analizar imprimibilidad. El campo printability es null hasta que la tarea alcanza el estado SUCCEEDED. Cuando se comprobó el grosor de pared, printability también incluye intended_print y thin_walls.

Request

GET

/openapi/v1/print/analyze/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl https://api.meshy.ai/openapi/v1/print/analyze/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}

Response (wall thickness checked)

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000012000,
  "expires_at": 1715725412000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "error",
    "issue_count": 2,
    "error_count": 1,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "intended_print": {
      "printer_type": "sla",
      "height_mm": 100,
      "longest_side_mm": 118,
      "wall_thickness_mm": 0.8,
      "dimensions_mm": [118, 72.41, 99.87]
    },
    "thin_walls": {
      "thin_area_ratio": 0.083,
      "has_thin_walls": true,
      "status": "error"
    },
    "evaluated_at": 1700000012000
  },
  "consumed_credits": 0
}

DELETE/openapi/v1/print/analyze/:id

Eliminar una tarea de Analizar imprimibilidad

Este endpoint elimina permanentemente una tarea de análisis de imprimibilidad y su resultado almacenado en caché. Esta acción es irreversible.

Parámetros de ruta

Name
id
Type
path
Description
El ID de la tarea de análisis de imprimibilidad que se va a eliminar.

Estado de la tarea

Una tarea que aún está en PENDING se elimina y los créditos consumidos en el momento de la creación se reembolsan.

Una tarea que ya está en IN_PROGRESS no se puede eliminar: la solicitud se rechaza con 409 Conflict y la tarea sigue en ejecución. Los créditos de una tarea que el worker ya ha comenzado no son reembolsables, por lo que eliminarla a mitad de la ejecución te costaría tanto los créditos como el resultado. Espera a que alcance el estado SUCCEEDED, FAILED o CANCELED, y luego elimínala.

Una tarea en un estado terminal (SUCCEEDED, FAILED o CANCELED) se elimina sin reembolso.

Devuelve

Devuelve 200 OK en caso de éxito, o 409 Conflict cuando la tarea está en IN_PROGRESS.

Request

DELETE

/openapi/v1/print/analyze/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/print/analyze/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS — the task is left running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

GET/openapi/v1/print/analyze

Listar tareas de Analizar imprimibilidad

Este endpoint le permite recuperar una lista de tareas de análisis de imprimibilidad.

Parámetros

Atributos opcionales

Name
page_num
Type
integer
Description
Número de página para la paginación. Comienza y por defecto es 1.
Name
page_size
Type
integer
Description
Límite del tamaño de página. Por defecto es 10 elementos. El máximo permitido es 100 elementos.
Name
sort_by
Type
string
Description
Campo por el cual ordenar. Valores disponibles:
- +created_at: Ordenar por hora de creación en orden ascendente.
- -created_at: Ordenar por hora de creación en orden descendente.

Devuelve

Devuelve una lista paginada de Objetos de tarea de Analizar imprimibilidad.

Request

GET

/openapi/v1/print/analyze

curl https://api.meshy.ai/openapi/v1/print/analyze?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-analyze",
    "status": "SUCCEEDED",
    "progress": 100,
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "expires_at": 1715725401000,
    "task_error": null,
    "printability": {
      "_version": "v1",
      "status": "warning",
      "issue_count": 1,
      "error_count": 0,
      "warning_count": 1,
      "metrics": {
        "is_watertight": true,
        "volume": 1.316167354292668,
        "non_manifold_edges": 0,
        "degenerate_faces": 43242,
        "holes": 0
      },
      "evaluated_at": 1700000001000
    },
    "consumed_credits": 0
  }
]

GET/openapi/v1/print/analyze/:id/stream

Transmitir una tarea de Analizar imprimibilidad

Este endpoint transmite actualizaciones en tiempo real para una tarea de analizar imprimibilidad utilizando Server-Sent Events (SSE).

Parámetros

Name
id
Type
path
Description
Identificador único de la tarea de analizar imprimibilidad a transmitir.

Devuelve

Devuelve un flujo de objetos de tarea de Analizar imprimibilidad como Server-Sent Events.

Cada fotograma (frame) transporta el objeto de tarea completo para la etapa —la misma forma que devuelve el endpoint Get—, por lo que mientras la tarea está en PENDING o IN_PROGRESS los campos de salida simplemente aún no están completados (null, [] o {}) y finished_at es null. El bloque printability se envía solo una vez que la tarea alcanza el estado SUCCEEDED.

Request

GET

/openapi/v1/print/analyze/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream

curl -N https://api.meshy.ai/openapi/v1/print/analyze/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// Every frame is the full task object; fields not yet populated are null / empty.
// The PENDING frame below is abbreviated to the fields that change.
event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}

The Analyze Printability Task Object

Name
id
Type
string
Description
Identificador único de la tarea. Aunque usamos un UUID k-sortable para los id de las tareas como detalle de implementación, no debes hacer ninguna suposición sobre el formato del id.
Name
type
Type
string
Description
Tipo de la tarea de analizar imprimibilidad. El valor es print-analyze.
Name
status
Type
string
Description
Estado de la tarea. Los valores posibles son uno de PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress de la tarea. Si la tarea aún no ha comenzado, esta propiedad será 0. Una vez que la tarea haya tenido éxito, esta pasará a ser 100.
Name
preceding_tasks
Type
integer
Description
El recuento de tareas precedentes.
El valor de este campo solo tiene sentido si el estado de la tarea es PENDING.
Name
created_at
Type
timestamp
Description
Marca de tiempo de cuándo se creó la tarea, en milisegundos.
Name
started_at
Type
timestamp
Description
Marca de tiempo de cuándo se inició la tarea, en milisegundos. Si la tarea aún no ha comenzado, esta propiedad será 0.
Name
finished_at
Type
timestamp
Description
Marca de tiempo de cuándo finalizó la tarea, en milisegundos. Si la tarea aún no ha finalizado, esta propiedad será 0.
Name
expires_at
Type
timestamp
Description
Marca de tiempo de cuándo expirará el resultado de la tarea en el sistema, en milisegundos. 0 si la tarea aún no ha finalizado.
Name
task_error
Type
object
Description
Información del error si la tarea ha fallado. Esta propiedad es null si la tarea no ha fallado. Consulta Errores para más detalles.
- Name
  message
  Type
  string
  Description
  Mensaje de error que describe qué salió mal.
Name
printability
Type
object
Description
Resultado de la evaluación de imprimibilidad. null hasta que la tarea alcance SUCCEEDED.
- Name
  _version
  Type
  string
  Description
  Versión del esquema del resultado de imprimibilidad. Actualmente v1.
- Name
  status
  Type
  string
  Description
  Estado general. Uno de:
  
  healthy: sin errores y sin advertencias.
  
  warning: al menos una advertencia, sin errores.
  
  error: al menos un error.
  
  unknown: no se pudo analizar el modelo.
  
  Cuando se comprobó el grosor de pared, este es el peor de los resultados anteriores y thin_walls.status. De peor a mejor: error, warning, unknown, healthy.
- Name
  issue_count
  Type
  integer
  Description
  Recuento total de problemas, igual a error_count + warning_count.
- Name
  error_count
  Type
  integer
  Description
  Número de problemas de nivel error. Los errores se generan cuando el modelo no es watertight, tiene volumen no positivo, o tiene aristas non-manifold. Cuando se comprobó el grosor de pared, las paredes demasiado delgadas (thin_walls.status es error) cuentan como un error adicional.
- Name
  warning_count
  Type
  integer
  Description
  Número de problemas de nivel advertencia. Las advertencias se generan cuando el modelo contiene caras degeneradas o agujeros.
- Name
  metrics
  Type
  object
  Description
  Métricas de geometría sin procesar devueltas por el evaluador.
  Name
  is_watertight
  Type
  boolean
  Description
  true cuando la malla no tiene aristas de límite (es decir, está cerrada).
  Name
  volume
  Type
  number
  Description
  Volumen del modelo en metros cúbicos.
  Name
  non_manifold_edges
  Type
  integer
  Description
  Recuento de aristas non-manifold.
  Name
  degenerate_faces
  Type
  integer
  Description
  Recuento de caras degeneradas (caras de área cero o inválidas).
  Name
  holes
  Type
  integer
  Description
  Recuento de agujeros (bucles de límite) en la malla.
- Name
  intended_print
  Type
  object
  Description
  La impresora y el tamaño que usó la comprobación de grosor de pared. Presente solo cuando se comprobó el grosor de pared.
  Name
  printer_type
  Type
  string
  Description
  fdm, sla, o full_color.
  Name
  height_mm
  Type
  number
  Description
  La altura de impresión en milímetros, si la impresión se dimensionó por altura. En caso contrario null.
  Name
  longest_side_mm
  Type
  number
  Description
  El lado más largo de la impresión en milímetros. Cuando se dimensiona por altura, se calcula a partir de las proporciones del modelo.
  Name
  wall_thickness_mm
  Type
  number
  Description
  El grosor de pared mínimo para printer_type, en milímetros. Las paredes más delgadas que este valor se reportan como demasiado delgadas.
  Name
  dimensions_mm
  Type
  array
  Description
  El [ancho, profundidad, altura] de la impresión en milímetros. La altura puede diferir de height_mm por una fracción de milímetro. null para entradas que no son GLB, o si no se puede determinar el tamaño del modelo.
- Name
  thin_walls
  Type
  object
  Description
  El resultado del grosor de pared. Presente solo cuando se comprobó el grosor de pared.
  Name
  thin_area_ratio
  Type
  number
  Description
  Proporción de la superficie, de 0 a 1, que es más delgada que intended_print.wall_thickness_mm. null si no se pudo medir el modelo.
  Name
  has_thin_walls
  Type
  boolean
  Description
  true si alguna parte de la superficie es demasiado delgada. Las esquinas agudas por sí solas pueden activar esto, así que usa status para decidir si las paredes necesitan engrosarse. null si no se pudo medir el modelo.
  Name
  status
  Type
  string
  Description
  El veredicto del grosor de pared. Uno de:
  
  healthy: el 5% o menos de la superficie es demasiado delgada.
  
  error: más del 5% de la superficie es demasiado delgada. Para engrosar las paredes, pasa el id de esta tarea a Reparar imprimibilidad como input_task_id (para un model_url de tipo .stl, .fbx, o .gltf, envía el archivo como model_url en su lugar).
  
  unknown: no se pudo medir el modelo. Si la propia comprobación de grosor de pared falla, la tarea termina en FAILED.
- Name
  evaluated_at
  Type
  timestamp
  Description
  Marca de tiempo de cuándo se calculó el análisis, en milisegundos desde el epoch.
Name
consumed_credits
Type
integer
Description
Siempre 0. Este endpoint es gratuito.

The Analyze Printability Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}

The Analyze Printability Task Object (wall thickness checked)

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000012000,
  "expires_at": 1715725412000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "error",
    "issue_count": 2,
    "error_count": 1,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "intended_print": {
      "printer_type": "sla",
      "height_mm": 100,
      "longest_side_mm": 118,
      "wall_thickness_mm": 0.8,
      "dimensions_mm": [118, 72.41, 99.87]
    },
    "thin_walls": {
      "thin_area_ratio": 0.083,
      "has_thin_walls": true,
      "status": "error"
    },
    "evaluated_at": 1700000012000
  },
  "consumed_credits": 0
}