API de Creative Lab Fidget Pixel

Convierte una foto en un tablero fidget de pixel art multicolor e imprimible en 3D en dos etapas. Una tarea de prototipo convierte la foto en una imagen de pixel art. Una tarea de construcción convierte esa imagen en piezas interconectadas en un único archivo 3MF, y toma el ID de la tarea de prototipo como input_task_id.

POST /openapi/creative-lab/fidget-pixel/v1/prototype
POST /openapi/creative-lab/fidget-pixel/v1/build

Ambos endpoints POST requieren un plan de pago. Una solicitud desde una cuenta con plan gratuito devuelve 402.

POST/openapi/creative-lab/fidget-pixel/v1/prototype

Crear una tarea de prototipo de Fidget Pixel

Genera una imagen de pixel art a partir de una foto. Para construir las piezas, pasa el ID de esta tarea al endpoint de construcción como input_task_id. Para conocer los campos de la tarea, consulta El objeto de tarea de prototipo de Fidget Pixel.

Si no te gusta la imagen, crea otra tarea de prototipo. Cada tarea se cobra por separado.

Request

POST

/openapi/creative-lab/fidget-pixel/v1/prototype

# Stage 1: pixelize the source photo
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/prototype \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>",
    "type": "person"
  }'

Response

{
  "result": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7"
}

Parámetros

Name
image_url
Type
string
Requerido
Description
La foto que se convertirá en pixel art, como URL pública o como data URI (data:image/jpeg;base64,<tus datos de imagen codificados en base64>).
La imagen debe ser un archivo JPG, JPEG, PNG o WebP de máximo 20 MB. Meshy detecta el formato a partir de los datos de la imagen, no de la extensión del archivo en la URL. Una URL sin extensión funciona, y Meshy sigue las redirecciones.
Name
type
Type
string
Requerido
Description
Lo que muestra la foto, que determina el estilo del pixel art. Los dos estilos se ven claramente diferentes. Cualquier otro valor devuelve 400.
Valores disponibles:
- person: una persona, en un retrato o una foto de cuerpo completo. Meshy dibuja un sprite de pixel art estilo chibi.
- other: cualquier otro sujeto, por ejemplo una mascota, un objeto, un mascot, un logotipo o un paisaje. Meshy dibuja un icono de pixel art estilo bead-art.
Name
name
Type
string
Description
Un nombre para la tarea, de hasta 100 caracteres. Se devuelve en el campo name de la tarea. Un nombre más largo devuelve 400.

Devuelve

El campo result contiene el ID de la nueva tarea de prototipo. Obtén la tarea o transmítela en streaming hasta que status sea SUCCEEDED. Luego pasa el ID al endpoint de construcción como input_task_id.

Modos de error

Name
400 - Bad Request
Description
La solicitud no se puede ejecutar. Por ejemplo:
- Falta image_url o type.
- type no es person ni other.
- La imagen no es un archivo JPG, JPEG, PNG o WebP.
- La imagen es demasiado pequeña, supera los 20 MB, o supera el número máximo de píxeles.
- Meshy no puede descargar la imagen, por ejemplo porque la URL devuelve 404 o se agota el tiempo de espera.
- El data URI no es un base64 válido.
- La imagen fue marcada como NSFW.
El mensaje de error indica qué problema encontró. Corrige la solicitud y envíala de nuevo.
Name
401 - Unauthorized
Description
Falta la clave de API o no es válida. Revisa el encabezado Authorization.
Name
402 - Payment Required
Description
Se aplica uno de los siguientes casos:
- La cuenta no tiene suficientes créditos.
- La clave de API, el espacio de trabajo o el miembro alcanzó su límite de créditos.
- La cuenta está en el plan gratuito.
Revisa tus créditos y tu plan, luego vuelve a intentarlo.
Name
403 - Forbidden
Description
Tu equipo tiene activado IP Filtering, y Meshy marcó la imagen por propiedad intelectual de terceros. Envía una imagen sobre la que tengas los derechos de uso.
Name
429 - Too Many Requests
Description
Se alcanzó uno de estos límites:
- Enviaste más solicitudes de las que permite tu límite de tasa. Espera unos segundos y vuelve a intentarlo. Consulta Límites de tasa.
- Hay demasiadas tareas tuyas en cola o en ejecución. Espera a que terminen algunas y vuelve a intentarlo.
- En un plan ilimitado sin créditos restantes, alcanzaste el número de tareas que pueden ejecutarse sin créditos. Espera a que termine una tarea, o añade créditos.
Name
500 - Internal Server Error
Description
Meshy encontró un error de servidor, por ejemplo porque no pudo ejecutar la verificación de propiedad intelectual sobre la imagen. Meshy no crea la tarea y reembolsa cualquier crédito cobrado. Vuelve a intentar la solicitud.

