Creative Lab — API de Fidget Colapsable

Convierte una foto de origen en un juguete fidget colapsable listo para imprimir de una sola pieza: la silueta del sujeto se convierte en un conjunto de anillos concéntricos anidados que se colapsan y se estiran de nuevo, impresos en una sola pieza sin necesidad de ensamblaje.

POST /openapi/creative-lab/fidget-collapsible/v1

A diferencia de los demás endpoints de Creative Lab, este no tiene un par de etapas de prototipo/build — no hay candidatos intermedios entre los que elegir, así que una sola tarea lleva la imagen hasta el modelo 3D. Los controles de geometría que expone la aplicación web (tamaño, número de capas, ancho de separación, grosor de pared, profundidad de extrusión, abultamiento) tampoco forman parte de la solicitud: cada tarea se genera con los mismos valores predeterminados del lado del servidor.

POST/openapi/creative-lab/fidget-collapsible/v1

Crear una tarea de Fidget Colapsable

Genera un modelo de fidget colapsable a partir de una foto de origen. Consulta El objeto de tarea de Fidget Colapsable para conocer la forma de la respuesta.

Cada tarea cuesta 6 créditos y requiere un plan de pago.

Parámetros

Name
image_url
Type
string
Requerido
Description
Foto de origen para que Meshy la convierta en un fidget colapsable. 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 de forma pública.
- 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>.
Un sujeto con un contorno claro y cerrado funciona mejor, ya que la silueta es lo que se convierte en los anillos. Fondos recargados, varios sujetos independientes o formas muy delgadas pueden dejar muy poca área para las paredes anidadas, y la tarea falla con un error de tarea.
Name
name
Type
string
Description
Nombre de tarea opcional para fines de visualización. Máximo 100 caracteres. Esto es solo una etiqueta de la tarea; no se graba nada en el modelo.

Devuelve

La propiedad result de la respuesta contiene el id de la tarea recién creada de fidget colapsable. Consulta periódicamente el endpoint Obtener una tarea o suscríbete al stream hasta que la tarea alcance el estado SUCCEEDED, y luego descarga el STL imprimible desde model_urls.stl (y, cuando esté presente, el GLB desde model_urls.glb para previsualizarlo primero).

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, supera el tamaño máximo de archivo o supera 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 la moderation de contenido NSFW.
Name
401 - Unauthorized
Description
Falló la autenticación. Verifica tu clave de API.
Name
402 - Payment Required
Description
O bien tu cuenta está en el plan gratuito —la creación de tareas en este endpoint requiere un plan de pago— o no tienes créditos suficientes.
Name
403 - Forbidden
Description
La imagen de entrada fue marcada por infracción de propiedad intelectual.
Name
429 - Too Many Requests
Description
Has superado tu límite de tasa.

Request

POST

/openapi/creative-lab/fidget-collapsible/v1

curl https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1 \
  -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"
}

GET/openapi/creative-lab/fidget-collapsible/v1/:id

Recuperar una tarea de Fidget Colapsable

Recupera una tarea de fidget colapsable dado un id de tarea válido. Solo las tareas creadas a través de este endpoint son direccionables aquí; una tarea de otro endpoint de Creative Lab, o una creada en la aplicación web, devuelve 404.

Consulta El objeto de tarea de Fidget Colapsable para conocer la forma de la respuesta.

Parámetros

Name
id
Type
path
Description
Identificador único de la tarea de fidget colapsable que se desea recuperar.

Devuelve

La respuesta contiene el objeto de tarea de fidget colapsable.

Request

GET

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

DELETE/openapi/creative-lab/fidget-collapsible/v1/:id

Eliminar una tarea de Fidget Colapsable

Cancela una tarea de fidget colapsable. Si la tarea todavía está en PENDING, los créditos consumidos en el momento de la creación se reembolsan. 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.

Parámetros de ruta

Name
id
Type
path
Description
Identificador único de la tarea de fidget colapsable 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 se encuentra en un estado terminal y no se puede cancelar.
Name
404 - Not Found
Description
La tarea no existe, pertenece a un usuario diferente o no fue creada a través de este endpoint.

Request

DELETE

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

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

GET/openapi/creative-lab/fidget-collapsible/v1/:id/stream

Transmitir una Tarea de Fidget Colapsable

Transmite actualizaciones en tiempo real para una tarea de fidget colapsable mediante Server-Sent Events (SSE). Una tarea que no existe, o que no fue creada a través de este endpoint, emite un único event: error payload con status_code: 404 y cierra el stream.

Parámetros

Name
id
Type
path
Description
Identificador único de la tarea de fidget colapsable a transmitir.

Devuelve

Devuelve un stream de objetos de tarea Collapsible Fidget como Server-Sent Events. Cada frame contiene 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.

Request

GET

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (task not found, or not created through this endpoint)
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// Every frame is the full task object; fields not yet populated are null / empty.
// The PENDING frame below is abbreviated to the fields that change.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

GET/openapi/creative-lab/fidget-collapsible/v1

Listar tareas de fidget colapsable

Recupera una lista paginada de tus tareas de fidget colapsable. Solo se incluyen las tareas creadas a través de este endpoint.

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 hora de creación en orden ascendente.
- -created_at: Ordenar por hora de creación en orden descendente.

Devuelve

Devuelve una lista paginada de el objeto de tarea de fidget colapsable.

Request

GET

/openapi/creative-lab/fidget-collapsible/v1

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-fidget-collapsible",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123512000,
    "expires_at": 1729382712000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
    }
  }
]

El objeto Collapsible Fidget Task

El objeto Collapsible Fidget Task es una unidad de trabajo que Meshy monitorea para convertir una foto de origen en un modelo de fidget plegable listo para imprimir. Es una tarea de una sola etapa: no hay prototipo del que encadenar, y la silueta intermedia no forma parte de la respuesta.

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 debe hacer ninguna suposición sobre el formato del id.
Name
type
Type
string
Description
Tipo de la tarea. El valor es creative-lab-fidget-collapsible.
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 se ha iniciado, esta propiedad será 0. Una vez que la tarea haya tenido éxito, se convertirá en 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 aplica a todas las marcas de tiempo en la 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á null.
Name
finished_at
Type
timestamp
Description
Marca de tiempo de cuando finalizó la tarea, en milisegundos. Si la tarea aún no ha finalizado, esta propiedad será null.
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.
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. Consulte 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).
Name
model_urls
Type
object
Description
URLs descargables para el modelo 3D generado. Se completan una vez que la tarea ha tenido SUCCEEDED: stl siempre está presente, glb solo cuando la renderización de vista previa tuvo éxito.
- Name
  stl
  Type
  string
  Description
  URL descargable al archivo STL. Este es el entregable imprimible: envíelo directamente a un laminador.
- Name
  glb
  Type
  string
  Description
  URL descargable al archivo GLB, para previsualizar el modelo en un visor 3D. Sus colores son solo para vista previa: el STL no lleva color, y un fidget impreso toma su color del filamento. El GLB es best-effort: cuando la renderización de vista previa no está disponible, la clave se omite por completo de model_urls, así que léala de forma defensiva; stl es el entregable y siempre está presente en una tarea SUCCEEDED.

Example Collapsible Fidget Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}