API de llavero de Creative Lab

Convierte una foto en un llavero imprimible en 3D con un relieve de color en dos etapas. Una tarea de prototipo genera una imagen conceptual coloreada a partir de la foto. Una tarea de compilación convierte esa imagen en un modelo 3D de relieve, y toma el ID de la tarea de prototipo como input_task_id.

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

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

Crear una tarea de prototipo de Keychain

Genera una imagen conceptual coloreada a partir de una foto. Para construir el modelo 3D, pasa el ID de esta tarea al endpoint de build como input_task_id. Para conocer los campos de la tarea, consulta El objeto de la tarea de prototipo de Keychain.

Request

POST

/openapi/creative-lab/keychain/v1/prototype

# Stage 1: generate a colorized keychain concept image
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>",
    "name_text": "Luna"
  }'

Response

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

Prototype example

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

Source photo used as the Creative Lab Keychain input — Prototype input

Creative Lab Keychain prototype output generated from the source photo — Prototype output

Parámetros

Name
image_url
Type
string
Requerido
Description
La foto que se convertirá en una imagen conceptual de keychain, como una URL pública o un Data URI (data:image/jpeg;base64,<tus datos de imagen codificados en base64>).
La imagen debe ser un archivo JPG, JPEG, PNG o WebP de un máximo de 20 MB.
Name
name
Type
string
Description
Un nombre para la tarea, de hasta 100 caracteres. Se devuelve en el campo name de la tarea. Un nombre más largo devuelve 400.
Etiqueta la tarea en tu panel y en las listas de tareas, y no aparece en el keychain. Para poner un nombre en el keychain, usa name_text.
Name
name_text
Type
string
Description
Un nombre para agregar al keychain, como el nombre de una mascota o de una persona, de hasta 10 caracteres. Meshy cuenta caracteres, no bytes, así que un nombre de 10 caracteres en chino, japonés o coreano cabe perfectamente. Un nombre más largo devuelve 400. Omítelo para un keychain sin nombre.
El nombre aparece en la cara del keychain como un detalle plano de color, no como texto en relieve o grabado.
Meshy recorta los espacios en blanco circundantes y elimina los caracteres de formato invisibles. El objeto de la tarea de prototipo devuelve el resultado como name_text, para que puedas verificar el texto antes de pagar por el build.
Meshy agrega el nombre en la etapa de prototipo. El build lo conserva, e ignora un name_text enviado al endpoint de build.
Cuando el texto no sea ASCII plano, envía el cuerpo de la solicitud como UTF-8 con Content-Type: application/json; charset=utf-8. Algunos clientes HTTP, como Invoke-RestMethod de Windows PowerShell, codifican el cuerpo como ISO-8859-1 de forma predeterminada. Eso convierte cada carácter no latino en ? antes de que la solicitud llegue a Meshy, y Meshy no puede distinguirlo de un nombre que querías enviar.
Name
remove_background
Type
boolean
predeterminado false
Description
Si se debe eliminar el fondo de la imagen de prototipo. true devuelve un PNG RGBA transparente que conserva todo el medallón, para que puedas colocarlo sobre cualquier fondo. El build también parte de la imagen sin su fondo. Si Meshy no puede eliminar el fondo, devuelve la imagen con su fondo, y la tarea igualmente se completa con éxito.
La opción remove_background del build es independiente.

Devuelve

El campo result contiene el ID de la nueva tarea de prototipo. Obtén la tarea o transmítela hasta que status sea SUCCEEDED. Luego pasa el ID al endpoint de build como input_task_id.

Modos de fallo

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 supera el número máximo de píxeles.
- Meshy no puede descargar la imagen, por ejemplo porque la URL devuelve 404 o agota el tiempo de espera.
- El Data URI no es base64 válido.
- name_text tiene más de 10 caracteres. Meshy lo rechaza en lugar de acortarlo, y no cobra por la solicitud.
- La imagen o name_text fue marcado como NSFW.
El mensaje de error indica qué problema encontró. Corrige la solicitud y envíala de nuevo.
Name
401 - Unauthorized
Description
La clave de API falta o no es válida. Revisa el encabezado Authorization.
Name
402 - Payment Required
Description
Aplica uno de los siguientes casos:
- 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 IP Filtering activado, y Meshy marcó la imagen por propiedad intelectual de terceros. Envía una imagen sobre la que tengas los derechos de uso. Meshy verifica la propiedad intelectual solo en la imagen, no en name_text.
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.
- Demasiadas de tus tareas están en cola o en ejecución. Espera a que algunas terminen 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 una tarea termine, o agrega créditos.
Name
500 - Internal Server Error
Description
Meshy encontró un error de servidor, por ejemplo porque no pudo ejecutar la verificación de propiedad intelectual sobre la imagen. Meshy no crea la tarea, y reembolsa cualquier crédito que haya cobrado. Vuelve a intentar la solicitud.

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

