Creative Lab — API de Keycap

Foto de origen que Meshy convertirá en imágenes de diseño de keycap. Actualmente admitimos los formatos .jpg, .jpeg, .png y .webp.

El formato se detecta decodificando los datos de la imagen, no a partir de la extensión de archivo de la URL; una URL sin extensión, o que redirige, funciona siempre que los bytes se decodifiquen en un formato compatible. Se siguen las redirecciones HTTP. La orientación EXIF se normaliza, por lo que una foto de teléfono rotada se usa tal como se ve.

Límites: al menos 32 píxeles por cada lado, como máximo 178,956,970 píxeles en total, y como máximo 20,000,000 bytes una vez descargada. Para un Data URI, el límite se aplica a los bytes decodificados, por lo que el archivo de origen en sí puede llegar a ese tamaño; es el texto en base64 el que es aproximadamente un tercio más grande, lo cual afecta al cuerpo de tu solicitud, no a este límite. Un Data URI debe declarar un tipo de contenido image/* y ;base64.

Hay dos formas de proporcionar la imagen:

• URL de acceso público: Una URL que sea accesible desde internet público.
• 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>.

Nombre de tarea opcional para fines de visualización. Máximo 100 caracteres.

Cuando se establece en true, el render de visualización devuelto en image_urls es un PNG RGBA transparente con el fondo eliminado, para que puedas componerlo sobre cualquier fondo.

Esto se aplica únicamente al render de visualización. El candidato que consume el endpoint de build no se ve afectado, por lo que el resultado 3D es idéntico en ambos casos.

La solicitud fue inaceptable. Causas comunes:

• Falta un parámetro: 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 recuento máximo de píxeles.
• URL inaccesible: No se pudo descargar el image_url (404 o timeout).
• Data URI no válido: La cadena base64 está mal formada.
• Contenido marcado: La imagen de entrada fue marcada por la moderation de NSFW.

Falló la autenticación. Por favor, verifica tu clave de API.

La cuenta está en el plan gratuito (se requiere un plan de pago para crear tareas) o no tiene créditos suficientes.

La imagen de entrada fue marcada por la moderation de propiedad intelectual.

Has excedido tu límite de tasa.

Se produjo un error inesperado del lado del servidor; por ejemplo, el servicio de moderation de contenido no estaba disponible, falló la preparación de la imagen de entrada, o no se pudo crear la tarea. En este caso no se crea ninguna tarea, por lo que reintentar es seguro.

El ID de tarea de una tarea de prototipo creada mediante este mismo endpoint de OpenAPI. El prototipo debe haber sido creado por la misma cuenta de Meshy, debe haber alcanzado el estado SUCCEEDED y debe haber producido al menos un candidato.

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/keycap/v1/prototype y rechaza cualquier otra fuente con 404.

El candidato a construir, tomado del array candidate_ids de la tarea de prototipo exitosa. Debe pertenecer a esa tarea; cualquier otro valor se rechaza con 400.

Nombre de tarea opcional para fines de visualización. Máximo 100 caracteres.

La base de keycap sobre la que construir. Actualmente el único valor disponible es cherry-mx-1x1-r1 — un keycap estándar de perfil Cherry MX de 1u. Se planean 3–5 tamaños estándar adicionales convencionales; no se admiten tamaños personalizados.

Tamaño objetivo de la cabeza esculpida, en milímetros: su dimensión más larga se escala a este valor. Rango: [10, 40]. Los valores por encima de aproximadamente 32.9 pueden reducirse para que la cabeza siga ajustándose al límite de huella protectora de la base, por lo que la dimensión más larga entregada puede ser menor a la solicitada. El valor aplicado no se refleja hoy en el objeto de tarea — si necesitas confirmar el tamaño que realmente recibiste, mide la caja delimitadora de la malla keycap-head en el modelo descargado.

Desplazamiento vertical aplicado a la cabeza antes de que se asiente sobre la base, en milímetros. Rango: [-5, 5].

La solicitud fue inaceptable. Causas comunes:

• Parámetro faltante: se requieren input_task_id y candidate_id.
• UUID inválido: 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 candidatos: la tarea de prototipo tuvo éxito pero no produjo candidatos.
• Candidato desconocido: candidate_id no es uno de los candidatos de la tarea de entrada.
• Opciones fuera de rango: uno de los campos de options quedó fuera de su rango permitido o conjunto de valores enumerados.

Falló la autenticación. Por favor, verifica tu clave de API.

La cuenta está en el plan gratuito (se requiere un plan de pago para crear tareas) o no tiene créditos suficientes.

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

Has excedido tu límite de tasa.

Ocurrió un error inesperado del lado del servidor — por ejemplo, el servicio de moderation de contenido no estaba disponible, falló la preparación de la imagen de entrada, o la tarea no pudo crearse. En este caso no se crea ninguna tarea, por lo que es seguro reintentar.

Identificador único de la tarea de keycap que se desea recuperar.

Identificador único de la tarea de keycap que se va a cancelar.

La tarea ya está en un estado terminal y no se puede cancelar.

La tarea no existe, pertenece a otro usuario, o su etapa no coincide con la ruta de la URL.

Se produjo un error inesperado del servidor durante la cancelación. Es posible que la tarea se haya cancelado o no; vuelva a leerla para confirmarlo antes de reintentar.

Identificador único de la tarea de keycap que se va a transmitir.

Puede ser prototype o build. La colección devuelve solo las tareas cuya etapa coincide con la URL — obtener /prototype nunca devuelve tareas de build y viceversa.

Número de página para la paginación.

Límite de tamaño de página. El máximo permitido es 100 elementos.

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.

Identificador único de la tarea. Aunque usamos un UUID ordenable por k como detalle de implementación para los ids de tareas, no debes hacer ninguna suposición sobre el formato del id.

Tipo de la tarea. El valor es creative-lab-keycap-prototype.

El nombre de la tarea proporcionado al crearla. Cadena vacía si no se proporcionó ningún nombre.

Estado de la tarea. Los valores posibles son uno de PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Progreso de la tarea. Si la tarea aún no ha comenzado, esta propiedad será 0. Una vez que la tarea haya finalizado con éxito, será 100.

Marca de tiempo de cuándo se creó la tarea, en milisegundos.

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.

Marca de tiempo de cuándo finalizó la tarea, en milisegundos. Si la tarea aún no ha finalizado, esta propiedad será 0.

Marca de tiempo de cuándo caduca el resultado de la tarea, en milisegundos.

El recuento de tareas precedentes.

Detalles del error para tareas fallidas. Consulta Errores para la referencia completa del objeto task_error.

El número de créditos consumidos por esta tarea. Una tarea que alcanza SUCCEEDED se cobra el importe completo correspondiente a su etapa. Una tarea que nunca llega a crearse (un 4xx en el momento de la solicitud, incluido un rechazo de moderation) no se cobra en absoluto. Una tarea que alcanza FAILED devuelve 0: el cargo se reembolsa, incluido un bloqueo de moderation asíncrono. Cancelar mediante DELETE reembolsa solo mientras la tarea sigue en PENDING; una tarea que ya está IN_PROGRESS permanece cobrada, porque el trabajo ya se ha realizado.

URL descargable del render de diseño de keycap terminado, es decir, cómo se ve el candidato como keycap terminado. Contiene una única entrada; image_urls[i] corresponde a candidate_ids[i]. Vacío hasta que la tarea alcanza SUCCEEDED. La URL es solo para visualización; el endpoint de construcción consume candidate_ids, no estas URLs. Mismo ciclo de vida de URL que model_urls: firmada, sin encabezado Authorization, válida hasta expires_at, y estable al volver a leer la tarea.

Identificadores de candidato opacos, en paralelo con image_urls. Pasa la entrada que corresponda a tu diseño elegido como el candidate_id de la solicitud de construcción. No hagas ninguna suposición sobre el formato de estos ids.

Identificador único de la tarea.

Tipo de la tarea. El valor es creative-lab-keycap-build.

El nombre de la tarea proporcionado al crearla. Cadena vacía si no se proporcionó ningún nombre.

Estado de la tarea. Los valores posibles son uno de PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Progreso de la tarea. Si la tarea aún no ha comenzado, esta propiedad será 0. Una vez que la tarea haya finalizado con éxito, será 100.

Marca de tiempo de cuándo se creó la tarea, en milisegundos.

Marca de tiempo de cuándo se inició la tarea, en milisegundos.

Marca de tiempo de cuándo finalizó la tarea, en milisegundos.

Marca de tiempo de cuándo caduca el resultado de la tarea, en milisegundos.

El número de tareas precedentes. Solo tiene sentido cuando el estado es PENDING.

Detalles del error para tareas fallidas. Consulta Errores para la referencia completa del objeto task_error.

El número de créditos consumidos por esta tarea. A una tarea que llega a SUCCEEDED se le cobra el importe completo correspondiente a su etapa. A una tarea que nunca llega a crearse (un 4xx en el momento de la solicitud, incluido un rechazo por moderation) no se le cobra nada en absoluto. Una tarea que llega a FAILED devuelve 0 — el cargo se reembolsa, incluido un bloqueo asíncrono de moderation. Cancelar mediante DELETE solo reembolsa mientras la tarea sigue en PENDING; una tarea que ya está en IN_PROGRESS sigue cobrada, porque el trabajo ya se ha realizado.

URLs descargables para los artefactos del modelo generado. Tanto el GLB como el paquete OBJ se exportan a escala real en milímetros, con eje Y hacia arriba, con el frente del keycap orientado hacia +Z. Las mallas se llaman keycap-head y keycap-base; cuando la base recurre a un relleno de patrón, también está presente una tercera malla keycap-base-interior para la cavidad del vástago. No asumas que siempre hay exactamente dos mallas.

Estas son URLs firmadas: obténlas sin un encabezado Authorization. Permanecen válidas hasta expires_at, que es 3 días después de finished_at, y volver a leer la tarea dentro de esa ventana devuelve la misma URL en lugar de una recién firmada. Descarga y almacena los archivos tú mismo antes de eso — no hay forma de renovar un enlace caducado.

URLs descargables para las imágenes intermedias del proceso, indexadas por tipo. Mismo ciclo de vida de URL que model_urls: firmadas, sin encabezado Authorization, válidas hasta expires_at, y estables cuando se vuelve a leer la tarea. Tipos emitidos actualmente:

• head_design — la imagen de diseño del candidato elegido que consumió la construcción (siempre presente).
• composite — el render de visualización del keycap terminado del candidato elegido (presente cuando está disponible).
• base_canvas — el lienzo pintado de la base del keycap (presente cuando está disponible).

Trata el conjunto de claves como abierto; se pueden añadir nuevos tipos sin que constituya un cambio disruptivo.