POST/openapi/creative-lab/fidget-pixel/v1/build

Crear una tarea de construcción de Fidget Pixel

Genera las piezas imprimibles en 3D a partir de una tarea de prototipo exitosa. Meshy muestrea la imagen pixel-art en la cuadrícula y la reduce a un máximo de color_count colores. Cada celda del sujeto se convierte en una pieza entrelazable, y el fondo no se imprime.

El resultado es un único archivo 3MF multicolor, listo para imprimir en color. Cada pieza tiene un cuerpo gris y una parte superior en el color de su píxel. Para conocer sus campos, consulta El objeto de tarea de construcción de Fidget Pixel.

Request

POST

/openapi/creative-lab/fidget-pixel/v1/build

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
    "options": {
      "shape": "square",
      "grid_size": 32,
      "piece_size_mm": 8,
      "color_count": 8,
      "piece_height_mm": 15
    },
    "output": {
      "format": "3mf"
    }
  }'

Response

{
  "result": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98"
}

Parámetros

Name
input_task_id
Type
string
Requerido
Description
El ID de la tarea de prototipo a construir. Debe ser una tarea creada por tu cuenta con POST /openapi/creative-lab/fidget-pixel/v1/prototype, con el estado SUCCEEDED.
Un ID que no sea una de tus tareas de prototipo de Fidget Pixel de la API devuelve 404, incluyendo un prototipo creado en la aplicación web.
Name
name
Type
string
Description
Un nombre para la tarea, de hasta 100 caracteres. Aparece de vuelta en el campo name de la tarea. Un nombre más largo devuelve 400.

`options`

Configuraciones para la forma y el tamaño de las piezas. Cada campo tiene un valor predeterminado, así que envía solo los campos que quieras cambiar. Un 0 usa el valor predeterminado del campo. Son las mismas configuraciones que en la aplicación web de Creative Lab. Otras configuraciones de forma son fijas, y Meshy las establece a partir de shape y piece_size_mm.

Name
shape
Type
string
predeterminado square
Description
La forma de la base de cada pieza. Cualquier otro valor devuelve 400.
Valores disponibles:
- square: piezas cuadradas en una cuadrícula cuadrada
- hex: piezas hexagonales en una cuadrícula hexagonal, con piece_size_mm establecido en 6 u 8
Name
grid_size
Type
integer
predeterminado 32
Description
El número de celdas de la cuadrícula a lo largo de cada lado del tablero, 16 o 32. Cualquier otro valor devuelve 400. Una cuadrícula de 32 conserva más detalle. Una cuadrícula de 16 da menos piezas del mismo tamaño, por lo que el tablero tiene aproximadamente la mitad de ancho.
Name
piece_size_mm
Type
integer
predeterminado 8
Description
La longitud del borde de cada pieza en milímetros, 6, 8 o 10. Cualquier otro valor devuelve 400. Junto con grid_size, establece el tamaño del tablero impreso. Por ejemplo, una cuadrícula de 32 con piezas de 8 mm mide aproximadamente 26.5 cm por lado.
10 no funciona con hex y devuelve 400, porque la cara hexagonal inclinada sobresale en la mayoría de las impresoras FDM para consumidores.
Name
color_count
Type
integer
predeterminado 8
Description
El número máximo de colores en la paleta pixel-art, de 1 a 8. Un valor fuera del rango devuelve 400. Para imprimir, necesitas hasta color_count más uno filamentos, uno por color y uno para los cuerpos grises.
Name
piece_height_mm
Type
integer
predeterminado 15
Description
La altura de cada pieza en milímetros, de 10 a 80. Un valor fuera del rango devuelve 400.

