API de Impresión Multicolor

Convierte modelos 3D al 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 adecuado 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 exitosa para usar como entrada. Tipos de tareas admitidos: Imagen a 3D, Multi-imagen a 3D, Texto a 3D, Remallado y Retexturizar. La tarea debe tener un estado SUCCEEDED.

Name
model_url
Type
string
Requerido
Description
URL de acceso público 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: 1 a 16.
Name
style
Type
string
predeterminado realistic
Description
Estilo visual de color del archivo 3MF generado.
Valores disponibles:
- realistic: Muestrea los colores directamente de la textura del modelo para obtener un detalle fino y fotorrealista. Produce un archivo más grande.
- cartoon: Aplana los colores en regiones uniformes y limpias para lograr un aspecto estilizado. Produce un archivo más pequeño.
La entrada debe contener color: realistic requiere una única textura de color base con coordenadas UV en cada parte de la malla; cartoon también acepta colores por vértice. Los modelos sin textura (blancos) son rechazados; consulte model_missing_texture.

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 fue inaceptable. 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.
- style no válido: El valor debe ser realistic o cartoon.
- Sin fuente de color: El modelo de entrada no tiene textura de color base (realistic necesita una única textura, con UVs, en cada parte de la malla) ni colores de vértice (cartoon acepta cualquiera de los dos). Aplique textura al modelo primero, o use cartoon para modelos con color por vértice. Las cargas .fbx se verifican después de que la tarea las normaliza y fallan con model_missing_texture en su lugar.
Name
401 - Unauthorized
Description
Error de autenticación. Verifique su clave de API.
Name
402 - Payment Required
Description
Créditos insuficientes para realizar esta tarea.
Name
429 - Too Many Requests
Description
Ha excedido su 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
  }'

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 la 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, incluyendo 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 va a eliminar.

Estado de la tarea

Una tarea que aún está 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 en ejecución. Los créditos de una tarea que el worker ya ha comenzado no son reembolsables, por lo que eliminarla a mitad de ejecución te costaría 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á IN_PROGRESS.

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

// 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/multi-color

Listar Tareas de Impresión 3D Multicolor

Este endpoint le 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 y tiene como valor predeterminado 1.
Name
page_size
Type
integer
Description
Límite de tamaño de página. El valor predeterminado 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 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 de una tarea de impresión 3D multicolor mediante Server-Sent Events (SSE).

Parámetros

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

Devuelve

Devuelve un flujo de Los objetos de tarea de impresión 3D como Server-Sent Events.

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 Task de impresión 3D

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 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 del archivo de modelo 3D generado por Meshy. La propiedad de un formato se omitirá si el formato no se genera, en lugar de devolver una cadena vacía.
- Name
  3mf
  Type
  string
  Description
  URL descargable del archivo 3MF multicolor.
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 se haya completado con éxito, 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 número de tareas precedentes.
El valor de este campo solo tiene sentido 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 ha comenzado, 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
task_error
Type
object
Description
Detalles del error para tareas fallidas. Consulta Errores para ver la referencia completa del objeto task_error.
Name
consumed_credits
Type
integer
Description
El número 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
}