Retexture API es una característica que te permite integrar las capacidades de retetexturización de IA de Meshy en tu propia aplicación. En esta sección,
encontrarás toda la información que necesitas para comenzar con esta API.
Este endpoint te permite crear una nueva tarea de Retexturizado. Consulta
El Objeto de Tarea de Retexturizado para ver qué
propiedades están incluidas en el objeto de tarea de Retexturizado.
Parámetros
Solo es requerido uno de input_task_id o model_url. Si se proporcionan ambos, input_task_id tiene prioridad.
Name
input_task_id
Type
string
Requerido
Description
El ID de la tarea completada de Imagen a 3D o Texto a 3D que deseas retexturizar.
Esta tarea debe ser una de las siguientes tareas: Vista previa de Texto a 3D, Refinar Texto a 3D, Imagen a 3D o Remallado.
Además, debe tener un estado de SUCCEEDED.
Name
model_url
Type
string
Requerido
Description
Proporciona un modelo 3D para que Meshy le aplique texturas. Formatos soportados: .glb, .gltf, .obj, .fbx, .stl.
Hay dos maneras de proporcionar el modelo:
URL accesible públicamente: Una URL que es accesible desde la internet pública.
Data URI: Un Data URI codificado en base64 del modelo. Usa MIME type application/octet-stream.
Ejemplo: data:application/octet-stream;base64,<tu modelo codificado en base64>.
Exactamente una entrada de estilo es requerida: text_style_prompt, image_style_url o multiview_image_urls.
multiview_image_urls no se puede combinar con ninguno de los otros dos; si se proporcionan ambos text_style_prompt y image_style_url, image_style_url tiene prioridad.
Name
text_style_prompt
Type
string
Requerido
Description
Describe el estilo de textura deseado del objeto usando texto. Máximo 600 caracteres.
Name
image_style_url
Type
string
Requerido
Description
Proporciona una imagen 2D para guiar el proceso de texturizado. Actualmente soportamos los formatos .jpg, .jpeg y .png.
Hay dos maneras de proporcionar la imagen:
URL accesible públicamente: Una URL que es accesible desde la internet pública
Data URI: Un Data URI codificado en base64 de la imagen. Ejemplo de un Data URI:
data:image/jpeg;base64,<tu imagen codificada en base64>
El texturizado de imágenes puede no funcionar óptimamente si hay diferencias importantes en geometría entre el asset original y la imagen cargada.
Name
multiview_image_urls
Type
string[]
Requerido
Description
Proporciona de 1 a 4 imágenes que muestren el mismo objeto desde diferentes vistas para guiar el texturizado.
La primera imagen es la vista principal (frontal); el orden de las vistas restantes (izquierda, trasera, derecha) no importa.
Cada elemento acepta los mismos formatos que image_style_url (una URL accesible públicamente o un Data URI base64, .jpg/.jpeg/.png).
Requiere ai_model: "meshy-7" (o latest).
Name
ai_model
Type
string
predeterminado latest
Description
ID del modelo de IA a utilizar para el retexturizado. Valores disponibles: meshy-5, meshy-6, meshy-7, latest (Meshy 7).
Name
enable_original_uv
Type
boolean
predeterminado false
Description
Mantén la distribución UV existente del modelo en lugar de generar una nueva.
Si estás retexturizando un modelo generado por Meshy (a través de un input_task_id, o un model_url que apunte a un resultado de Meshy),
establece esto a true para reutilizar su distribución UV optimizada.
Si estás retexturizando un modelo de terceros que has cargado, establece true cuando ya tenga UVs buenos que quieras conservar, o déjalo
false para que Meshy desenvuelva nuevas UVs (mejor para modelos que carecen de mapeo UV adecuado).
Name
enable_pbr
Type
boolean
predeterminado false
Description
Genera Mapas PBR (metálico, rugosidad, normal) además del color base. Un mapa de emisión también
está incluido cuando ai_model es meshy-6, excepto a texture_resolution: 8k.
meshy-7 y latest no producen un mapa de emisión.
Name
texture_resolution
Type
string
predeterminado 2k
Description
Resolución de textura de color base. Una de 2k (2048×2048), 4k (4096×4096) o 8k (8192×8192). Las resoluciones más altas capturan más detalle en la superficie.
4k y 8k requieren ai_modelmeshy-6, meshy-7 o latest. A 8k, no se produce ningún mapa de emisión.
Name
hd_texture
Type
boolean
⚠ obsoleto
predeterminado false
Description
Usa texture_resolution en su lugar — equivalente a texture_resolution: "4k". Cuando ambos están configurados, texture_resolution prevalece.
Name
remove_lighting
Type
boolean
predeterminado true
Description
Elimina reflejos y sombras del color base de la textura, produciendo un resultado más limpio que funciona mejor bajo configuraciones de iluminación personalizadas.
Solo es compatible cuando ai_model es meshy-6.
Name
target_formats
Type
string[]
Description
Especifica qué formatos de archivo 3D incluir en la salida. Solo se generarán y devolverán los formatos solicitados, lo que puede reducir el tiempo de finalización de la tarea.
Cuando se omite, se incluyen todos los formatos soportados.
Cuando se omite, se generan todos los formatos excepto 3mf. 3mf solo se incluye cuando se especifica explícitamente.
Name
alpha_thumbnail
Type
boolean
predeterminado false
Description
Cuando se establece en true, la tarea además renderiza una versión de vista previa con fondo transparente (RGBA) y la devuelve como alpha_thumbnail_url en la respuesta GET. El campo thumbnail_url existente no cambia.
Devuelve
La propiedad result de la respuesta contiene el id de la tarea de Retexturizado recién creada.
Modos de Fallo
Name
400 - Bad Request
Description
La solicitud era inaceptable. Causas comunes:
Parámetro faltante: Se debe proporcionar model_url o input_task_id.
Estilo faltante: Se debe proporcionar uno de text_style_prompt, image_style_url o multiview_image_urls.
Entradas de estilo conflictivas: multiview_image_urls no puede combinarse con text_style_prompt o image_style_url.
Modelo no compatible para vista múltiple: multiview_image_urls requiere ai_model: "meshy-7" (o latest).
Modelo no disponible: ai_model: "meshy-7" se está implementando progresivamente y aún no está habilitado para tu cuenta.
Tarea de entrada no válida: El input_task_id debe referirse a una tarea exitosa de un modelo compatible.
Formato de modelo no válido: El model_url apunta a un archivo con una extensión no compatible.
URL no accesible: El model_url, image_style_url o un elemento de multiview_image_urls no se pudo descargar.
Name
401 - Unauthorized
Description
La autenticación falló. Por favor verifica tu clave de API.
Name
402 - Payment Required
Description
Créditos insuficientes para realizar esta tarea.
Name
429 - Too Many Requests
Description
Has excedido tu límite de tasa.
Request
POST
/openapi/v1/retexture
# Retexturizar con prompt de textocurlhttps://api.meshy.ai/openapi/v1/retexture \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "model_url": "https://cdn.meshy.ai/model/example_model_2.glb", "text_style_prompt": "colmillos rojos, traje de Samurai que se fusiona con el estilo batik japonés", "enable_original_uv": true, "enable_pbr": true }'# Retexturizar con estilo de imagen y PBRcurlhttps://api.meshy.ai/openapi/v1/retexture \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "model_url": "https://cdn.meshy.ai/model/example_model_2.glb", "image_style_url": "https://cdn.meshy.ai/image/example_image.jpg", "ai_model": "latest", "enable_pbr": true, "enable_original_uv": true }'
Este endpoint te permite obtener una tarea de Retexturizado dado un id de tarea válido.
Consulta El Objeto de Tarea de Retexturizado para ver qué
propiedades están incluidas en el objeto de tarea de Retexturizado.
Parámetros
Name
id
Type
path
Description
Identificador único para la tarea de Retexturizado a obtener.
{"id":"018a210d-8ba4-705c-b111-1f1776f7f578","type":"retexture","model_urls": {"glb":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***","fbx":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***","obj":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***","usdz":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***","mtl":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***","stl":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***" },"thumbnail_url":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***","text_style_prompt":"colmillos rojos, traje de Samurai que se fusiona con el estilo batik japonés","texture_image_url":"","progress":100,"started_at":1692771667037,"created_at":1692771650657,"expires_at":1692771679037,"finished_at":1692771669037,"status":"SUCCEEDED","texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***","metallic":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX","normal":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX","roughness":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX","emission":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX" } ],"task_error": {"message":"" },"consumed_credits":10}
[ {"id":"018a210d-8ba4-705c-b111-1f1776f7f578","type":"retexture","model_urls": {"glb":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***","fbx":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***","usdz":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***" },"thumbnail_url":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***","text_style_prompt":"colmillos rojos, traje de Samurai que se fusiona con el estilo batik japonés","progress":100,"started_at":1692771667037,"created_at":1692771650657,"expires_at":1692771679037,"finished_at":1692771669037,"status":"SUCCEEDED","texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***","metallic":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX","normal":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX","roughness":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX","emission":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX" } ],"preceding_tasks":0,"task_error": {"message":"" },"consumed_credits":10 }]
El objeto de Tarea de Retexturizado es una unidad de trabajo que Meshy utiliza para generar una textura 3D a partir de entradas de texto o imagen.
El modelo tiene las siguientes propiedades:
Propiedades
Name
id
Type
string
Description
Identificador único para la tarea. Aunque usamos un UUID ordenable por k para los ids de tarea como detalle de implementación, no debes hacer ninguna suposición sobre el formato del id.
Name
type
Type
string
Description
Tipo de la tarea de Retexturizado. El valor es retexture.
Name
model_urls
Type
object
Description
URL descargable del archivo de modelo 3D texturizado generado por Meshy.
Name
glb
Type
string
Description
URL descargable del archivo GLB.
Name
fbx
Type
string
Description
URL descargable del archivo FBX.
Name
obj
Type
string
Description
URL descargable del archivo OBJ.
Name
usdz
Type
string
Description
URL descargable del archivo USDZ.
Name
mtl
Type
string
Description
URL descargable del archivo MTL, devuelto junto con exportaciones OBJ cuando hay texturas presentes.
Name
stl
Type
string
Description
URL descargable del archivo STL.
Name
3mf
Type
string
Description
URL descargable del archivo 3MF. Solo presente cuando 3mf fue solicitado a través de target_formats.
Name
text_style_prompt
Type
string
Description
Este es el prompt de texto que se utilizó para crear la tarea de texturizado.
Name
image_style_url
Type
string
Description
Esta es la imagen de entrada que se utilizó para crear la tarea de texturizado.
Name
multiview_image_urls
Type
string[]
Description
URLs descargables de las imágenes de referencia de vista múltiple que se utilizaron para crear la tarea de texturizado. Solo presente cuando la tarea se creó con multiview_image_urls.
Name
thumbnail_url
Type
string
Description
URL descargable de la imagen miniatura del archivo de modelo.
Name
alpha_thumbnail_url
Type
string
Description
URL descargable de una versión de thumbnail_url con fondo transparente (RGBA). Solo presente cuando la tarea se creó con alpha_thumbnail: true y la vista previa transparente se renderizó exitosamente; de lo contrario, este campo se omite.
Name
progress
Type
integer
Description
Progreso de la tarea. Si la tarea aún no se ha iniciado, esta propiedad será 0. Una vez que la tarea haya tenido éxito, esto se convertirá en 100.
Name
started_at
Type
timestamp
Description
Marca de tiempo de cuando la tarea comenzó, en milisegundos. Si la tarea aún no se ha iniciado, esta propiedad será 0.
Una marca de tiempo representa el número de milisegundos transcurridos desde el 1 de enero de 1970 UTC, siguiendo el
estándar RFC 3339.
Por ejemplo, el viernes 1 de septiembre de 2023 a las 12:00:00 PM GMT se representa como 1693569600000.
Esto aplica a todas las marcas de tiempo en Meshy API.
Name
created_at
Type
timestamp
Description
Marca de tiempo de cuando la tarea fue creada, en milisegundos.
Name
expires_at
Type
timestamp
Description
Marca de tiempo de cuando el resultado de la tarea expira, en milisegundos.
Name
finished_at
Type
timestamp
Description
Marca de tiempo de cuando la tarea fue finalizada, en milisegundos. Si la tarea aún no ha finalizado, esta propiedad será 0.
Name
status
Type
string
Description
Estado de la tarea. Los valores posibles son uno de PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Un array de objetos URL de texturas que se generan a partir de la tarea. Normalmente, esto solo contiene un objeto URL de textura. Cada URL de textura tiene las siguientes propiedades:
Name
base_color
Type
string
Description
URL descargable de la imagen del mapa de color base.
Name
metallic
Type
string
Description
URL descargable de la imagen del mapa metálico.
Si la tarea se crea con enable_pbr: false, esta propiedad será omitida.
Name
normal
Type
string
Description
URL descargable de la imagen del mapa de normales.
Si la tarea se crea con enable_pbr: false, esta propiedad será omitida.
Name
roughness
Type
string
Description
URL descargable de la imagen del mapa de rugosidad.
Si la tarea se crea con enable_pbr: false, esta propiedad será omitida.
Name
emission
Type
string
Description
URL descargable de la imagen del mapa de emisión.
Si la tarea se crea con enable_pbr: false, o ai_model es meshy-5, esta propiedad será omitida.
Name
preceding_tasks
Type
integer
Description
El conteo de tareas precedentes.
Esta propiedad solo está presente cuando el estado de la tarea es PENDING.
Name
task_error
Type
object
Description
Detalles de error para tareas fallidas. Consulta Errores para la referencia completa del objeto task_error.
Name
consumed_credits
Type
integer
Description
El número de créditos consumidos por esta tarea. Presente cuando el estado de la tarea es PENDING, IN_PROGRESS, o SUCCEEDED. Se devuelve 0 para tareas FAILED (los créditos son reembolsados en caso de fallo).
Example Retexture Task Model
{"id":"018a210d-8ba4-705c-b111-1f1776f7f578","type":"retexture","model_urls": {"glb":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***","fbx":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***","usdz":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***" },"text_style_prompt":"colmillos rojos, traje de Samurai que se fusiona con el estilo batik japonés","image_style_url":"https://assets.meshy.ai/***/image/example_image.jpg?Expires=***","thumbnail_url":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***","progress":100,"started_at":1692771667037,"created_at":1692771650657,"expires_at":1692771679037,"finished_at":1692771669037,"status":"SUCCEEDED","texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***","metallic":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX","normal":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX","roughness":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX","emission":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX" } ],"preceding_tasks":0,"task_error": {"message":"" },"consumed_credits":10}