API de impresión multicolor

Convertir modelos 3D a formato 3MF multicolor para impresión 3D, con una paleta de colores configurable de hasta 16 colores.

POST/openapi/v1/print/multi-color

Crear una tarea de impresión 3D multicolor

Este endpoint crea una nueva tarea de impresión 3D multicolor. La tarea convierte un modelo 3D en un archivo 3MF multicolor apto para impresión 3D.

Parámetros

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

Name
input_task_id
Type
string
Requerido
Description
El ID de una tarea completada correctamente para usar como entrada. 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.

Name
model_url
Type
string
Requerido
Description
URL públicamente accesible o Data URI de un modelo 3D. Actualmente admitimos los formatos .glb y .fbx.

Name
max_colors
Type
integer
predeterminado 4
Description
Número máximo de colores en la paleta de salida.
Rango válido: de 1 a 16.
Name
max_depth
Type
integer
predeterminado 4
Description
Profundidad del quadtree para la precisión del color. Los valores más altos producen límites de color más precisos, pero aumentan el tamaño del archivo.
Rango válido: de 3 a 6.

Devuelve

La propiedad result de la respuesta contiene el id de la tarea de impresión 3D recién creada.

Modos de fallo

Name
400 - Bad Request
Description
La solicitud no fue aceptable. Causas comunes:
- Parámetro faltante: Se debe proporcionar model_url o input_task_id.
- Formato de modelo no válido: model_url apunta a un archivo con una extensión no compatible (solo se admiten .glb y .fbx).
- URL inaccesible: No se pudo descargar model_url.
- Tarea de entrada no válida: input_task_id debe hacer referencia a una tarea exitosa.
- max_colors no válido: El valor debe estar entre 1 y 16.
- max_depth no válido: El valor debe estar entre 3 y 6.
Name
401 - Unauthorized
Description
Falló la autenticación. Comprueba tu clave de API.
Name
402 - Payment Required
Description
Créditos insuficientes para realizar esta tarea.
Name
429 - Too Many Requests
Description
Has superado tu límite de tasa.

Request

POST

/openapi/v1/print/multi-color

# Convert a 3D model to multi-color 3MF for printing
curl https://api.meshy.ai/openapi/v1/print/multi-color \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "max_colors": 8,
    "max_depth": 5
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

GET/openapi/v1/print/multi-color/:id

Recuperar una tarea de impresión 3D multicolor

Este endpoint recupera una tarea de impresión 3D multicolor por su ID.

Parámetros

Name
id
Type
path
Description
El ID de la tarea de impresión 3D que se va a recuperar.

Devuelve

El objeto de tarea de impresión 3D.

Request

GET

/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-multi-color",
  "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}

DELETE/openapi/v1/print/multi-color/:id

Eliminar una tarea de impresión 3D multicolor

Este endpoint elimina permanentemente una tarea de impresión 3D multicolor, incluidos todos los modelos y datos asociados. Esta acción es irreversible.

Parámetros de ruta

Name
id
Type
path
Description
El ID de la tarea de impresión 3D multicolor que se desea eliminar.

Devoluciones

Devuelve 200 OK si se realiza correctamente.

Request

DELETE

/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f

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

Response

// Returns 200 Ok on success.

GET/openapi/v1/print/multi-color

Listar tareas de impresión 3D multicolor

Este endpoint te permite recuperar una lista de tareas de impresión 3D multicolor.

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 del 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 los objetos de tarea de impresión 3D.

Request

GET

/openapi/v1/print/multi-color

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-multi-color",
    "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null,
  "consumed_credits": 10
  }
]

GET/openapi/v1/print/multi-color/:id/stream

Transmitir una tarea de impresión 3D multicolor

Este endpoint transmite actualizaciones en tiempo real para una tarea de impresión 3D multicolor mediante Eventos enviados por el servidor (SSE).

Parámetros

Name
id
Type
path
Description
Identificador único de la tarea de impresión 3D multicolor que se va a transmitir.

Devuelve

Devuelve un flujo de Los objetos de tarea de impresión 3D como Eventos enviados por el servidor.

Para las tareas PENDING o IN_PROGRESS, el flujo de respuesta solo incluirá los campos necesarios progress y status.

Request

GET

/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream

curl -N https://api.meshy.ai/openapi/v1/print/multi-color/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-multi-color",
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.3mf?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}

El objeto de tarea de impresión 3D

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 impresión 3D. El valor es print-multi-color.
Name
model_urls
Type
object
Description
URL descargable al archivo de modelo 3D generado por Meshy. La propiedad de un formato se omitirá si no se genera el formato, en lugar de devolver una cadena vacía.
- Name
  3mf
  Type
  string
  Description
  URL descargable al archivo 3MF multicolor.
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
status
Type
string
Description
Estado de la tarea. Los valores posibles son uno de PENDING, IN_PROGRESS, SUCCEEDED, FAILED.
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
task_error
Type
object
Description
Detalles del error para las tareas fallidas. Consulta Errores para ver la referencia completa del objeto task_error.
Name
consumed_credits
Type
integer
Description
La cantidad de créditos consumidos por esta tarea. Presente cuando el estado de la tarea es PENDING, IN_PROGRESS o SUCCEEDED. Devuelve 0 para tareas FAILED (los créditos se reembolsan en caso de fallo).

The 3D Print Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-multi-color",
  "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}