`output`

Configuraciones para el archivo de resultado.

Name
format
Type
string
predeterminado 3mf
Description
El formato de archivo del resultado. Cualquier otro valor devuelve 400.
Valores disponibles:
- 3mf: un único archivo model.3mf multicolor, devuelto en model_urls.3mf

Devuelve

El campo result contiene el ID de la nueva tarea de construcción. Obtén la tarea o transmítela hasta que status sea SUCCEEDED. Luego descarga el archivo 3MF desde model_urls.3mf.

Modos de fallo

Name
400 - Bad Request
Description
La solicitud no puede ejecutarse. Por ejemplo:
- input_task_id falta o no es un ID de tarea válido.
- El estado de la tarea de prototipo no es SUCCEEDED. Si todavía se está ejecutando, espera y vuelve a intentarlo. Si falló o se canceló, crea una nueva tarea de prototipo.
- La tarea de prototipo tuvo éxito pero no tiene imagen. Crea una nueva tarea de prototipo.
- Un campo de options está fuera de sus valores permitidos, por ejemplo un grid_size distinto de 16 o 32.
- piece_size_mm es 10 y shape es hex. Las piezas hexagonales solo vienen en 6 y 8 mm.
- output.format no es 3mf.
El mensaje de error indica qué problema encontró.
Name
401 - Unauthorized
Description
Falta la clave de API o no es válida. Revisa el encabezado Authorization.
Name
402 - Payment Required
Description
Se aplica uno de estos casos:
- La cuenta no tiene suficientes créditos.
- La clave de API, el espacio de trabajo o el miembro alcanzó su límite de créditos.
- La cuenta está en el plan gratuito.
Revisa tus créditos y tu plan, luego vuelve a intentarlo.
Name
403 - Forbidden
Description
Tu equipo tiene Filtrado de IP activado, y Meshy marcó la imagen de la tarea de prototipo por propiedad intelectual de terceros. Crea una tarea de prototipo a partir de una imagen sobre la que tengas los derechos de uso.
Name
404 - Not Found
Description
input_task_id no coincide con ninguna tarea de prototipo de Fidget Pixel creada por tu cuenta con la API. Un prototipo creado en la aplicación web también devuelve 404. Envía el ID de result de una respuesta de creación de prototipo.
Name
429 - Too Many Requests
Description
Se alcanzó uno de estos límites:
- Enviaste más solicitudes de las que permite tu límite de tasa. Espera unos segundos y vuelve a intentarlo. Consulta Límites de tasa.
- Hay demasiadas tareas tuyas en cola o en ejecución. Espera a que algunas terminen y vuelve a intentarlo.
- En un plan ilimitado sin créditos restantes, alcanzaste el número de tareas que pueden ejecutarse sin créditos. Espera a que una tarea termine o agrega créditos.
Name
500 - Internal Server Error
Description
Meshy encontró un error de servidor, por ejemplo porque no pudo ejecutar la verificación de propiedad intelectual en la imagen de la tarea de prototipo. Meshy no crea la tarea y reembolsa cualquier crédito que haya cobrado. Vuelve a intentar la solicitud.

GET/openapi/creative-lab/fidget-pixel/v1/(prototype|build)/:id

