API de Analizar Imprimibilidad

Analizar 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 analizar 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á inmediatamente lista y el primer GET sobre ella devolverá el resultado del análisis sin pasar por el trabajador.

Parámetros

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

  • 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 del archivo: 100 MB. Debe usar http, https, o una URL data: (las URLs de datos evitan las verificaciones de extensión).

Retornos

La propiedad result de la respuesta contiene el id de la nueva tarea de analizar imprimibilidad creada.

Modos de Fallo

  • Name
    400 - Bad Request
    Description

    La solicitud fue inaceptable. Causas comunes:

    • Parámetro faltante: ni input_task_id ni model_url fueron proporcionados.
    • UUID inválido: input_task_id no es un UUID válido.
    • URL de modelo invá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 excedió los 100 MB.
    • Tarea no exitosa: la tarea referenciada aún está pendiente, en progreso, o fallida.
  • Name
    401 - Unauthorized
    Description

    La autenticación falló. Por favor, verifica tu clave de API.

  • Name
    403 - Forbidden
    Description

    La tarea existe pero es propiedad de 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 modo no produce un activo 3D.
    • El archivo de modelo subyacente ya no está disponible en el almacenamiento.
  • Name
    429 - Too Many Requests
    Description

    Has excedido tu cuota de tareas pendientes o 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 a recuperar.

Retorna

El Objeto de Tarea de Analizar Imprimibilidad. El campo imprimibilidad 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 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 analizar imprimibilidad.

Parámetros

Atributos opcionales

  • Name
    page_num
    Type
    integer
    Description

    Número de página para 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 50 elementos.

  • Name
    sort_by
    Type
    string
    Description

    Campo para ordenar. Valores disponibles:

    • +created_at: Ordenar por tiempo de creación en orden ascendente.
    • -created_at: Ordenar por tiempo de creación en orden descendente.

Retornos

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 para la tarea de analizar imprimibilidad a transmitir.

Retornos

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 solo una vez que 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 la Tarea Analizar Imprimibilidad

  • Name
    id
    Type
    string
    Description

    Identificador único para la tarea. Aunque usamos un UUID k-sortable 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

    Progreso de la tarea. Si la tarea aún no ha comenzado, esta propiedad será 0. Una vez que la tarea haya tenido éxito, esto se convertirá en 100.

  • Name
    preceding_tasks
    Type
    integer
    Description

    El conteo de tareas precedentes.

    El valor de este campo es significativo solo si el estado de la tarea es PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Marca de tiempo de cuando la tarea fue creada, en milisegundos.

  • Name
    started_at
    Type
    timestamp
    Description

    Marca de tiempo de cuando la tarea fue iniciada, en milisegundos. Si la tarea aún no ha comenzado, esta propiedad será 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Marca de tiempo de cuando la tarea fue finalizada, en milisegundos. Si la tarea aún no ha finalizado, esta propiedad será 0.

  • Name
    expires_at
    Type
    timestamp
    Description

    Marca de tiempo de cuando 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 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: el modelo no pudo ser analizado.
    • Name
      issue_count
      Type
      integer
      Description

      Conteo total de problemas, igual a error_count + warning_count.

    • Name
      error_count
      Type
      integer
      Description

      Número de problemas a nivel de error. Se generan errores cuando el modelo no es hermético, tiene volumen no positivo, o tiene aristas non-manifold.

    • Name
      warning_count
      Type
      integer
      Description

      Número de problemas a nivel de advertencia. Se generan advertencias cuando el modelo contiene caras degeneradas o agujeros.

    • Name
      metrics
      Type
      object
      Description

      Métricas de geometría cruda devueltas por el evaluador.

      • Name
        is_watertight
        Type
        boolean
        Description

        true cuando la malla no tiene aristas de borde (es decir, está cerrada).

      • Name
        volume
        Type
        number
        Description

        Volumen del modelo en metros cúbicos.

      • Name
        non_manifold_edges
        Type
        integer
        Description

        Conteo de aristas non-manifold.

      • Name
        degenerate_faces
        Type
        integer
        Description

        Conteo de caras degeneradas (caras de área cero o inválidas).

      • Name
        holes
        Type
        integer
        Description

        Conteo de agujeros (bucles de borde) en la malla.

    • Name
      evaluated_at
      Type
      timestamp
      Description

      Marca de tiempo de cuando se realizó el análisis, en milisegundos desde la época.

  • Name
    consumed_credits
    Type
    integer
    Description

    Siempre 0. Este endpoint es gratuito.

El Objeto de la Tarea Analizar Imprimibilidad

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