Convierte una foto de origen en una figura coleccionable de vinilo 3D de cabezota en dos
etapas: prototype genera una imagen conceptual estilizada a partir de tu
foto de entrada, luego build convierte esa imagen conceptual en un modelo 3D con texturas.
Las dos etapas están vinculadas mediante input_task_id.
POST /openapi/creative-lab/vinyl-figure/v1/prototype
Genera una única imagen de concepto con estilo de figura de vinilo a partir de la foto de origen. El ID de tarea devuelto es lo que pasarás como input_task_id al endpoint de build. Consulta
El objeto de tarea de prototipo de figura de vinilo
para conocer la forma de la respuesta.
Parámetros
Name
image_url
Type
string
Requerido
Description
Foto de origen para que Meshy la estilice como una figura de vinilo de cabeza grande. Actualmente admitimos los formatos .jpg, .jpeg, .png y .webp.
Hay dos formas de proporcionar la imagen:
URL de acceso público: Una URL accesible desde internet públicamente.
Data URI: Un Data URI de la imagen codificado en base64. Ejemplo de un Data URI: data:image/jpeg;base64,<tus datos de imagen codificados en base64>.
Name
name
Type
string
Description
Nombre de tarea opcional para fines de visualización. Máximo 100 caracteres.
Name
remove_background
Type
boolean
predeterminado false
Description
Cuando se establece en true, la imagen de prototipo se devuelve como un PNG RGBA transparente con el fondo eliminado, de modo que puedas componer el sujeto sobre cualquier fondo.
Resultados devueltos
La propiedad result de la respuesta contiene el id de tarea de la tarea de prototipo de figura de vinilo recién creada. Consulta periódicamente el endpoint Obtener una tarea o suscríbete al stream hasta que la tarea alcance el estado SUCCEEDED, y luego pasa ese ID al endpoint de build como input_task_id.
Modos de fallo
Name
400 - Bad Request
Description
La solicitud fue inaceptable. Causas comunes:
Parámetro faltante: image_url es obligatorio.
Formato de imagen no válido: El image_url proporcionado no tiene un formato compatible (.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 número máximo de píxeles.
URL inaccesible: No se pudo descargar el image_url (404 o timeout).
Data URI no válido: La cadena en base64 está mal formada.
Contenido marcado: La imagen de entrada fue marcada por moderation de contenido NSFW o de propiedad intelectual.
Name
401 - Unauthorized
Description
Falló la autenticación. 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.
Request
POST
/openapi/creative-lab/vinyl-figure/v1/prototype
# Stage 1: generate a vinyl-figure-style concept imagecurlhttps://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/prototype \-XPOST \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "image_url": "<your publicly accessible image url or base64-encoded data URI>" }'
Response
{"result":"019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de"}
Ejemplo de prototipo
Comienza con una foto de origen y luego genera la imagen de prototipo utilizada por la etapa de build.
Entrada del prototipo
Salida del prototipo
Crear una tarea de construcción de figura de vinilo
Genera la figura de vinilo 3D texturizada final a partir de una tarea de prototipo exitosa. La construcción ejecuta el mismo pipeline de imagen a 3D que
Imagen a 3D, por lo que el formato del objeto de respuesta y la lista de URLs de salida coinciden exactamente. Consulte
El objeto de tarea de construcción de figura de vinilo
para conocer la forma de la respuesta.
Parámetros
Name
input_task_id
Type
string
Requerido
Description
El ID de tarea de una tarea de prototipo creada a través de este mismo endpoint de OpenAPI. El prototipo debe haberse creado con la misma clave de API, debe haber alcanzado SUCCEEDED y debe haber producido exactamente una imagen candidata.
Las tareas de prototipo creadas a través de la aplicación web no se aceptan; el endpoint de construcción solo acepta tareas de prototipo producidas por POST /openapi/creative-lab/vinyl-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.
Devuelve
La propiedad result de la respuesta contiene el id de la tarea recién creada de construcción de figura de vinilo. Consulte periódicamente el endpoint Obtener una tarea o suscríbase al stream hasta que la tarea alcance SUCCEEDED, luego descargue el GLB texturizado desde model_urls.glb (o el par OBJ + MTL desde model_urls.obj y model_urls.mtl si su pipeline posterior prefiere OBJ).
Modos de fallo
Name
400 - Bad Request
Description
La solicitud no era aceptable. Causas comunes:
Parámetro faltante: input_task_id es obligatorio.
UUID no válido: El input_task_id no es un UUID válido.
Tarea principal no exitosa: La tarea de prototipo referenciada aún no ha alcanzado SUCCEEDED.
Sin candidato: La tarea de prototipo tuvo éxito pero no produjo ninguna imagen candidata.
Name
401 - Unauthorized
Description
La autenticación falló. Por favor, verifique su 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 de prototipo en modo API se encadenan a la construcción).
Name
429 - Too Many Requests
Description
Ha excedido su límite de tasa.
Request
POST
/openapi/creative-lab/vinyl-figure/v1/build
# Stage 2: chain build off a succeeded prototype taskcurlhttps://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/build \-XPOST \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "input_task_id": "019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de" }'
Recupera una tarea de prototipo o de construcción dado un id de tarea válido. La ruta de la 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.
Cancela una tarea de figura de vinilo. Si la tarea aún está en PENDING, se reembolsan
los créditos consumidos en el momento de la creación. Las tareas que ya están
en IN_PROGRESS se cancelan sin reembolso (es posible que el worker ya esté
consumiendo recursos). Las tareas que ya han alcanzado un estado terminal
(SUCCEEDED, FAILED, CANCELED) no se pueden cancelar.
La ruta de la URL debe coincidir con la etapa de la tarea; usar DELETE en
/prototype/:buildId devuelve 404.
Parámetros de ruta
Name
id
Type
path
Description
Identificador único de la tarea de figura de vinilo que se desea 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 se encuentra en un estado terminal y no se puede cancelar.
Name
404 - Not Found
Description
La tarea no existe, pertenece a otro usuario, o su etapa no coincide con la ruta de la URL.
Transmite en streaming actualizaciones en tiempo real para una tarea de figura de vinilo mediante Server-Sent Events
(SSE). La ruta de la URL debe coincidir con la etapa de la tarea — abrir un stream en
/prototype/:buildId/stream emite un único payload event: error con
status_code: 404 y cierra el stream.
Parámetros
Name
id
Type
path
Description
Identificador único de la tarea de figura de vinilo a transmitir.
Devuelve
Devuelve un stream de objetos de tarea Vinyl Figure Prototype
o Vinyl Figure Build
como Server-Sent Events. Cada frame lleva el objeto de tarea completo para la etapa — la misma forma que
devuelve el endpoint Get — así que mientras la tarea esté en PENDING o IN_PROGRESS los
campos de salida simplemente aún no están poblados (null, [] o {}) y
finished_at es null.
Recupera una lista paginada de tus tareas de figura de vinilo para una sola etapa.
La ruta de la URL selecciona la etapa: /prototype devuelve las tareas de prototipo;
/build devuelve las tareas de compilación. Las tareas de la otra etapa no se incluyen
en ninguna de las respuestas.
Parámetros de ruta
Name
stage
Type
path
Requerido
Description
prototype o build. La colección devuelve solo las tareas
cuya etapa coincide con la URL: consultar /prototype nunca devuelve
tareas de compilació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 del tamaño de página. El máximo permitido es de 100 elementos.
Name
sort_by
Type
string
predeterminado -created_at
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.
El objeto Tarea de Prototipo de Figura de Vinilo es una unidad de trabajo que Meshy mantiene registrada
para generar una imagen de concepto con estilo de figura de vinilo a partir de una foto de origen.
La salida de esta etapa se encadena a
la etapa de construcción mediante input_task_id.
Propiedades
Name
id
Type
string
Description
Identificador único de la tarea. Si bien 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. El valor es creative-lab-vinyl-figure-prototype.
Name
name
Type
string
Description
El nombre de la tarea proporcionado al crearla. 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
Progress de la tarea. Si la tarea aún no ha comenzado, esta propiedad será 0. Una vez que la tarea haya tenido éxito, será 100.
Name
created_at
Type
timestamp
Description
Marca de tiempo de cuándo se creó la tarea, en milisegundos.
Una marca de tiempo representa la cantidad 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 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 aún no se ha iniciado, esta propiedad será 0.
Name
finished_at
Type
timestamp
Description
Marca de tiempo de cuándo se finalizó la tarea, en milisegundos. Si la tarea aún no ha finalizado, esta propiedad será 0.
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
El recuento de tareas precedentes.
El valor de este campo solo tiene sentido si el estado de la tarea es PENDING.
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
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).
Name
image_urls
Type
array of strings
Description
URLs descargables para los candidatos de imagen de concepto generados por esta tarea de prototipo. Actualmente la API siempre devuelve exactamente un candidato; el campo es un arreglo para que futuras revisiones puedan mostrar múltiples candidatos sin un cambio disruptivo.
El objeto Vinyl Figure Build Task es una unidad de trabajo que Meshy supervisa
para generar una figura de vinilo 3D con textura a partir de una tarea de prototipo exitosa.
Ejecuta el mismo pipeline de imagen a 3D utilizado por Imagen a 3D,
por lo que los campos de salida reflejan el objeto de tarea de ese endpoint.
Propiedades
Name
id
Type
string
Description
Identificador único de la tarea.
Name
type
Type
string
Description
Tipo de la tarea. El valor es creative-lab-vinyl-figure-build.
Name
name
Type
string
Description
El nombre de la tarea proporcionado al crearla. 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 aún no ha comenzado, esta propiedad será 0. Una vez que la tarea se haya completado con éxito, pasará a ser 100.
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.
Name
finished_at
Type
timestamp
Description
Marca de tiempo de cuándo finalizó la tarea, en milisegundos.
Name
expires_at
Type
timestamp
Description
Marca de tiempo de cuándo caduca el resultado de la tarea, en milisegundos.
Name
preceding_tasks
Type
integer
Description
El número de tareas precedentes. Solo tiene sentido cuando el estado es PENDING.
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. Devuelve 0 para tareas FAILED (los créditos se reembolsan en caso de fallo).
Name
prompt
Type
string
Description
Siempre vacío para vinyl figure build. Presente por compatibilidad entre endpoints con la forma compartida V2ImageTo3DTaskResponse utilizada por Imagen a 3D.
Name
negative_prompt
Type
string
Description
Siempre vacío para vinyl figure build. Presente por compatibilidad entre endpoints.
Name
texture_prompt
Type
string
Description
Siempre vacío para vinyl figure build. Presente por compatibilidad entre endpoints.
Name
texture_image_url
Type
string
Description
Siempre vacío para vinyl figure build. Presente por compatibilidad entre endpoints.
Name
model_urls
Type
object
Description
URLs descargables para el modelo 3D generado. El vinyl figure build produce un GLB con textura, además del par OBJ + MTL para los pipelines que prefieren Wavefront OBJ. La forma de este campo coincide con el objeto model_urls de Imagen a 3D, de modo que futuras incorporaciones de formatos encajen sin cambios disruptivos.
Name
glb
Type
string
Description
URL descargable al archivo GLB con textura.
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 complementario del OBJ. Combínalo con obj y la entrada de texture_urls[0].base_color.
Name
thumbnail_url
Type
string
Description
URL descargable a la imagen de miniatura del archivo del modelo.
Name
texture_urls
Type
array
Description
Un array de objetos de 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.