Obtener una tarea de Fidget Pixel

Devuelve una tarea de prototipo o de construcción. La ruta debe coincidir con la etapa de la tarea. Una tarea de construcción solicitada a través de /prototype/:id devuelve 404, y lo mismo ocurre con una tarea de prototipo solicitada a través de /build/:id.

Para conocer los campos, consulta El objeto de tarea de prototipo de Fidget Pixel y El objeto de tarea de construcción de Fidget Pixel.

Request

GET

/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7

# Prototype
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
  "type": "creative-lab-fidget-pixel-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001000000,
  "started_at": 1757001005000,
  "finished_at": 1757001178000,
  "expires_at": 1757260378000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/pixel-art.jpg?Expires=***"
  ]
}

Build Response

{
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001300000,
  "started_at": 1757001304000,
  "finished_at": 1757001309000,
  "expires_at": 1757260509000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/output/model.3mf?Expires=***"
  }
}

Parámetros

Name
id
Type
path
Description
El ID de la tarea de la respuesta de creación.

Devuelve

El objeto de tarea de prototipo o el objeto de tarea de construcción, según la etapa indicada en la ruta.

Modos de fallo

Name
400 - Bad Request
Description
id no es un ID de tarea válido. Envía el ID result de la respuesta de creación.
Name
403 - Forbidden
Description
Tu equipo tiene activado el filtrado de IP, y Meshy marcó la imagen de la tarea de prototipo por propiedad intelectual de terceros. Las tareas de construcción y los equipos del plan Enterprise no reciben este error. Crea una tarea de prototipo a partir de una imagen sobre la que tengas derechos de uso.
Name
404 - Not Found
Description
Ninguna tarea de Fidget Pixel con este ID pertenece a tu cuenta, o la etapa de la tarea no coincide con la ruta. Revisa el ID y usa /prototype o /build para que coincida con la tarea.
Name
500 - Internal Server Error
Description
Meshy no pudo ejecutar la verificación de propiedad intelectual. Vuelve a intentar la solicitud.

DELETE/openapi/creative-lab/fidget-pixel/v1/(prototype|build)/:id

Eliminar una tarea de Fidget Pixel

Cancela una tarea de Fidget Pixel. Cancelar una tarea PENDING reembolsa sus créditos. Una tarea IN_PROGRESS se cancela sin reembolso, porque un worker ya la ha iniciado. No se puede cancelar una tarea con un estado final (SUCCEEDED, FAILED o CANCELED).

La ruta debe coincidir con la etapa de la tarea. Por ejemplo, DELETE en /prototype/:id con el ID de una tarea de build devuelve 404.

Request

DELETE

/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 204 No Content on success (empty body).

Parámetros de ruta

Name
id
Type
path
Description
El ID de la tarea a cancelar.

Devuelve

204 No Content con un cuerpo vacío.

Modos de fallo

Name
400 - Bad Request
Description
Se aplica uno de los siguientes casos:
- id no es un ID de tarea válido. Envía el ID result de la respuesta de creación.
- La tarea ya tiene un estado final (SUCCEEDED, FAILED o CANCELED), por lo que no se puede cancelar.
Name
404 - Not Found
Description
Ninguna tarea de Fidget Pixel con este ID pertenece a tu cuenta, o la etapa de la tarea no coincide con la ruta. Verifica el ID y usa /prototype o /build para que coincida con la tarea.

GET/openapi/creative-lab/fidget-pixel/v1/(prototype|build)/:id/stream

Transmitir una tarea de Fidget Pixel en streaming

Transmite las actualizaciones de una tarea de Fidget Pixel como eventos enviados por el servidor (SSE). La ruta debe coincidir con la etapa de la tarea. Si no coincide, por ejemplo el ID de una tarea de build en /prototype/:id/stream, el stream envía un evento error con status_code: 404 y se cierra. Un id que no sea un ID de tarea válido hace lo mismo con status_code: 400.

