Creative Lab — Fidget Pixel API

Foto de origen para que Meshy la pixelice. 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 una que redirige, funciona siempre que los bytes se decodifiquen a un formato compatible. Se siguen las redirecciones HTTP.

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 en base64 de la imagen. Ejemplo de un Data URI: data:image/jpeg;base64,<tus datos de imagen codificados en base64>.

Lo que muestra la foto. Selecciona el estilo de pixelización, así que elige con cuidado — las dos opciones producen resultados visiblemente diferentes. Valores disponibles:

• person — el sujeto es una persona (retrato o cuerpo completo). Produce un sprite de pixel-art estilo chibi del sujeto.
• other — cualquier otra cosa: mascotas, objetos, mascotas de marca, logotipos, paisajes. Produce un icono de pixel-art estilo bead-art del sujeto.

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

La solicitud no era aceptable. Causas comunes:

• Parámetro faltante: image_url y type son ambos obligatorios.
• Tipo no válido: type debe ser person o other.
• 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 inalcanzable: No se pudo descargar el image_url (404 o timeout).
• Data URI no válido: La cadena en base64 está malformada.
• Contenido marcado: La imagen de entrada fue marcada por la moderation de contenido NSFW.

Error de autenticación. Comprueba tu clave de API.

Créditos insuficientes para realizar esta tarea, o la clave de API pertenece a una cuenta de plan gratuito.

La imagen de entrada fue marcada por la moderation de propiedad intelectual (Content flagged for intellectual property violation). Solo se bloquean las cuentas Enterprise con el filtrado de propiedad intelectual activado; no se cobra nada.

Has superado tu límite de tasa.

No se pudo completar la propia verificación de propiedad intelectual (Unable to perform intellectual property check, please try again). Las cuentas Enterprise con el filtrado de propiedad intelectual activado fallan de forma segura (fail closed) en esta verificación; no se cobra nada — vuelve a intentar la solicitud.

El ID de tarea de una tarea de prototipo creada a través de este mismo endpoint de OpenAPI. El prototipo debe haber sido creado por la misma cuenta de Meshy y debe haber alcanzado SUCCEEDED.

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

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

Forma de la base de cada pieza. Valores disponibles:

• square (predeterminado) — piezas cuadradas en una cuadrícula cuadrada.
• hex — piezas hexagonales en una cuadrícula hexagonal. Las piezas hexagonales están disponibles solo en 6 y 8 mm.

Número de piezas a lo largo de cada lado del tablero. Valores disponibles: 16 o 32. Una cuadrícula de 32 conserva más detalle; una cuadrícula de 16 significa piezas menos numerosas y más grandes para el mismo sujeto.

Longitud de arista de cada pieza, en milímetros. Valores disponibles: 6, 8 o 10. Junto con grid_size, esto establece el tamaño del tablero impreso — por ejemplo 32 × 8 mm ≈ 26 cm por lado. 10 no está disponible para shape: "hex" (la cara hexagonal inclinada genera voladizos en la mayoría de las impresoras FDM de consumo).

Número máximo de colores en la paleta a la que se cuantiza la imagen. Rango: [1, 8]. Cada color se convierte en un filamento en tu laminador.

Altura de cada pieza, en milímetros. Rango: [10, 80].

Artefacto devuelto por la construcción. Valores disponibles:

• 3mf (predeterminado) — devuelve un único model.3mf bajo model_urls.3mf, con un objeto por pieza y el color de la pieza adjunto a cada objeto.

La solicitud fue inaceptable. Causas comunes:

• Parámetro faltante: input_task_id es obligatorio.
• UUID inválido: input_task_id no es un UUID válido.
• El padre no tuvo éxito: La tarea de prototipo referenciada aún no ha alcanzado SUCCEEDED.
• Sin candidato: La tarea de prototipo tuvo éxito pero no produjo ninguna imagen de pixel art; crea un nuevo prototipo.
• Opciones fuera de rango: Uno de los campos de options está fuera de su conjunto o rango permitido — por ejemplo options.grid_size must be 16 or 32, o options.piece_size_mm=10 is not supported for shape=hex; hex pieces are available in 6 and 8 mm.
• Formato no compatible: output.format debe ser 3mf.

Error de autenticación. Verifica tu clave de API.

Créditos insuficientes para realizar esta tarea, o la clave de API pertenece a una cuenta de plan gratuito.

