API de Reparar imprimibilidad

Repara un modelo 3D para la imprimibilidad FDM — corrige aristas non-manifold, caras degeneradas, agujeros y otros problemas de topology para que la malla esté lista para imprimir.

POST/openapi/v1/print/repair

Crear una tarea de reparación de imprimibilidad

Este endpoint crea una nueva tarea de reparación de imprimibilidad. La tarea ejecuta una reparación de topology en un modelo 3D y devuelve una versión estanca (watertight) y lista para imprimir.

El formato de salida coincide con el formato de entrada. Si envías un .stl mediante model_url, el campo model_urls.stl de la respuesta contendrá la malla reparada y los demás campos de formato quedarán vacíos. El input_task_id de la ruta siempre lee el GLB de la tarea de origen, por lo que la salida es .glb.

Parámetros

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

Las texturas existentes se eliminan durante la reparación debido a los cambios de geometría. Para volver a añadir texturas, usa la API de Retexturizar sobre el modelo reparado.

  • Name
    model_url
    Type
    string
    Requerido
    Description

    URL de un modelo 3D a reparar. Formatos admitidos: .glb, .gltf, .obj, .fbx, .stl. Tamaño máximo de archivo: 100 MB. Debe usar http, https, o una URL data: (las URLs de datos omiten las verificaciones de extensión).

  • Name
    alpha_thumbnail
    Type
    boolean
    predeterminado false
    Description

    Cuando se establece en true, la tarea además renderiza una versión con fondo transparente (RGBA) de la vista previa y la devuelve como alpha_thumbnail_url en la respuesta GET. El campo existente thumbnail_url no cambia.

Devuelve

La propiedad result de la respuesta contiene el id de la tarea de reparación 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 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 superó los 100 MB.
    • Tarea no completada: la tarea referenciada aún está pendiente, en progreso o ha fallado.
    • GLB faltante: la tarea referenciada no tiene un asset GLB para reparar.
  • Name
    401 - Unauthorized
    Description

    Falló la autenticación. Por favor, verifica tu clave de API.

  • Name
    402 - Payment Required
    Description

    Causas comunes:

    • Plan gratuito: la creación de tareas requiere un plan de pago. Actualiza en la página de suscripción.
    • Créditos insuficientes: se alcanzó el límite de créditos del espacio de trabajo.
  • Name
    404 - Not Found
    Description

    La tarea referenciada no existe o pertenece a otro usuario.

  • Name
    429 - Too Many Requests
    Description

    Has superado tu cuota de tareas pendientes o el límite de tasa.

Request

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

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

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}
GET/openapi/v1/print/repair/:id

Recuperar una tarea de reparación de imprimibilidad

Este endpoint recupera una tarea de reparación de imprimibilidad por su ID.

Parámetros

  • Name
    id
    Type
    path
    Description

    El ID de la tarea de reparación de imprimibilidad a recuperar.

Devuelve

El Objeto de tarea de reparación de imprimibilidad. El bloque model_urls está vacío hasta que la tarea alcanza SUCCEEDED. Solo se rellena el campo de model_urls que coincide con el formato de entrada.

Request

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-repair",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1715725401000,
  "task_error": null,
  "model_urls": {
    "glb": "",
    "gltf": "",
    "fbx": "",
    "obj": "",
    "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}
DELETE/openapi/v1/print/repair/:id

Eliminar una tarea de Reparar imprimibilidad

Este endpoint elimina permanentemente una tarea de reparar imprimibilidad y su resultado reparado. Esta acción es irreversible.

Parámetros de ruta

  • Name
    id
    Type
    path
    Description

    El ID de la tarea de reparar 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á IN_PROGRESS no se puede eliminar: la solicitud se rechaza con 409 Conflict y la tarea sigue ejecutándose. Los créditos de una tarea que el worker ya ha iniciado no son reembolsables, por lo que eliminarla a mitad de ejecución te haría perder 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/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/print/repair/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/repair

Listar tareas de reparar imprimibilidad

Este endpoint le permite recuperar una lista de tareas de reparar 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 de 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 reparar imprimibilidad.

Request

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-repair",
    "status": "SUCCEEDED",
    "progress": 100,
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000030000,
    "expires_at": 1715725401000,
    "task_error": null,
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "gltf": "",
      "fbx": "",
      "obj": "",
      "stl": "",
      "usdz": "",
      "3mf": "",
      "mtl": ""
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
    "texture_urls": [],
    "consumed_credits": 10
  }
]
GET/openapi/v1/print/repair/:id/stream