Request

GET

/openapi/creative-lab/fidget-pixel/v1/build/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/stream

curl -N https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (wrong stage or task not found)
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// Every frame is the full task object for the stage; fields not yet populated are null / empty.
event: message
data: {
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "name": "",
  "status": "PENDING",
  "progress": 0,
  "created_at": 1757001300000,
  "started_at": null,
  "finished_at": null,
  "expires_at": 1757260500000,
  "preceding_tasks": 2,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {}
}

event: message
data: {
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001300000,
  "started_at": 1757001304000,
  "finished_at": 1757001309000,
  "expires_at": 1757260509000,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/output/model.3mf?Expires=***"
  }
}

Parámetros

Name
id
Type
path
Description
El ID de la tarea proveniente de la respuesta de creación.

Devuelve

Un stream de objetos de tarea de prototype o build. Cada evento contiene el objeto de tarea completo, tal como lo devuelve Obtener una tarea de Fidget Pixel. Mientras la tarea está en PENDING o IN_PROGRESS, sus campos de salida siguen vacíos (null, [] o {}), y finished_at es null.

Si el filtrado de IP bloquea el resultado de la tarea, el stream envía un evento error en su lugar, con el status_code que devolvería una solicitud de obtención.

GET/openapi/creative-lab/fidget-pixel/v1/(prototype|build)

Listar tareas de Fidget Pixel

Devuelve tus tareas de Fidget Pixel de una etapa, una página a la vez. La ruta selecciona la etapa. /prototype devuelve solo tareas de prototipo, y /build devuelve solo tareas de compilación.

Request

GET

/openapi/creative-lab/fidget-pixel/v1/prototype

# List prototype tasks
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/prototype?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# List build tasks
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response (List Prototype Tasks)

[
  {
    "id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
    "type": "creative-lab-fidget-pixel-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1757001000000,
    "started_at": 1757001005000,
    "finished_at": 1757001178000,
    "expires_at": 1757260378000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/pixel-art.jpg?Expires=***"
    ]
  }
]

Parámetros de ruta

Name
stage
Type
path
Requerido
Description
La etapa a listar, prototype o build.

Parámetros de consulta

Name
page_num
Type
integer
predeterminado 1
Description
La página a devolver, de 1 a 255. 0 devuelve la primera página. Un valor fuera de 0 a 255 devuelve 400.
Name
page_size
Type
integer
predeterminado 10
Description
Número de tareas por página, hasta 100. Un valor de 101 a 255 devuelve 100 tareas, y 0 usa el valor predeterminado. Un valor fuera de 0 a 255 devuelve 400.
Name
sort_by
Type
string
predeterminado -created_at
Description
El orden de clasificación.
Valores disponibles:
- -created_at: más reciente primero
- +created_at: más antiguo primero

Devuelve

Un arreglo de objetos de tarea de prototipo u objetos de tarea de compilación, según coincida con la etapa en la ruta.

El objeto de tarea de prototipo de Fidget Pixel

Una tarea de prototipo convierte una foto en una imagen de arte de píxeles. Para convertir la imagen en piezas imprimibles en 3D, pasa el ID de la tarea al endpoint de build como input_task_id.

Propiedades

Example Fidget Pixel Prototype Task Object

{
  "id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
  "type": "creative-lab-fidget-pixel-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001000000,
  "started_at": 1757001005000,
  "finished_at": 1757001178000,
  "expires_at": 1757260378000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/pixel-art.jpg?Expires=***"
  ]
}