La imagen del prototipo referenciado fue marcada por la moderation de propiedad intelectual. Solo se bloquean las cuentas Enterprise con el filtrado de propiedad intelectual habilitado; no se cobra nada.

La tarea de prototipo referenciada no existe, pertenece a otro usuario, o fue creada a través de la aplicación web (solo las tareas de prototipo en mode API se encadenan a la construcción).

Has excedido tu límite de tasa.

No se pudo establecer el veredicto de propiedad intelectual del prototipo referenciado (Unable to perform intellectual property check, please try again). Las cuentas Enterprise con el filtrado de propiedad intelectual habilitado fallan de forma cerrada en esta verificación; no se cobra nada — vuelve a intentar la solicitud.

Identificador único de la tarea de fidget pixel que se desea recuperar.

id no es un UUID válido (Invalid ID).

La imagen de la tarea fue marcada por la moderación de propiedad intelectual. Solo las cuentas Enterprise con el filtrado de propiedad intelectual habilitado son bloqueadas.

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

No se pudo completar la verificación de propiedad intelectual (Unable to perform intellectual property check, please try again); las cuentas Enterprise con el filtrado de propiedad intelectual habilitado fallan de forma cerrada. Vuelve a intentar la solicitud.

Identificador único de la tarea de fidget pixel que se desea cancelar.

La solicitud fue inaceptable. Causas comunes:

• ID inválido: id no es un UUID válido.
• Estado terminal: La tarea ya está en SUCCEEDED, FAILED o CANCELED y no se puede cancelar.

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

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

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

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

Límite del 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 tarea, no debes hacer ninguna suposición sobre el formato del id.

Tipo de la tarea. El valor es creative-lab-fidget-pixel-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 se haya completado con éxito, esta 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 ha comenzado, esta propiedad será null.

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

Marca de tiempo de cuándo expira el resultado de la tarea, en milisegundos — 3 días después de que la tarea finalizó. Las cuentas empresariales conservan los resultados de la API indefinidamente (consulta Retención de recursos); para ellas, esta marca de tiempo se establece en aproximadamente 100 años en el futuro.

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. 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 — se reembolsa el cargo. Cancelar mediante DELETE solo reembolsa mientras la tarea aún esté en PENDING; una tarea que ya esté IN_PROGRESS mantiene el cargo, porque el trabajo ya se ha invertido.

URLs descargables para la imagen de pixel art generada por esta tarea de prototipo. Actualmente la API siempre devuelve exactamente una imagen; el campo es un array para que futuras revisiones puedan mostrar múltiples candidatas sin un cambio disruptivo. Vacío hasta que la tarea llega a SUCCEEDED.

Estas son URLs firmadas: obtenlas 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 ese momento — no hay forma de renovar un enlace expirado.

Identificador único de la tarea.

Tipo de la tarea. El valor es creative-lab-fidget-pixel-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 se ha iniciado, esta propiedad será 0. Una vez que la tarea haya finalizado con éxito, esta propiedad 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. null hasta que la tarea se inicia.

Marca de tiempo de cuándo finalizó la tarea, en milisegundos. null hasta que la tarea finaliza.

Marca de tiempo de cuándo expira el resultado de la tarea, en milisegundos: 3 días después de que la tarea finalizara. Las cuentas Enterprise conservan los resultados de la API de forma indefinida (consulta Retención de recursos); para ellas, esta marca de tiempo se establece con un adelanto de unos 100 años.

El recuento de tareas precedentes. Solo tiene sentido cuando el estado es PENDING.

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

El número de créditos consumidos por esta tarea. A una tarea que alcanza el estado 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 alcanza el estado FAILED devuelve 0: el cargo se reembolsa. Cancelar mediante DELETE solo reembolsa mientras la tarea sigue en estado PENDING; una tarea que ya está en IN_PROGRESS sigue teniendo el cargo, porque el trabajo ya se ha invertido.

URLs descargables para el recurso generado, indexadas por formato. Contiene exactamente una entrada: el formato solicitado mediante el output.format de la solicitud de compilación. Está vacío hasta que la tarea alcanza el estado SUCCEEDED.

Estas son URLs firmadas: obténlas sin una cabecera 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 firmada de nuevo. Descarga y almacena los archivos por tu cuenta antes de ese momento; no hay forma de renovar un enlace expirado.