Creative Lab — API de figura

Convierte una foto de origen en una figura 3D coleccionable de estilo chibi en dos etapas: prototipo genera una imagen conceptual estilizada a partir de tu foto de entrada, luego construcción convierte esa imagen conceptual en un modelo 3D con textura. Las dos etapas están vinculadas mediante input_task_id.

POST /openapi/creative-lab/figure/v1/prototype
POST /openapi/creative-lab/figure/v1/build

POST/openapi/creative-lab/figure/v1/prototype

Crear una tarea de prototipo de figura

Genera una única imagen conceptual de estilo chibi a partir de la foto de origen. El ID de tarea devuelto es lo que pasas como input_task_id al endpoint de compilación. Consulta El objeto de tarea de prototipo de figura para ver la estructura de la respuesta.

Parámetros

Name
image_url
Type
string
Requerido
Description
Foto de origen para que Meshy la estilice como una figura chibi. 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úblico.
- Data URI: Una Data URI codificada en base64 de la imagen. Ejemplo de una 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.

Devuelve

La propiedad result de la respuesta contiene el id de tarea de la tarea de prototipo de figura recién creada. Consulta periódicamente el endpoint Get a Task o suscríbete al stream hasta que la tarea alcance SUCCEEDED; luego pasa ese ID al endpoint de compilación como input_task_id.

Modos de fallo

Name
400 - Bad Request
Description
La solicitud no fue aceptable. Causas comunes:
- Parámetro faltante: image_url es obligatorio.
- Formato de imagen no válido: El image_url proporcionado no es un formato admitido (.jpg, .jpeg, .png, .webp).
- Dimensiones de imagen fuera de rango: La imagen es demasiado pequeña, supera el tamaño máximo de archivo o supera el recuento máximo de píxeles.
- URL inaccesible: No se pudo descargar el image_url (404 o timeout).
- Data URI no válida: La cadena base64 está mal formada.
- Contenido marcado: La imagen de entrada fue marcada por moderation de NSFW o de propiedad intelectual.
Name
401 - Unauthorized
Description
La autenticación falló. Comprueba tu clave de API.
Name
402 - Payment Required
Description
Créditos insuficientes para realizar esta tarea.
Name
429 - Too Many Requests
Description
Has superado tu límite de tasa.

Request

POST

/openapi/creative-lab/figure/v1/prototype

# Stage 1: generate a chibi-style concept image
curl https://api.meshy.ai/openapi/creative-lab/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>"
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Prototype example

Start with a source portrait, then generate the prototype image used by the build stage.

Source portrait used as the Creative Lab Figure input — Prototype input

Chibi-style figurine prototype image generated from the source photo — Prototype output

POST/openapi/creative-lab/figure/v1/build

Crear una tarea de construcción de figura

Genera la figura 3D final con textura a partir de una tarea de prototipo completada correctamente. 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. Consulta El objeto de tarea de construcción de figura para ver 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 mediante 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 acepta solo tareas de prototipo producidas por POST /openapi/creative-lab/figure/v1/prototype y rechaza cualquier otro origen 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 tarea de la tarea de construcción de figura recién creada. Consulta el endpoint Obtener una tarea o suscríbete al stream hasta que la tarea alcance SUCCEEDED; luego descarga el GLB con textura desde model_urls.glb (o el par OBJ + MTL desde model_urls.obj y model_urls.mtl si tu 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.
- Padre no completado correctamente: La tarea de prototipo referenciada aún no ha alcanzado SUCCEEDED.
- Sin candidato: La tarea de prototipo se completó correctamente, pero no produjo ninguna imagen candidata.
Name
401 - Unauthorized
Description
La autenticación falló. Comprueba 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 se creó a través de la aplicación web (solo las tareas de prototipo en mode API se encadenan a la construcción).
Name
429 - Too Many Requests
Description
Has excedido tu límite de tasa.

Request

POST

/openapi/creative-lab/figure/v1/build

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/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"
  }'

Response

{
  "result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}

Build example

The build task turns the selected prototype image into a downloadable textured 3D model.

Creative Lab Figure build model preview — Build model preview

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

Recuperar una tarea de figura

Recupera una tarea de prototipo o build dado un id de tarea válido. La ruta de la URL debe coincidir con la etapa de la tarea: una tarea de build obtenida a través de /prototype/:id devuelve 404, y viceversa.

Consulta El objeto de tarea de prototipo de figura y El objeto de tarea de build de figura para las formas de respuesta.

Parámetros

Name
id
Type
path
Description
Identificador único de la tarea de figura que se va a recuperar.

Devuelve

La respuesta contiene el objeto de tarea de figura. La forma depende de qué etapa se solicitó.

Request

GET

/openapi/creative-lab/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

# Prototype
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-figure-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Build Response

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-figure-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 20,
  "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=***"
    }
  ]
}

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

Eliminar una tarea de figura

