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 Reparar imprimibilidad

Este endpoint crea una nueva tarea de Reparar imprimibilidad. La tarea ejecuta reparación de topology en un modelo 3D y devuelve una versión hermética y lista para imprimir.

El formato de salida coincide con el formato de entrada. Si envías un .stl mediante model_url, el model_urls.stl de la respuesta contendrá la malla reparada y los demás campos de formato estarán vacíos. La ruta input_task_id 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 en el modelo reparado.

Name
input_task_id
Type
string
Requerido
Description
El ID de una tarea SUCCEEDED de tu propiedad. Tipos de tarea compatibles: Imagen a 3D, Multi-imagen a 3D, Texto a 3D, Remallado y Retexturizar. La tarea debe tener un estado de SUCCEEDED y debe haber producido un activo GLB.

Name
model_url
Type
string
Requerido
Description
URL de un modelo 3D para reparar. Formatos compatibles: .glb, .stl, .obj. 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).

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

Devuelve

La propiedad result de la respuesta contiene el id de la tarea de Reparar 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 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 SUCCEEDED: la tarea referenciada aún está pendiente, en progress o ha fallado.
- GLB faltante: la tarea referenciada no tiene ningún activo GLB para reparar.
Name
401 - Unauthorized
Description
La autenticación falló. Comprueba 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 un usuario diferente.
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 Reparar imprimibilidad

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

Parámetros

Name
id
Type
path
Description
El ID de la tarea de Reparar imprimibilidad que se va a recuperar.

Devuelve

El objeto de tarea de Reparar imprimibilidad. El bloque model_urls está vacío hasta que la tarea alcanza SUCCEEDED. Solo se completa el campo 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": "",
    "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 salida reparada. 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.

Devuelve

Devuelve 200 OK si se realiza correctamente.

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

// Returns 200 Ok on success.

GET/openapi/v1/print/repair

Listar tareas de Reparar imprimibilidad

Este endpoint te 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 en 1 y el valor predeterminado es 1.
Name
page_size
Type
integer
Description
Límite de tamaño de página. El valor predeterminado es de 10 elementos. El máximo permitido es de 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 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=***",
      "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 en streaming una tarea de Reparar imprimibilidad

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

Parámetros

Name
id
Type
path
Description
Identificador único de la tarea de Reparar imprimibilidad que se va a transmitir en streaming.

Devuelve

Devuelve un flujo de objetos de tarea de Reparar 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 model_urls se envía solo una vez que la tarea alcanza 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.
// 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-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=***",
    "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 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 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
progress de la tarea. Si la tarea aún no ha comenzado, esta propiedad será 0. Una vez que la tarea se haya completado 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 cuando se creó la tarea, en milisegundos.
Name
started_at
Type
timestamp
Description
Marca de tiempo de cuando 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 cuando 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 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
model_urls
Type
object
Description
URL descargables al modelo 3D reparado. Solo se rellena el campo que coincide con el formato de entrada; los demás campos de formato son 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
  fbx
  Type
  string
  Description
  Reservado para la salida FBX. Siempre es una cadena vacía para tareas de reparar imprimibilidad.
- 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 USDZ. Siempre es una cadena vacía para tareas de reparar imprimibilidad.
- Name
  3mf
  Type
  string
  Description
  Reservado para la salida 3MF. Siempre es una cadena vacía para tareas de reparar imprimibilidad.
- Name
  mtl
  Type
  string
  Description
  Reservado para la salida MTL. Siempre es una cadena vacía para 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; de lo contrario, este campo se omite.
Name
texture_urls
Type
array
Description
Siempre es un arreglo vacío. La reparación conserva solo la geometría de entrada y no vuelve a hornear 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 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=***",
    "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
}