Name
id
Type
string
Description
El ID de la tarea. No dependas de su formato.
Name
type
Type
string
Description
El tipo de tarea, siempre creative-lab-fidget-pixel-prototype.
Name
name
Type
string
Description
El name que enviaste al crear la tarea, o "" si no enviaste uno.
Name
status
Type
string
Description
El estado de la tarea.
Valores disponibles:
- PENDING: esperando en la cola
- IN_PROGRESS: generando el resultado
- SUCCEEDED: final, con el resultado
- FAILED: final, con el motivo en task_error
- CANCELED: final, sin resultado
Name
progress
Type
integer
Description
Porcentaje del trabajo completado, de 0 a 100. Es 0 hasta que la tarea comienza y 100 cuando tiene éxito.
Name
created_at
Type
timestamp
Description
Momento en que se creó la tarea, en milisegundos Unix.
Name
started_at
Type
timestamp
Description
Momento en que un worker inició la tarea, en milisegundos Unix. null hasta entonces.
Name
finished_at
Type
timestamp
Description
Momento en que la tarea alcanzó un estado final, en milisegundos Unix. null hasta entonces.
Name
expires_at
Type
timestamp
Description
Momento en que expira el resultado de la tarea, en milisegundos Unix. Son 3 días después de finished_at, o 3 días después de created_at hasta que la tarea finalice. Para las cuentas Enterprise, que conservan los resultados de la API indefinidamente, es aproximadamente 100 años después. Consulta Retención de recursos.
Name
preceding_tasks
Type
integer
Description
La posición de la tarea en la cola mientras está en PENDING. 1 significa que comienza a continuación. 0 después de que la tarea sale de la cola, y siempre 0 en los resultados de listas.
Name
task_error
Type
object
Description
Por qué falló la tarea. null a menos que status sea FAILED. Consulta Errores.
Name
consumed_credits
Type
integer
Description
Número de créditos cobrados por la tarea, después de cualquier reembolso. Una solicitud que devuelve un error no se cobra. Una tarea fallida es 0, porque Meshy la reembolsa. Cancelar reembolsa una tarea solo mientras está en PENDING. Si Meshy no puede leer el cobro, una respuesta de get o stream omite el campo, y una solicitud de lista devuelve 500. En ese caso, reintenta la solicitud.
Name
image_urls
Type
array of strings
Description
URLs de descarga para la imagen de arte de píxeles. El array tiene una URL después de que la tarea tiene éxito, y está vacío hasta entonces.
Las URLs están firmadas, así que recupéralas sin un encabezado Authorization. Permanecen válidas hasta expires_at. Obtener la tarea nuevamente antes de ese momento devuelve las mismas URLs, no unas recién firmadas. Una URL expirada no se puede renovar, así que descarga y almacena los archivos antes de ese momento.

El objeto de tarea de construcción de Fidget Pixel

Una tarea de construcción genera las piezas imprimibles en 3D a partir de una tarea de prototipo exitosa. Meshy muestrea la imagen de pixel art en la cuadrícula y devuelve las piezas en un único archivo 3MF multicolor.

Propiedades

Example Fidget Pixel Build Task Object

{
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001300000,
  "started_at": 1757001304000,
  "finished_at": 1757001309000,
  "expires_at": 1757260509000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/output/model.3mf?Expires=***"
  }
}