Crear una tarea de construcción de Keychain

Genera el llavero apto para impresión 3D a partir de una tarea de prototipo exitosa. Meshy convierte la imagen conceptual del prototipo en un relieve de mapa de profundidad y devuelve un archivo de modelo en el formato que elijas. Para conocer los campos de la tarea, consulta El objeto de tarea de construcción de Keychain.

Request

POST

/openapi/creative-lab/keychain/v1/build

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "options": {
      "badge_shape": "circle",
      "size_mm": 40,
      "relief_height_mm": 2.5
    },
    "output": {
      "format": "glb"
    }
  }'

Response

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

Build example

The build task converts the selected prototype image into a 3D-printable keychain model.

Creative Lab Keychain build model preview — Build model preview

Parámetros

Name
input_task_id
Type
string
Requerido
Description
El ID de la tarea de prototipo a construir. Debe ser una tarea creada por tu cuenta con POST /openapi/creative-lab/keychain/v1/prototype, con el estado SUCCEEDED.
Un ID que no corresponda a una de tus tareas de prototipo de Keychain de la API devuelve 404, incluyendo un prototipo creado en la aplicación web.
Name
name
Type
string
Description
Un nombre para la tarea, de hasta 100 caracteres. Se devuelve en el campo name de la tarea. Un nombre más largo devuelve 400.

`options`

Configuraciones opcionales para la forma del relieve. Cada campo tiene un valor predeterminado, así que envía solo los que quieras cambiar. Un valor fuera del rango de un campo devuelve 400.

Name
badge_shape
Type
string
predeterminado circle
Description
El contorno del llavero cuando Meshy no lo traza a partir del sujeto. Meshy lo usa cuando remove_background es false, o cuando no puede encontrar el contorno del sujeto.
Valores disponibles:
- circle
- rounded-rect
- hexagon
- shield
- star
Name
size_mm
Type
number
predeterminado 40
Description
La longitud del lado del cuadrado delimitador del llavero, en milímetros, hasta 400. 0 usa el valor predeterminado.
Name
relief_height_mm
Type
number
predeterminado 2.2
Description
La altura máxima del relieve sobre la base, en milímetros, de 0 a 20.
Name
relief_offset_mm
Type
number
predeterminado 0
Description
Cuánto bajar el relieve, en milímetros, de 0 a 20. Meshy lo resta de la altura del relieve en todas partes, hasta la base.
Name
base_thickness_mm
Type
number
predeterminado 0.1
Description
El grosor de la placa base plana detrás del relieve, en milímetros, de 0 a 20.
Name
has_closed_back
Type
boolean
predeterminado true
Description
Si se debe cerrar la parte posterior del llavero. false deja la parte posterior abierta, como una carcasa.
Name
relief_curve
Type
string
predeterminado linear
Description
La curva que asigna los valores del mapa de profundidad a la altura del relieve.
Valores disponibles:
- linear
- gamma
- s-curve
Name
curve_param
Type
number
predeterminado 1.0
Description
La intensidad de la curva, hasta 10. Las curvas gamma y s-curve la usan, y linear la ignora. 0 usa el valor predeterminado.
Name
invert_depth
Type
boolean
predeterminado false
Description
Si se debe invertir el mapa de profundidad, de modo que las áreas más oscuras se conviertan en un relieve más alto.
Name
smoothing
Type
number
predeterminado 0.24
Description
Cuánto suavizar el mapa de profundidad antes de que Meshy construya el relieve, de 0 a 10.
Name
relief_scale
Type
number
predeterminado 1.0
Description
Cuánto acercar el relieve y su textura dentro del contorno, respecto al centro, hasta 10. Un valor superior a 1 agranda el sujeto, y un valor inferior a 1 lo reduce. No cambia la altura del relieve. 0 usa el valor predeterminado.
Name
depth_threshold
Type
number
predeterminado 0.1
Description
El valor del mapa de profundidad por debajo del cual Meshy establece la profundidad en cero, de 0 a 1.
Name
remove_background
Type
boolean
predeterminado true
Description
Si se debe trazar el contorno del llavero a partir del sujeto, de modo que el llavero siga la forma del sujeto. false usa en su lugar el contorno de badge_shape. Meshy también usa badge_shape cuando no puede encontrar el contorno del sujeto.
Esto es independiente del parámetro remove_background del prototipo, que establece si la imagen del prototipo tiene un fondo transparente.
Name
export_resolution
Type
integer
predeterminado 512
Description
La resolución de la malla del modelo exportado, de 64 a 512. Meshy construye la geometría a partir de un mapa de profundidad de 512 píxeles, así que una malla más fina añadiría caras sin añadir detalle. 0 usa el valor predeterminado.

