API de Fidget Colapsable de Creative Lab

Convierte una foto en un juguete fidget colapsable imprimible de una sola pieza en una sola tarea. La silueta del sujeto se convierte en anillos concéntricos anidados que se colapsan planos y se estiran de nuevo. El juguete se imprime 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 etapas separadas de prototipo y construcción. No hay imágenes candidatas entre las cuales elegir, así que una sola tarea convierte la foto en un modelo 3D.

La solicitud tampoco tiene configuraciones de geometría. La aplicación web te permite establecer el tamaño, el número de capas, el ancho del espacio, el grosor de pared, la profundidad de extrusión y el abultamiento. Cada tarea de la API usa los mismos valores predeterminados para estos parámetros.

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

Crear una tarea de Fidget Colapsable

Genera un modelo de fidget colapsable a partir de una foto. Para conocer los campos de la tarea, consulta El objeto de tarea de Fidget Colapsable.

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

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"
}

Parámetros

Name
image_url
Type
string
Requerido
Description
La foto que se convertirá en un fidget colapsable, como una URL pública o un data URI (data:image/jpeg;base64,<your base64-encoded image data>).
La imagen debe ser un archivo JPG, JPEG, PNG o WebP de hasta 20 MB.
La silueta del sujeto se convierte en los anillos, por lo que un sujeto con un contorno claro y cerrado funciona mejor. Un fondo recargado, varios sujetos separados o formas muy delgadas pueden dejar muy poca área para las paredes anidadas. En ese caso, la tarea falla.
Name
name
Type
string
Description
Un nombre para la tarea, de hasta 100 caracteres. Se devuelve en el campo name de la tarea, y Meshy no lo graba en el modelo. Un nombre más largo devuelve 400.

Devuelve

El campo result contiene el ID de la nueva tarea. Obtén la tarea o transmítela hasta que status sea SUCCEEDED. Luego descarga el archivo STL imprimible desde model_urls.stl. Para previsualizar el modelo primero, descarga el archivo GLB desde model_urls.glb cuando esté presente.

Modos de falla

Name
400 - Bad Request
Description
La solicitud no puede ejecutarse. Por ejemplo:
- Falta image_url.
- La imagen no es un archivo JPG, JPEG, PNG o WebP.
- La imagen es demasiado pequeña, supera los 20 MB o excede 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 vuelve a enviarla.
Name
401 - Unauthorized
Description
Falta la clave de API o no es válida. Verifica el encabezado Authorization.
Name
402 - Payment Required
Description
Se aplica una de las siguientes condiciones:
- 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 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 agrega créditos.
Name
500 - Internal Server Error
Description
Meshy tuvo un error de servidor, por ejemplo porque no pudo ejecutar la verificación de propiedad intelectual en la imagen. Meshy no crea la tarea y reembolsa cualquier crédito que haya cobrado. Vuelve a intentar la solicitud.

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

Obtener una tarea de Collapsible Fidget

Devuelve una tarea de Collapsible Fidget. Solo se devuelven las tareas creadas con este endpoint. Una tarea de otro endpoint de Creative Lab, o una creada en la aplicación web, devuelve 404.

Para conocer los campos, consulta El objeto de tarea Collapsible Fidget.

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=***"
  }
}

Parámetros

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

Devuelve

El objeto de tarea Collapsible Fidget.

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 por propiedad intelectual de terceros. Los equipos en el plan Enterprise no reciben este error. Crea una tarea a partir de una imagen sobre la que tengas los derechos de uso.
Name
404 - Not Found
Description
Ninguna tarea de Collapsible Fidget con este ID pertenece a tu cuenta, o la tarea no se creó con este endpoint. Verifica el ID.
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-collapsible/v1/:id

Eliminar una tarea de Collapsible Fidget

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

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).

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 Collapsible Fidget con este ID pertenece a tu cuenta, o la tarea no fue creada con este endpoint. Verifica el ID.

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

Transmitir en streaming una tarea de Collapsible Fidget

Transmite las actualizaciones de una tarea de Collapsible Fidget como eventos enviados por el servidor (SSE). Si la tarea no existe o no se creó con este endpoint, el stream envía un evento error con status_code: 404 y se cierra.

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 following PENDING frame is shortened 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=***"
  }
}

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 Collapsible Fidget. Cada evento contiene el objeto de tarea completo, tal como lo devuelve Obtener una tarea de Collapsible Fidget. 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 get.

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

Listar tareas de Fidget plegable

Devuelve tus tareas de Fidget plegable, una página a la vez. Solo se incluyen las tareas creadas con este endpoint.

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=***"
    }
  }
]

Parámetros de consulta

Name
page_num
Type
integer
predeterminado 1
Description
La página que se va a devolver, de 1 a 255. 0 devuelve la primera página. Un valor fuera del rango 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 del rango 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 recientes primero
- +created_at: más antiguas primero

Devuelve

Un array de objetos de tarea de Fidget plegable.

El objeto de tarea de Collapsible Fidget

Una tarea de Collapsible Fidget convierte una foto en un modelo de fidget colapsable imprimible de una pieza. Es una tarea de una sola etapa, por lo que no hay ninguna tarea de prototipo de la que encadenarla. La respuesta no incluye la silueta que Meshy genera en el proceso.

Propiedades

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=***"
  }
}

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-collapsible.
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
Hora en que se creó la tarea, en milisegundos Unix.
Name
started_at
Type
timestamp
Description
Hora en que un worker inició la tarea, en milisegundos Unix. null hasta entonces.
Name
finished_at
Type
timestamp
Description
Hora en que la tarea alcanzó un estado final, en milisegundos Unix. null hasta entonces.
Name
expires_at
Type
timestamp
Description
Hora 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 termine. Para cuentas Enterprise, que conservan los resultados de la API indefinidamente, son unos 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 cobro, 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 modelo 3D, vacío hasta que la tarea tenga éxito. Una tarea exitosa siempre tiene stl, y tiene glb solo si Meshy renderizó la vista previa.
- Name
  stl
  Type
  string
  Description
  URL de descarga para el archivo STL, que es el archivo para imprimir. Puedes abrirlo directamente en un laminador.
- Name
  glb
  Type
  string
  Description
  URL de descarga para un archivo GLB para previsualizar el modelo en un visor 3D. Sus colores son solo para la vista previa. El archivo STL no tiene color, por lo que el fidget impreso toma su color del filamento.
  Si Meshy no puede renderizar la vista previa, model_urls no tiene la clave glb, así que verifica la clave antes de leerla. Una tarea SUCCEEDED siempre tiene stl.