Name
id
Type
string
Description
El ID de la tarea. No dependas de su formato.
Name
type
Type
string
Description
El tipo de tarea, siempre creative-lab-fidget-pixel-build.
Name
name
Type
string
Description
El name que enviaste al crear la tarea, o "" si no enviaste ninguno.
Name
status
Type
string
Description
El estado de la tarea.
Valores disponibles:
- PENDING: esperando en la cola
- IN_PROGRESS: generando el resultado
- SUCCEEDED: final, con el resultado
- FAILED: final, con el motivo en task_error
- CANCELED: final, sin resultado
Name
progress
Type
integer
Description
Porcentaje del trabajo realizado, de 0 a 100. Es 0 hasta que la tarea comienza y 100 cuando tiene éxito.
Name
created_at
Type
timestamp
Description
Momento en que se creó la tarea, en milisegundos Unix.
Name
started_at
Type
timestamp
Description
Momento en que un worker comenzó la tarea, en milisegundos Unix. null hasta entonces.
Name
finished_at
Type
timestamp
Description
Momento en que la tarea alcanzó un estado final, en milisegundos Unix. null hasta entonces.
Name
expires_at
Type
timestamp
Description
Momento en que expira el resultado de la tarea, en milisegundos Unix. Son 3 días después de finished_at, o 3 días después de created_at hasta que la tarea termina. Para las cuentas Enterprise, que conservan los resultados de la API indefinidamente, son aproximadamente 100 años después. Consulta Retención de recursos.
Name
preceding_tasks
Type
integer
Description
La posición de la tarea en la cola mientras está PENDING. 1 significa que empieza a continuación. 0 después de que la tarea sale de la cola, y siempre 0 en los resultados de listas.
Name
task_error
Type
object
Description
Por qué falló la tarea. null a menos que status sea FAILED. Consulta Errores.
Name
consumed_credits
Type
integer
Description
Número de créditos cobrados por la tarea, después de cualquier reembolso. Una solicitud que devuelve un error no se cobra. Una tarea fallida es 0, porque Meshy la reembolsa. Cancelar reembolsa una tarea solo mientras está PENDING. Si Meshy no puede leer el cargo, una respuesta de obtención o de transmisión omite el campo, y una solicitud de lista devuelve 500. En ese caso, reintenta la solicitud.
Name
model_urls
Type
object
Description
URLs de descarga para el resultado, indexadas por formato de archivo. El objeto tiene una entrada, para el output.format que enviaste, y está vacío hasta que la tarea tiene éxito.
Las URLs están firmadas, así que recupéralas sin un encabezado Authorization. Permanecen válidas hasta expires_at. Obtener la tarea nuevamente antes de ese momento devuelve las mismas URLs, no unas recién firmadas. Una URL expirada no se puede renovar, así que descarga y almacena los archivos antes de ese momento.
- Name
  3mf
  Type
  string
  Description
  URL de descarga para el archivo 3MF multicolor. Cada pieza tiene un cuerpo gris y una parte superior en el color de su píxel. Presente cuando output.format es 3mf, que es el valor predeterminado.

Ejemplo de principio a fin

Los siguientes scripts de cURL y Python ejecutan todo el flujo. Cada script crea una tarea de prototipo a partir de una foto y espera a que tenga éxito. Luego crea una tarea de construcción, espera a que esa tarea termine y descarga el archivo 3MF desde model_urls.3mf.

El script de cURL necesita curl y jq, y el script de Python necesita el paquete requests. Para ejecutar un script, sigue estos pasos:

Establece MESHY_API_KEY con tu clave de API.
Establece IMAGE_PATH con la ruta de una foto local, o IMAGE_URL con la URL pública de una imagen.
Opcional: Para pixelar un sujeto que no sea una persona, establece PIXEL_TYPE en other.
Ejecuta el script.

Una tarea de prototipo normalmente termina en unos pocos minutos. Una tarea de construcción normalmente termina en bastante menos de un minuto.

En tu aplicación, muestra la imagen de image_urls a tu usuario antes de crear la tarea de construcción. Si no les gusta, crea otra tarea de prototipo en su lugar. De esta manera, solo gastas créditos de construcción en una imagen que ellos aprueban.

Complete flow

POST

/openapi/creative-lab/fidget-pixel/v1

#!/usr/bin/env bash
set -euo pipefail

# Requires curl and jq. Point IMAGE_PATH at a local photo, or IMAGE_URL at a public one:
#   export MESHY_API_KEY=msy_...
#   export IMAGE_PATH=./portrait.jpg          # or: export IMAGE_URL=https://...
#   export PIXEL_TYPE=person                  # or: other
: "${MESHY_API_KEY:?export MESHY_API_KEY first}"
if [[ -z "${IMAGE_PATH:-}" && -z "${IMAGE_URL:-}" ]]; then
  echo "export IMAGE_PATH (local file) or IMAGE_URL (public url) first" >&2
  exit 1