Transmitir una Tarea de Reparar Imprimibilidad

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

Parámetros

  • Name
    id
    Type
    path
    Description

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

Devuelve

Devuelve un flujo de Objetos de Tarea de Reparar Imprimibilidad como Server-Sent Events.

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

Request

GET
/openapi/v1/print/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream
curl -N https://api.meshy.ai/openapi/v1/print/repair/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-repair",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1715725401000,
  "task_error": null,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.glb?Expires=***",
    "gltf": "",
    "fbx": "",
    "obj": "",
    "stl": "",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}

El objeto de tarea Reparar 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 debes hacer suposiciones sobre el formato del id.

  • Name
    type
    Type
    string
    Description

    Tipo de la tarea de reparar imprimibilidad. El valor es print-repair.

  • 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, esta 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 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 expirará el resultado de la tarea 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. Consulta Errores para más detalles.

    • Name
      message
      Type
      string
      Description

      Mensaje de error que describe qué salió mal.

  • Name
    model_urls
    Type
    object
    Description

    URLs descargables al modelo 3D reparado. Solo se rellena el campo que coincide con el formato de entrada; los demás campos de formato quedan como cadenas vacías.

    • Name
      glb
      Type
      string
      Description

      URL descargable al GLB reparado. Se rellena cuando la entrada fue un GLB o cuando se usó input_task_id.

    • Name
      gltf
      Type
      string
      Description

      URL descargable al GLTF reparado. Se rellena cuando la entrada fue una carga de GLTF.

    • Name
      fbx
      Type
      string
      Description

      URL descargable al FBX reparado. Se rellena cuando la entrada fue una carga de FBX.

    • Name
      obj
      Type
      string
      Description

      URL descargable al OBJ reparado. Se rellena cuando la entrada fue una carga de OBJ.

    • Name
      stl
      Type
      string
      Description

      URL descargable al STL reparado. Se rellena cuando la entrada fue una carga de STL.

    • Name
      usdz
      Type
      string
      Description

      Reservado para la salida en USDZ. Siempre es una cadena vacía para las tareas de reparar imprimibilidad.

    • Name
      3mf
      Type
      string
      Description

      Reservado para la salida en 3MF. Siempre es una cadena vacía para las tareas de reparar imprimibilidad.

    • Name
      mtl
      Type
      string
      Description

      Reservado para la salida en MTL. Siempre es una cadena vacía para las tareas de reparar imprimibilidad.

  • Name
    thumbnail_url
    Type
    string
    Description

    URL de una imagen de vista previa renderizada a partir del modelo reparado.

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    URL descargable a una versión con fondo transparente (RGBA) de thumbnail_url. Solo está presente cuando la tarea se creó con alpha_thumbnail: true y la vista previa transparente se renderizó correctamente; en caso contrario, este campo se omite.

  • Name
    texture_urls
    Type
    array
    Description

    Siempre es un array vacío. La reparación conserva únicamente la geometría de entrada y no vuelve a generar las texturas.

  • Name
    consumed_credits
    Type
    integer
    Description

    El número de créditos consumidos por esta tarea. 10 una vez que la tarea ha alcanzado SUCCEEDED. Devuelve 0 para las tareas FAILED (los créditos se reembolsan en caso de fallo).

The Repair Printability Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-repair",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1715725401000,
  "task_error": null,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "gltf": "",
    "fbx": "",
    "obj": "",
    "stl": "",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}