API de Analizar imprimibilidad

Analiza un modelo 3D para determinar su imprimibilidad FDM — estanqueidad, volumen, agujeros, aristas non-manifold y caras degeneradas.

POST/openapi/v1/print/analyze

Create an Analyze Printability Task

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.

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.

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 posterior (incluido Meshy 7) y debe tener un estado SUCCEEDED.

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).

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ó ni input_task_id ni model_url.
- UUID no válido: input_task_id no es un UUID válido.
- URL de modelo no válida: model_url está mal formada, 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.
- Tarea no exitosa: la tarea referenciada aún está pendiente, en progreso o falló.
Name
401 - Unauthorized
Description
Error de autenticación. Verifica 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 asset 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"
  }'

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.

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
}

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
}

El Objeto Task de Analizar imprimibilidad

Name
id
Type
string
Description
Identificador único de la tarea. Aunque usamos un UUID k-sortable para los ids de tareas como detalle de implementación, no debe 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
Progreso de la tarea. Si la tarea aún no ha comenzado, esta propiedad será 0. Una vez que la tarea haya finalizado con éxito, esto se convertirá en 100.
Name
preceding_tasks
Type
integer
Description
El número de tareas precedentes.
El valor de este campo solo es significativo 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 se ha iniciado, 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 el resultado de la tarea expirará del 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. Consulte 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.
- 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 de error. Los errores se generan cuando el modelo no es watertight, tiene volumen no positivo, o tiene aristas non-manifold.
- Name
  warning_count
  Type
  integer
  Description
  Número de problemas de nivel de advertencia. Las advertencias se generan cuando el modelo contiene caras degeneradas o agujeros.
- Name
  metrics
  Type
  object
  Description
  Métricas de geometría en bruto devueltas por el evaluador.
  Name
  is_watertight
  Type
  boolean
  Description
  true cuando la malla no tiene aristas de contorno (es decir, está cerrada).
  Name
  volume
  Type
  number
  Description
  Volumen del modelo en metros cúbicos.
  Name
  non_manifold_edges
  Type
  integer
  Description
  Número de aristas non-manifold.
  Name
  degenerate_faces
  Type
  integer
  Description
  Número de caras degeneradas (caras de área cero o inválidas).
  Name
  holes
  Type
  integer
  Description
  Número de agujeros (bucles de contorno) en la malla.
- 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
}