fi
PIXEL_TYPE=${PIXEL_TYPE:-person}

BASE="https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1"
AUTH="Authorization: Bearer $MESHY_API_KEY"

# api METHOD URL [curl args...] -> prints the response body, non-zero on failure.
# Note we do not use -f/--fail: it discards the body, and the body is the only
# place the reason appears.
api() {
  local method=$1 url=$2 out http_code body
  shift 2
  out=$(curl --silent --show-error --max-time 60 --write-out $'\n%{http_code}' \
    -X "$method" "$url" -H "$AUTH" "$@") || return 1
  http_code=${out##*$'\n'}
  body=${out%$'\n'*}
  if ((http_code >= 400)); then
    echo "HTTP $http_code for $url: $body" >&2
    return 1
  fi
  printf '%s' "$body"
}

# Each task gets its own 40-minute budget.
poll() {
  local kind=$1 id=$2 delay=5 task_status deadline
  deadline=$(($(date +%s) + 2400))
  while :; do
    if (($(date +%s) >= deadline)); then
      echo "gave up waiting for $kind $id" >&2
      return 1
    fi
    task_status=$(api GET "$BASE/$kind/$id" | jq -r '.status')
    echo "$kind: $task_status"
    case "$task_status" in
    SUCCEEDED) return 0 ;;
    FAILED | CANCELED) return 1 ;;
    esac
    sleep "$delay"
    delay=$((delay * 2 > 30 ? 30 : delay * 2))
  done
}

# Build the request body in a file. A base64 data URI must never go on the
# command line or into an exported variable - a photo of any real size will
# exceed the OS argument limit.
BODY=$(mktemp)
trap 'rm -f "$BODY"' EXIT
if [[ -n "${IMAGE_PATH:-}" ]]; then
  # Declare the real type: the API accepts JPEG, PNG and WebP.
  case "$(printf '%s' "${IMAGE_PATH##*.}" | tr 'A-Z' 'a-z')" in
    png) MIME=image/png ;;
    webp) MIME=image/webp ;;
    *) MIME=image/jpeg ;;
  esac
  {
    printf '{"type":"%s","image_url":"data:%s;base64,' "$PIXEL_TYPE" "$MIME"
    base64 <"$IMAGE_PATH" | tr -d '\n'
    printf '"}'
  } >"$BODY"
else
  jq -n --arg t "$PIXEL_TYPE" --arg u "$IMAGE_URL" \
    '{type: $t, image_url: $u}' >"$BODY"
fi

# 1. Create the prototype task
PROTO_ID=$(api POST "$BASE/prototype" \
  -H 'Content-Type: application/json' --data-binary @"$BODY" | jq -r '.result')

# 2. Wait for the pixel-art image (show image_urls[0] to a user in production)
poll prototype "$PROTO_ID"

# 3. Create the build task (defaults: square pieces, 32x32 grid, 8 mm, 8 colors, 15 mm tall)
jq -n --arg p "$PROTO_ID" \
  '{input_task_id: $p, options: {shape: "square", grid_size: 32, piece_size_mm: 8, color_count: 8, piece_height_mm: 15}, output: {format: "3mf"}}' >"$BODY"
BUILD_ID=$(api POST "$BASE/build" \
  -H 'Content-Type: application/json' --data-binary @"$BODY" | jq -r '.result')

# 4. Wait for the pieces
poll build "$BUILD_ID"

# 5. Download the 3MF. This is a signed URL: no Authorization header,
#    and it stays valid for 3 days after the task finishes.
TASK=$(api GET "$BASE/build/$BUILD_ID")
curl --silent --show-error --fail --max-time 900 \
  -o fidget-pixel.3mf "$(jq -r '.model_urls["3mf"]' <<<"$TASK")"
echo "Done: fidget-pixel.3mf"