Creative Lab — Keycap API

Foto fuente para que Meshy la convierta en imágenes de diseño de tecla. Actualmente soportamos los formatos .jpg, .jpeg, .png y .webp.

El formato se detecta decodificando los datos de la imagen, no a partir de la extensión del archivo de la URL — una URL sin extensión, o una que redirige, funciona siempre que los bytes se decodifiquen a 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 en 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 fuente en sí puede tener hasta ese tamaño — es el texto base64 el que es aproximadamente un tercio más grande, lo que importa para el cuerpo de tu solicitud, no para este límite. Un Data URI debe declarar un tipo de contenido image/* y ;base64.

Hay dos formas de proporcionar la imagen:

• URL accesible públicamente: Una URL que es accesible desde internet público.
• Data URI: Un Data URI codificado en base64 de la imagen. Ejemplo de un Data URI: data:image/jpeg;base64,<tus datos de imagen codificados en base64>.

Nombre de tarea opcional para propósitos 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 solo al render de visualización. El candidato que consume el endpoint de construcción no se ve afectado, por lo que el resultado 3D es idéntico de cualquier manera.

La solicitud fue inaceptable. Causas comunes:

• Parámetro faltante: image_url es requerido.
• Formato de imagen no válido: El image_url proporcionado no es 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 conteo máximo de píxeles.
• URL inalcanzable: El image_url no se pudo descargar (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 NSFW.

La autenticación falló. 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 suficientes créditos.

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

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 no se pudo crear la tarea. No se crea ninguna tarea en este caso, por lo que reintentar es seguro.

El ID de la tarea de un prototipo creado a través de este mismo endpoint de OpenAPI. El prototipo debe haber sido creado por la misma cuenta de Meshy, debe haber alcanzado SUCCEEDED, y debe haber producido al menos un candidato.

Las tareas de prototipo creadas a través de la aplicación web no son aceptadas — 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 es rechazado con 400.

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

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

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 ser reducidos para que la cabeza aún se ajuste al límite de la 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 en el objeto de la tarea hoy en día — 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 en la base, en milímetros. Rango: [-5, 5].

La solicitud no fue aceptable. Causas comunes:

• Parámetro faltante: input_task_id y candidate_id son requeridos.
• UUID inválido: El input_task_id no es un UUID válido.
• Padre no exitoso: 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 options cayó fuera de su rango permitido o conjunto de enumeración.

La autenticación falló. 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 suficientes créditos.

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 en la construcción).

Has excedido tu límite de tasa.

Ocurrió un error inesperado del lado del servidor — por ejemplo, el servicio de moderación de contenido no estaba disponible, la puesta en escena de la imagen de entrada falló, o la tarea no pudo ser creada. No se crea ninguna tarea en este caso, por lo que volver a intentarlo es seguro.

Identificador único para la tarea de keycap a recuperar.

Identificador único para la tarea de keycap a cancelar.

La tarea ya está en un estado terminal y no puede ser cancelada.

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

Ocurrió un error inesperado del lado del servidor al cancelar. La tarea puede o no haber sido cancelada — vuelva a leerla para confirmar antes de reintentar.

Identificador único para la tarea de keycap a transmitir.

Ya sea prototype o build. La colección devuelve solo tareas cuya etapa coincide con la URL — al buscar /prototype nunca se devuelven tareas de construcción y viceversa.

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

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

Campo para ordenar. Valores disponibles:

• +created_at: Ordenar por tiempo de creación en orden ascendente.
• -created_at: Ordenar por tiempo de creación en orden descendente.

Identificador único para la tarea. Aunque usamos un UUID ordenable por clave para los ids de tarea como detalle de implementación, 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 cuando se creó la tarea. Cadena vacía si no se proporcionó un 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 tenido éxito, esto se convertirá en 100.

Marca de tiempo de cuando se creó la tarea, en milisegundos.

Marca de tiempo de cuando se inició la tarea, en milisegundos. Si la tarea aún no ha comenzado, esta propiedad será 0.

Marca de tiempo de cuando se terminó la tarea, en milisegundos. Si la tarea aún no ha terminado, esta propiedad será 0.

Marca de tiempo de cuando expira el resultado de la tarea, en milisegundos.

El conteo de tareas precedentes.

Detalles de 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 monto total por su etapa. Una tarea que nunca se crea (un 4xx en el momento de la solicitud, incluida una moderación rechazada) no se cobra en absoluto. Una tarea que alcanza FAILED devuelve 0 — el cargo es reembolsado, incluyendo un bloqueo de moderación asincrónico. Cancelar a través de DELETE solo reembolsa mientras la tarea aún está PENDING; una tarea ya IN_PROGRESS permanece cobrada, porque el trabajo ha sido gastado.

URL descargable del render del diseño de keycap terminado — cómo se ve el candidato como un keycap terminado. Contiene una sola 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 cuando se vuelve a leer la tarea.

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

Identificador único para la tarea.

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

El nombre de la tarea proporcionado cuando se creó la tarea. Cadena vacía si no se proporcionó un 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 tenido éxito, esto se convertirá en 100.

Marca de tiempo de cuando se creó la tarea, en milisegundos.

Marca de tiempo de cuando se inició la tarea, en milisegundos.

Marca de tiempo de cuando se terminó la tarea, en milisegundos.

Marca de tiempo de cuando expira el resultado de la tarea, en milisegundos.

El conteo de tareas precedentes. Significativo solo cuando el estado es PENDING.

Detalles del error para tareas fallidas. Consulte 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 monto total por su etapa. Una tarea que nunca se crea (un 4xx en el momento de la solicitud, incluida una moderación rechazada) no se cobra en absoluto. Una tarea que alcanza FAILED devuelve 0 — el cargo es reembolsado, incluida una moderación asincrónica bloqueada. Cancelar a través de DELETE solo reembolsa mientras la tarea aún está PENDING; una tarea ya IN_PROGRESS permanece cobrada, porque el trabajo ha sido gastado.

URLs descargables para los artefactos del modelo generado. Tanto el GLB como el paquete OBJ se exportan a escala milimétrica del mundo real, Y-arriba, con el frente del keycap mirando hacia +Z. Las mallas se nombran 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 asuma exactamente dos mallas.

Estas son URLs firmadas: recupérelas sin un encabezado de 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 URL idéntica en lugar de una recién firmada. Descargue y almacene los archivos usted mismo antes de entonces — no hay forma de actualizar un enlace expirado.

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

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

Trate el conjunto de claves como abierto; se pueden agregar nuevos tipos sin un cambio disruptivo.