API de Impresión Multicolor

Convertir modelos 3D en 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 uno de input_task_id o model_url es requerido. 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 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 soportamos 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: Muestra colores directamente de la textura del modelo para un detalle fino y foto-realista. Produce un archivo más grande.
- cartoon: Aplana los colores en regiones limpias y uniformes para un aspecto estilizado. Produce un archivo más pequeño.

Retornos

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 inválido: El model_url apunta a un archivo con una extensión no soportada (solo se soportan .glb y .fbx).
- URL inalcanzable: No se pudo descargar el model_url.
- Tarea de entrada inválida: El input_task_id debe referirse a una tarea exitosa.
- max_colors inválido: El valor debe estar entre 1 y 16.
- Estilo inválido: El valor debe ser realistic o cartoon.
Name
401 - Unauthorized
Description
La autenticación falló. Por favor, verifica tu clave de API.
Name
402 - Payment Required
Description
Créditos insuficientes para realizar esta tarea.
Name
429 - Too Many Requests
Description
Has excedido tu límite de tasa.

Solicitud

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

Respuesta

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

Devuelve

El objeto de la Tarea de Impresión 3D.

Solicitud

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

Respuesta

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

Retornos

Devuelve 200 OK en caso de éxito.

Solicitud

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

Respuesta

// 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 y por defecto es 1.
Name
page_size
Type
integer
Description
Límite del 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 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 utilizando Server-Sent Events (SSE).

Parámetros

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

Retornos

Devuelve un flujo de Los Objetos de Tarea de Impresión 3D como Server-Sent Events.

Para tareas PENDING o IN_PROGRESS, el flujo de respuesta solo incluirá los campos necesarios de 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 para la tarea. Aunque usamos un UUID k-sortable para los ids de tarea como detalle de implementación, no debes hacer suposiciones 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 para el archivo del modelo 3D generado por Meshy. La propiedad para 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 para el 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 haya tenido éxito, esto se convertirá en 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 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
task_error
Type
object
Description
Detalles del error para tareas fallidas. Consulta Errores para 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).

El Objeto de Tarea de Impresión 3D

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