`output`

Opcional. Establece el formato de archivo que devuelve la construcción.

Name
format
Type
string
predeterminado glb
Description
El formato de archivo que devuelve la construcción.
Valores disponibles:
- glb: un archivo model.glb, en model_urls.glb
- obj: un archivo zip con model.obj, model.mtl y texture.png, en model_urls.obj
- zip: un archivo zip con todos los archivos que genera Meshy, en model_urls.bundle_zip

Devuelve

El campo result contiene el ID de la nueva tarea de construcción. Obtén la tarea o transmítela hasta que status sea SUCCEEDED. Luego descarga el archivo de la única entrada en model_urls.

Modos de falla

Name
400 - Bad Request
Description
La solicitud no se puede ejecutar. Por ejemplo:
- Falta input_task_id o no es un ID de tarea válido.
- El estado de la tarea de prototipo no es SUCCEEDED. Si todavía se está ejecutando, espera y vuelve a intentarlo. Si falló o fue cancelada, crea una nueva tarea de prototipo.
- La tarea de prototipo tuvo éxito pero no tiene imagen. Crea una nueva tarea de prototipo.
- Un campo de options está fuera de su rango o no es un valor disponible.
El mensaje de error indica qué problema encontró.
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 uno de los siguientes casos:
- 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
404 - Not Found
Description
input_task_id no coincide con ninguna tarea de prototipo de Keychain creada por tu cuenta con la API. Un prototipo creado en la aplicación web también devuelve 404. Envía el ID result de una respuesta de creación de prototipo.
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 finalicen algunas y vuelve a intentarlo.
- En un plan ilimitado sin créditos restantes, alcanzaste la cantidad de tareas que pueden ejecutarse sin créditos. Espera a que finalice una tarea, o añade créditos.

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

Obtener una tarea de Keychain

Devuelve una tarea de prototipo o de compilación. La ruta debe coincidir con la etapa de la tarea. Una tarea de compilación solicitada a través de /prototype/:id devuelve 404, y lo mismo ocurre con una tarea de prototipo solicitada a través de /build/:id.

Para conocer los campos, consulta El objeto de tarea de prototipo de Keychain y El objeto de tarea de compilación de Keychain.

Request

GET

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

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

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

Prototype Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-keychain-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-keychain-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": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}

Parámetros

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

Devuelve

El objeto de tarea de prototipo o el objeto de tarea de compilación, según la etapa indicada en la ruta.

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 de prototipo por propiedad intelectual de terceros. Las tareas de compilación y los equipos del plan Enterprise no reciben este error. Crea una tarea de prototipo a partir de una imagen sobre la que tengas los derechos de uso.
Name
404 - Not Found
Description
Ninguna tarea de Keychain con este ID pertenece a tu cuenta, o la etapa de la tarea no coincide con la ruta. Verifica el ID y usa /prototype o /build según corresponda a la tarea.
Name
500 - Internal Server Error
Description
Meshy no pudo ejecutar la verificación de propiedad intelectual. Reintenta la solicitud.

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

Eliminar una tarea de Keychain

Cancela una tarea de Keychain. 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.

La ruta debe coincidir con la etapa de la tarea. Por ejemplo, DELETE en /prototype/:id con el ID de una tarea de build devuelve 404.

Request

DELETE

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

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype/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 Keychain con este ID pertenece a tu cuenta, o la etapa de la tarea no coincide con la ruta. Verifica el ID y usa /prototype o /build para que coincida con la tarea.

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

Transmitir una tarea de Keychain

Transmite las actualizaciones de una tarea de Keychain como Server-Sent Events (SSE). La ruta debe coincidir con la etapa de la tarea. Si no es así, por ejemplo el ID de una tarea de build en /prototype/:id/stream, el stream envía un evento error con status_code: 404 y se cierra.

Request

GET

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

