Convierte una foto de origen en una minifigura coleccionable de estilo ladrillo en dos etapas:
prototipo genera una imagen conceptual estilizada a partir de tu foto de entrada, luego
construcción transforma esa imagen conceptual en un modelo 3D con textura. Las dos etapas
están vinculadas mediante input_task_id.
POST /openapi/creative-lab/brick-figure/v1/prototype
Genera una imagen de concepto de estilo bloque a partir de la foto fuente. El ID de tarea devuelto es lo que debes pasar como input_task_id al endpoint de construcción. Consulta El Objeto de Tarea de Prototipo de Figura de Bloque para conocer la estructura de la respuesta.
Parámetros
Name
image_url
Type
string
Requerido
Description
Foto fuente para que Meshy la estilice como una minifigura de bloque. Actualmente admitimos los formatos .jpg, .jpeg, .png y .webp.
Hay dos formas de proporcionar la imagen:
URL accesible públicamente: Una URL que sea accesible desde internet de forma pública.
Data URI: Un Data URI codificado en base64 de la imagen. Ejemplo de un Data URI: data:image/jpeg;base64,<your base64-encoded image data>.
Name
name
Type
string
Description
Nombre de tarea opcional para fines de visualización. Máximo 100 caracteres.
Retornos
La propiedad result de la respuesta contiene el ID de tarea del prototipo de figura de bloque recién creado. Consulta el endpoint Obtener una Tarea o suscríbete al stream hasta que la tarea alcance SUCCEEDED, luego pasa ese ID al endpoint de construcción como input_task_id.
Modos de Falla
Name
400 - Bad Request
Description
La solicitud no fue aceptable. Causas comunes:
Parámetro faltante: se requiere image_url.
Formato de imagen no válido: El image_url proporcionado no es un formato soportado (.jpg, .jpeg, .png, .webp).
Dimensiones de imagen fuera de rango: La imagen es demasiado pequeña, excede el tamaño máximo de archivo o excede el conteo máximo de píxeles.
URL inaccesible: No se pudo descargar el image_url (404 o timeout).
Data URI no válido: La cadena base64 está malformada.
Contenido marcado: La imagen de entrada fue marcada por la moderación NSFW o de propiedad intelectual.
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
403 - Forbidden
Description
La imagen de entrada fue marcada por infracción de propiedad intelectual.
Name
429 - Too Many Requests
Description
Has excedido tu límite de tasa.
Solicitud
POST
/openapi/creative-lab/brick-figure/v1/prototype
# Etapa 1: generar una imagen de concepto estilo bloquecurl https://api.meshy.ai/openapi/creative-lab/brick-figure/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>" }'
Genera la figura de ladrillo 3D final con textura a partir de una tarea de prototipo exitosa. La construcción ejecuta la misma canalización de imagen a 3D que Imagen a 3D, por lo que el formato del objeto de respuesta y la lista de URL de salida coinciden exactamente. Consulte El Objeto de la Tarea de Construcción de Figura de Ladrillo para conocer la estructura de la respuesta.
Parámetros
Name
input_task_id
Type
string
Requerido
Description
El ID de la tarea de un prototipo creado a través de este mismo endpoint OpenAPI. El prototipo debe haber sido creado con la misma clave de API, debe haber alcanzado SUCCEEDED, y debe haber producido exactamente una imagen candidata.
Las tareas prototipo creadas a través de la aplicación web no son aceptadas — el endpoint de construcción acepta solo tareas prototipo producidas por POST /openapi/creative-lab/brick-figure/v1/prototype y rechaza cualquier otra fuente con 404.
Name
name
Type
string
Description
Nombre de tarea opcional para fines de visualización. Máximo 100 caracteres.
Retornos
La propiedad result de la respuesta contiene el id de la tarea de construcción de figura de ladrillo recién creada. Consulte el endpoint Obtener una Tarea o suscríbase al stream hasta que la tarea alcance SUCCEEDED, luego descargue el GLB con textura de model_urls.glb (o el par OBJ + MTL de model_urls.obj y model_urls.mtl si su canalización downstream prefiere OBJ).
Modos de Fallo
Name
400 - Bad Request
Description
La solicitud fue inaceptable. Causas comunes:
Parámetro faltante: input_task_id es requerido.
UUID inválido: El input_task_id no es un UUID válido.
Padre no exitoso: La tarea de prototipo referenciada no ha alcanzado aún SUCCEEDED.
Sin candidato: La tarea de prototipo tuvo éxito pero no produjo ninguna imagen candidata.
Name
401 - Unauthorized
Description
Falló la autenticación. Por favor, revisa tu clave de API.
Name
402 - Payment Required
Description
Créditos insuficientes para realizar esta tarea.
Name
404 - Not Found
Description
La tarea de prototipo referenciada no existe, pertenece a un usuario diferente o fue creada a través de la aplicación web (solo las tareas prototipo en modo API se encadenan en construcción).
Name
429 - Too Many Requests
Description
Has excedido tu límite de tasa.
Request
POST
/openapi/creative-lab/brick-figure/v1/build
# Etapa 2: encadenar construcción de una tarea de prototipo exitosacurl https://api.meshy.ai/openapi/creative-lab/brick-figure/v1/build \ -X POST \ -H "Authorization: Bearer ${YOUR_API_KEY}" \ -H 'Content-Type: application/json' \ -d '{ "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578" }'
Recupera una tarea de prototipo o construcción dado un id de tarea válido. La ruta URL
debe coincidir con la etapa de la tarea: una tarea de construcción obtenida a través de
/prototype/:id devuelve 404, y viceversa.
Cancelar una tarea de figura de ladrillo. Si la tarea aún está PENDING, los créditos
consumidos en el momento de la creación se reembolsan. Las tareas que ya están
IN_PROGRESS se cancelan sin reembolso (el trabajador ya puede estar
consumiendo recursos). Las tareas que ya han alcanzado un estado final
(SUCCEEDED, FAILED, CANCELED) no se pueden cancelar.
La ruta URL debe coincidir con la etapa de la tarea — DELETE en
/prototype/:buildId devuelve 404.
Parámetros de Ruta
Name
id
Type
path
Description
Identificador único para la tarea de figura de ladrillo que se va a cancelar.
Devuelve
Devuelve 204 No Content en caso de éxito con un cuerpo vacío.
Modos de Fallo
Name
400 - Bad Request
Description
La tarea ya está en un estado final y no se puede cancelar.
Name
404 - Not Found
Description
La tarea no existe, pertenece a un usuario diferente, o su etapa no coincide con la ruta URL.
Transmite actualizaciones en tiempo real para una tarea de figura de ladrillo a través de Server-Sent Events (SSE).
La ruta URL debe coincidir con la etapa de la tarea: abrir un stream en
/prototype/:buildId/stream emite un único event: error payload con
status_code: 404 y cierra el stream.
Parámetros
Name
id
Type
path
Description
Identificador único para la tarea de figura de ladrillo a transmitir.
Devuelve
Devuelve un stream de objetos de tarea de Figura de Ladrillo Prototipo
o Figura de Ladrillo Construcción como
Server-Sent Events. Para tareas PENDING o IN_PROGRESS, el stream de respuesta
incluirá solo los campos necesarios de progress y status.
// Ejemplo de evento de error (etapa incorrecta o tarea no encontrada)event: errordata: {"status_code": 404,"message": "Task not found"}// Los ejemplos de eventos de mensaje ilustran el progreso de la tarea.// Para tareas PENDING o IN_PROGRESS, el flujo de respuesta no incluirá todos los campos.event: messagedata: {"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb","progress": 0,"status": "PENDING"}event: messagedata: {"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb","type": "creative-lab-brick-figure-build","status": "SUCCEEDED","progress": 100,"created_at": 1729123500000,"started_at": 1729123510000,"finished_at": 1729123535000,"expires_at": 1729382735000,"task_error": null,"consumed_credits": 30,"prompt": "","negative_prompt": "","texture_prompt": "","texture_image_url": "","model_urls": {"glb":"https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***","obj":"https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.obj?Expires=***","mtl":"https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.mtl?Expires=***" },"thumbnail_url": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/preview.png?Expires=***","texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/texture_0.png?Expires=***" } ]}
Recupera una lista paginada de tus tareas de figura brick para una sola etapa. La ruta
URL selecciona la etapa — /prototype devuelve tareas de prototipo; /build
devuelve tareas de construcción. Las tareas de la otra etapa no están incluidas en ninguna
de las respuestas.
Parámetros de Ruta
Name
stage
Type
path
Requerido
Description
Ya sea prototype o build. La colección devuelve solo tareas
cuya etapa coincide con la URL — al buscar /prototype nunca se devuelven
tareas de construcción y viceversa.
Parámetros de Consulta
Name
page_num
Type
integer
predeterminado 1
Description
Número de página para la paginación.
Name
page_size
Type
integer
predeterminado 10
Description
Límite de tamaño de página. El máximo permitido es 100 elementos.
Name
sort_by
Type
string
predeterminado -created_at
Description
Campo por el cual 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.
El objeto Brick Figure Prototype Task es una unidad de trabajo que Meshy sigue para generar una imagen conceptual al estilo de ladrillo a partir de una foto fuente. La salida de esta etapa se encadena en la etapa de construcción a través de input_task_id.
Propiedades
Name
id
Type
string
Description
Identificador único para la tarea. Aunque usamos un UUID k-sortable para las ids de las tareas como detalle de implementación, no deberías hacer ninguna suposición sobre el formato del id.
Name
type
Type
string
Description
Tipo de tarea. El valor es creative-lab-brick-figure-prototype.
Name
name
Type
string
Description
El nombre de la tarea proporcionado cuando se creó la tarea. Cadena vacía si no se proporcionó ningún nombre.
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 no ha comenzado aún, esta propiedad será 0. Una vez que la tarea ha tenido éxito, esto se convertirá en 100.
Name
created_at
Type
timestamp
Description
Marca de tiempo de cuándo fue creada la tarea, en milisegundos.
Una marca de tiempo representa el número de milisegundos transcurridos desde el 1 de enero de 1970 UTC, siguiendo
el estándar RFC 3339.
Por ejemplo, el viernes, 1 de septiembre de 2023 a las 12:00:00 PM GMT se representa como 1693569600000. Esto se aplica
a todas las marcas de tiempo en Meshy API.
Name
started_at
Type
timestamp
Description
Marca de tiempo de cuándo se inició la tarea, en milisegundos. Si la tarea no ha comenzado aún, esta propiedad será null.
Name
finished_at
Type
timestamp
Description
Marca de tiempo de cuándo se terminó la tarea, en milisegundos. Si la tarea no ha terminado aún, esta propiedad será null.
Name
expires_at
Type
timestamp
Description
Marca de tiempo de cuándo expira el resultado de la tarea, en milisegundos.
Name
preceding_tasks
Type
integer
Description
La cantidad de tareas precedentes.
El valor de este campo es significativo solo si el estado de la tarea es PENDING.
Name
task_error
Type
object
Description
Detalles del error para las 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 las tareas FAILED (los créditos son reembolsados en caso de fallo).
Name
image_urls
Type
array of strings
Description
URLs descargables para los candidatos a imagen conceptual generados por esta tarea prototipo. Actualmente la API siempre devuelve exactamente un candidato; el campo es un array para que futuras revisiones puedan mostrar múltiples candidatos sin un cambio disruptivo.
Ejemplo de Objeto de Tarea Prototipo de Figura de Ladrillo
El objeto de tarea de construcción de figura de ladrillo es una unidad de trabajo que Meshy sigue para generar una figura de ladrillo 3D con textura a partir de una tarea prototipo SUCCEEDED. Ejecuta la misma canalización de imagen-a-3D utilizada por Imagen a 3D, por lo que los campos de salida reflejan los del objeto de tarea de ese endpoint.
Propiedades
Name
id
Type
string
Description
Identificador único para la tarea.
Name
type
Type
string
Description
Tipo de la tarea. El valor es creative-lab-brick-figure-build.
Name
name
Type
string
Description
El nombre de la tarea proporcionado cuando se creó la tarea. Cadena vacía si no se proporcionó ningún nombre.
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 no ha comenzado aún, esta propiedad será 0. Una vez que la tarea haya tenido éxito, esto será 100.
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 comenzó la tarea, en milisegundos.
Name
finished_at
Type
timestamp
Description
Marca de tiempo de cuando se terminó la tarea, en milisegundos.
Name
expires_at
Type
timestamp
Description
Marca de tiempo de cuando expira el resultado de la tarea, en milisegundos.
Name
preceding_tasks
Type
integer
Description
El conteo de tareas precedentes. Significativo solo cuando el estado es PENDING.
Name
task_error
Type
object
Description
Detalles del error para las 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. Devuelve 0 para tareas FAILED (los créditos se reembolsan en caso de fallo).
Name
prompt
Type
string
Description
Siempre vacío para la construcción de figuras de ladrillo. Presente para compatibilidad entre endpoints con la forma compartida V2ImageTo3DTaskResponse utilizada por Imagen a 3D.
Name
negative_prompt
Type
string
Description
Siempre vacío para la construcción de figuras de ladrillo. Presente para compatibilidad entre endpoints.
Name
texture_prompt
Type
string
Description
Siempre vacío para la construcción de figuras de ladrillo. Presente para compatibilidad entre endpoints.
Name
texture_image_url
Type
string
Description
Siempre vacío para la construcción de figuras de ladrillo. Presente para compatibilidad entre endpoints.
Name
model_urls
Type
object
Description
URLs descargables para el modelo 3D generado. La construcción de la figura de ladrillo emite un GLB texturizado más el par OBJ + MTL para los pipelines que prefieren Wavefront OBJ. La forma del campo coincide con el objeto model_urls Imagen a 3D para que las futuras adiciones de formatos se integren sin un cambio brusco.
Name
glb
Type
string
Description
URL descargable al archivo GLB texturizado.
Name
obj
Type
string
Description
URL descargable al archivo Wavefront OBJ (geometría + UV).
Name
mtl
Type
string
Description
URL descargable al archivo de material MTL compañero del OBJ. Emparejar con obj y la entrada de texture_urls[0].base_color.
Name
thumbnail_url
Type
string
Description
URL descargable a la imagen en miniatura del archivo del modelo.
Name
texture_urls
Type
array
Description
Una matriz de objetos URL de textura generados por esta tarea. Actualmente contiene un único objeto con el mapa de color base.
Name
base_color
Type
string
Description
URL descargable a la imagen del mapa de color base.
Ejemplo de Objeto de Tarea de Construcción de Figura de Ladrillo