API de Analizar imprimibilidad

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

POST/openapi/v1/print/analyze

Crear una tarea de Analizar 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.

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

Parámetros

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

  • Name
    input_task_id
    Type
    string
    Requerido
    Description

    El ID de una tarea completada correctamente de tu propiedad. Tipos de tareas compatibles: Imagen a 3D, Multi-imagen a 3D, Texto a 3D, Remallado y Retexturizar. La tarea debe usar Meshy 6 (o cualquier modelo Preview) y debe tener un estado de SUCCEEDED.

  • Name
    model_url
    Type
    string
    Requerido
    Description

    URL de un modelo 3D para analizar. Formatos compatibles: .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 era 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 compatible o tiene una extensión de archivo no compatible.
    • Archivo de modelo demasiado grande: el cuerpo de model_url superó los 100 MB.
    • Tarea no completada correctamente: la tarea referenciada aún está pendiente, en progress o ha fallado.
  • Name
    401 - Unauthorized
    Description

    La autenticación falló. Comprueba tu clave de API.

  • Name
    403 - Forbidden
    Description

    La tarea existe, pero pertenece a un usuario diferente.

  • 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 el 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 va a recuperar.

Devuelve

El objeto de tarea de Analizar imprimibilidad. El campo printability es null hasta que la tarea alcanza 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 Analizar imprimibilidad y su resultado en caché. Esta acción es irreversible.

Parámetros de ruta

  • Name
    id
    Type
    path
    Description

    El ID de la tarea de Analizar imprimibilidad que se va a eliminar.

Devuelve

Devuelve 200 OK en caso de éxito.

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

// Returns 200 Ok on success.
GET/openapi/v1/print/analyze

Listar tareas de Analizar imprimibilidad

Este endpoint te 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 tiene el valor predeterminado 1.

  • Name
    page_size
    Type
    integer
    Description

    Límite de tamaño de página. El valor predeterminado es 10 elementos. El máximo permitido es 50 elementos.

  • Name
    sort_by
    Type
    string
    Description

    Campo por el que 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 en streaming una tarea de Analizar imprimibilidad

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

Parámetros

  • Name
    id
    Type
    path
    Description

    Identificador único de la tarea de Analizar imprimibilidad que se va a transmitir.

Devuelve

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

Para tareas PENDING o IN_PROGRESS, el flujo de respuesta solo incluirá los campos necesarios progress y status. El bloque printability se envía únicamente cuando la tarea alcanza 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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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 de tarea de Analizar imprimibilidad

  • Name
    id
    Type
    string
    Description

    Identificador único de la tarea. Aunque usamos un UUID ordenable por k para los ids de tarea 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 finalizado correctamente, pasará a ser 100.

  • Name
    preceding_tasks
    Type
    integer
    Description

    El recuento 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 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 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 de error si la tarea ha fallado. Esta propiedad es null si la tarea no ha fallado. Consulta Errores para obtener más detalles.

    • Name
      message
      Type
      string
      Description

      Mensaje de error que describe qué salió mal.

  • Name
    printability
    Type
    object
    Description

    Resultado de 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 ni 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 estanco, 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 sin procesar 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

        Recuento de aristas non-manifold.

      • Name
        degenerate_faces
        Type
        integer
        Description

        Recuento de caras degeneradas (caras de área cero o no válidas).

      • Name
        holes
        Type
        integer
        Description

        Recuento 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 la época Unix.

  • 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
}