curl -N https://api.meshy.ai/openapi/creative-lab/keychain/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.
// 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": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-keychain-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}

Parámetros

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

Devuelve

Un stream de objetos de tarea prototype o build. Cada evento contiene el objeto de tarea completo, tal como lo devuelve Obtener una tarea de Keychain. 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 en su lugar un evento error, con el status_code que devolvería una solicitud get.

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

Listar tareas de Keychain

Devuelve tus tareas de llavero de una etapa, una página a la vez. La ruta selecciona la etapa. /prototype devuelve solo tareas de prototipo, y /build devuelve solo tareas de compilación.

Request

GET

/openapi/creative-lab/keychain/v1/prototype

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

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

Response (List Prototype Tasks)

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-keychain-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=***"
    ]
  }
]

Parámetros de ruta

Name
stage
Type
path
Requerido
Description
La etapa a listar, prototype o build.

Parámetros de consulta

Name
page_num
Type
integer
predeterminado 1
Description
La página a devolver, de 1 a 255. 0 devuelve la primera página. Un valor fuera del rango 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 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 arreglo de objetos de tarea de prototipo u objetos de tarea de compilación, correspondiente a la etapa indicada en la ruta.

El objeto de tarea de prototipo de Keychain

Una tarea de prototipo genera una imagen de concepto coloreada a partir de una foto. Para convertir la imagen en un modelo 3D, pasa el ID de la tarea al endpoint de build como input_task_id.

Propiedades

Example Keychain Prototype Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-keychain-prototype",
  "name": "",
  "name_text": "Luna",
  "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=***"
  ]
}

Name
id
Type
string
Description
El ID de la tarea. No confíes en su formato.
Name
type
Type
string
Description
El tipo de tarea, siempre creative-lab-keychain-prototype.
Name
name
Type
string
Description
El name que enviaste al crear la tarea, o "" si no enviaste ninguno.
Name
name_text
Type
string
Description
El nombre que Meshy añadió al llavero, después de recortar los espacios en blanco y eliminar caracteres de formato invisibles. Se omite cuando no enviaste name_text. Para comprobar que tu cliente HTTP codificó el texto correctamente, compáralo con lo que enviaste.
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 completado, 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. Es 3 días después de finished_at, o 3 días después de created_at hasta que la tarea termine. Para las cuentas Enterprise, que conservan los resultados de la API indefinidamente, es aproximadamente 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 comienza a continuación. 0 después de que la tarea sale de la cola, y siempre 0 en los resultados de lista.
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 get o stream omite el campo, y una solicitud de lista devuelve 500. En ese caso, reintenta la solicitud.
Name
image_urls
Type
array of strings
Description
URLs de descarga para la imagen de concepto. El array tiene una URL después de que la tarea tiene éxito, y está vacío hasta entonces.

El objeto de tarea de construcción de Keychain

Una tarea de construcción genera el llavero 3D a partir de una tarea de prototipo exitosa. Devuelve un archivo de modelo en el formato que solicitaste.

Propiedades

Example Keychain Build Task Object

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-keychain-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": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?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-keychain-build.
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 completado, de 0 a 100. Es 0 hasta que la tarea comienza y 100 cuando tiene éxito.
Name
created_at
Type
timestamp
Description
Momento en que se creó la tarea, en milisegundos Unix.
Name
started_at
Type
timestamp
Description
Momento en que un worker inició la tarea, en milisegundos Unix. null hasta entonces.
Name
finished_at
Type
timestamp
Description
Momento en que la tarea alcanzó un estado final, en milisegundos Unix. null hasta entonces.
Name
expires_at
Type
timestamp
Description
Momento 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 termina. Para las cuentas Enterprise, que conservan los resultados de la API indefinidamente, es 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 es la siguiente en comenzar. 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 cargo, una respuesta de obtención o de transmisión deja el campo fuera, y una solicitud de lista devuelve 500. En ese caso, reintenta la solicitud.
Name
model_urls
Type
object
Description
URLs de descarga para el archivo de modelo, con una entrada para el output.format que solicitaste. {} hasta que la tarea tenga éxito.
- Name
  glb
  Type
  string
  Description
  URL de descarga para el archivo GLB. Presente cuando output.format es glb.
- Name
  obj
  Type
  string
  Description
  URL de descarga para un archivo zip con model.obj, model.mtl, y texture.png. Presente cuando output.format es obj.
- Name
  bundle_zip
  Type
  string
  Description
  URL de descarga para un archivo zip con todos los archivos que genera Meshy. Presente cuando output.format es zip.