API de Reparar Imprimibilidad

Reparar un modelo 3D para la imprimibilidad FDM — arreglar 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 una 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 a través de model_url, el model_urls.stl de la respuesta contendrá la malla reparada y los otros campos de formato estarán vacíos. La ruta input_task_id siempre lee el GLB de la tarea fuente, por lo que la salida es .glb.

Parámetros

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

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

Name
input_task_id
Type
string
Requerido
Description
El ID de una tarea exitosa que posees. Tipos de tareas soportadas: 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 asset GLB.

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

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

Retornos

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

Modos de Fallo

Name
400 - Bad Request
Description
La solicitud fue inaceptable. 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 soportado, o tiene una extensión de archivo no soportada.
- 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.
- GLB faltante: la tarea referenciada no tiene un asset GLB para reparar.
Name
401 - Unauthorized
Description
La autenticación falló. 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. Mejora 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 es propiedad de un usuario diferente.
Name
429 - Too Many Requests
Description
Has excedido tu cuota de tareas pendientes o 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 a recuperar.

Retornos

El Objeto de Tarea de Reparar Imprimibilidad. El bloque model_urls está vacío hasta que la tarea alcanza SUCCEEDED. Solo el campo model_urls que coincide con el formato de entrada está poblado.

Solicitud

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

Respuesta

{
  "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 a eliminar.

Retornos

Devuelve 200 OK en caso de éxito.

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

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

Retornos

Devuelve una transmisión de Objetos de Tarea de Reparar Imprimibilidad como Server-Sent Events.

Para tareas PENDING o IN_PROGRESS, la transmisión de respuesta solo incluirá los campos necesarios de 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=***",
    "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 la Tarea de Reparar Imprimibilidad

Name
id
Type
string
Description
Identificador único para 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
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
model_urls
Type
object
Description
URLs descargables para el modelo 3D reparado. Solo el campo que coincide con el formato de entrada está poblado; los otros campos de formato son cadenas vacías.
- Name
  glb
  Type
  string
  Description
  URL descargable para el GLB reparado. Poblado cuando la entrada fue un GLB o cuando se usó input_task_id.
- Name
  gltf
  Type
  string
  Description
  URL descargable para el GLTF reparado. Poblado cuando la entrada fue una carga de GLTF.
- Name
  fbx
  Type
  string
  Description
  URL descargable para el FBX reparado. Poblado cuando la entrada fue una carga de FBX.
- Name
  obj
  Type
  string
  Description
  URL descargable para el OBJ reparado. Poblado cuando la entrada fue una carga de OBJ.
- Name
  stl
  Type
  string
  Description
  URL descargable para el STL reparado. Poblado cuando la entrada fue una carga de STL.
- Name
  usdz
  Type
  string
  Description
  Reservado para salida USDZ. Siempre una cadena vacía para tareas de reparar imprimibilidad.
- Name
  3mf
  Type
  string
  Description
  Reservado para salida 3MF. Siempre una cadena vacía para tareas de reparar imprimibilidad.
- Name
  mtl
  Type
  string
  Description
  Reservado para salida MTL. Siempre una cadena vacía para tareas de reparar imprimibilidad.
Name
thumbnail_url
Type
string
Description
URL de una imagen de vista previa renderizada desde el modelo reparado.
Name
alpha_thumbnail_url
Type
string
Description
URL descargable para una versión con fondo transparente (RGBA) de thumbnail_url. Solo presente cuando la tarea fue creada con alpha_thumbnail: true y la vista previa transparente fue renderizada exitosamente; de lo contrario, este campo se omite.
Name
texture_urls
Type
array
Description
Siempre un arreglo vacío. La reparación preserva 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).

El Objeto de la Tarea de Reparar Imprimibilidad

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