Cancela una tarea de figura. 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 (es posible que el trabajador 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: DELETE en /prototype/:buildId devuelve 404.

Parámetros de ruta

Name
id
Type
path
Description
Identificador único de la tarea de figura que se va a cancelar.

Devoluciones

Devuelve 204 No Content si se realiza correctamente, con un cuerpo vacío.

Modos de fallo

Name
400 - Bad Request
Description
La tarea ya está en un estado terminal 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 de la URL.

Request

DELETE

/openapi/creative-lab/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

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

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

Transmitir en streaming una tarea de figura

Transmite en streaming actualizaciones en tiempo real de una tarea de figura mediante Server-Sent Events (SSE). La ruta de la URL debe coincidir con la etapa de la tarea: abrir un flujo en /prototype/:buildId/stream emite un único payload event: error con status_code: 404 y cierra el flujo.

Parámetros

Name
id
Type
path
Description
Identificador único de la tarea de figura que se va a transmitir en streaming.

Devuelve

Devuelve un flujo de objetos de tarea de Prototipo de figura o Build de figura como Server-Sent Events. Para tareas PENDING o IN_PROGRESS, el flujo de respuesta solo incluirá los campos necesarios progress y status.

Request

GET

/openapi/creative-lab/figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream

curl -N https://api.meshy.ai/openapi/creative-lab/figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-figure-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "task_error": null,
  "consumed_credits": 20,
  "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=***"
    }
  ]
}

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

Listar tareas de figura

Recupera una lista paginada de tus tareas de figura para una sola etapa. La ruta de la URL selecciona la etapa: /prototype devuelve tareas de prototipo; /build devuelve tareas de compilación. Las tareas de la otra etapa no se incluyen en ninguna respuesta.

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: obtener /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 de tamaño de página. El máximo permitido es de 50 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.

Devuelve

Devuelve una lista paginada del objeto de tarea por etapa: ya sea el objeto de tarea de prototipo de figura al listar /prototype o el objeto de tarea de compilación de figura al listar /build.

Request

GET

/openapi/creative-lab/figure/v1/prototype

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

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

Response (List Prototype Tasks)

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-figure-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123486000,
    "expires_at": 1729382686000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/concept.png?Expires=***"
    ]
  }
]

El objeto de tarea de prototipo de figura

El objeto de tarea de prototipo de figura es una unidad de trabajo de la que Meshy hace seguimiento para generar una imagen conceptual de estilo chibi a partir de una foto de origen. La salida de esta etapa se encadena en la etapa de construcción mediante input_task_id.

Propiedades

Name
id
Type
string
Description
Identificador único de la tarea. Aunque usamos un UUID k-sortable para los ids de tarea 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. El valor es creative-lab-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
progress de la tarea. Si la tarea aún no se ha iniciado, esta propiedad será 0. Una vez que la tarea se haya completado correctamente, pasará a ser 100.
Name
created_at
Type
timestamp
Description
Marca de tiempo de cuando se creó 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 cuando 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 cuando 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 cuando expira el resultado de la tarea, en milisegundos.
Name
preceding_tasks
Type
integer
Description
El número de tareas precedentes.
El valor de este campo solo es significativo si el estado de la tarea 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. 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 las imágenes conceptuales candidatas generadas por esta tarea de prototipo. Actualmente, la API siempre devuelve exactamente una candidata; el campo es un array para que futuras revisiones puedan mostrar múltiples candidatas sin introducir un cambio incompatible.

Example Figure Prototype Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-figure-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

El objeto de tarea de creación de figura

El objeto de tarea de creación de figura es una unidad de trabajo que Meshy supervisa para generar una figura 3D con textura a partir de una tarea de prototipo completada correctamente. Ejecuta la misma canalización de Imagen a 3D utilizada 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-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
Progress de la tarea. Si la tarea aún no ha comenzado, esta propiedad será 0. Una vez que la tarea se haya completado correctamente, pasará a 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 inició la tarea, en milisegundos.
Name
finished_at
Type
timestamp
Description
Marca de tiempo de cuando finalizó 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 recuento de tareas precedentes. Solo tiene significado cuando el estado es PENDING.
Name
task_error
Type
object
Description
Detalles del error para tareas fallidas. Consulta Errores para obtener 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 está vacío para la creación de figura. Presente por compatibilidad entre endpoints con la forma compartida V2ImageTo3DTaskResponse utilizada por Imagen a 3D.
Name
negative_prompt
Type
string
Description
Siempre está vacío para la creación de figura. Presente por compatibilidad entre endpoints.
Name
texture_prompt
Type
string
Description
Siempre está vacío para la creación de figura. Presente por compatibilidad entre endpoints.
Name
texture_image_url
Type
string
Description
Siempre está vacío para la creación de figura. Presente por compatibilidad entre endpoints.
Name
model_urls
Type
object
Description
URL descargables para el modelo 3D generado. La creación de figura emite un GLB con textura más el par OBJ + MTL para pipelines que prefieren Wavefront OBJ. La forma del campo coincide con el objeto model_urls de Imagen a 3D, de modo que las futuras incorporaciones de formatos encajen sin un cambio incompatible.
- Name
  glb
  Type
  string
  Description
  URL descargable del archivo GLB con textura.
- Name
  obj
  Type
  string
  Description
  URL descargable del archivo Wavefront OBJ (geometría + UV).
- Name
  mtl
  Type
  string
  Description
  URL descargable del archivo de material MTL complementario del OBJ. Emparejar con obj y la entrada de texture_urls[0].base_color.
Name
thumbnail_url
Type
string
Description
URL descargable de la imagen en 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 de la imagen del mapa de color base.

Example Figure Build Task Object

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-figure-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 20,
  "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=***"
    }
  ]
}