Retexture API es una función que te permite integrar las capacidades de retexturización con IA de Meshy en tu propia aplicación. En esta sección, encontrarás toda la información
que necesitas para comenzar a usar esta API.
Este endpoint le permite crear una nueva tarea de Retexturizar. Consulte
El objeto de tarea Retexture para ver qué
propiedades se incluyen en el objeto de tarea Retexture.
Parámetros
Solo se requiere 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 desea retexturizar.
Esta tarea debe ser una de las siguientes: Text to 3D Preview, Text to 3D Refine, Image to 3D o Remesh. Además, debe tener un estado SUCCEEDED.
Name
model_url
Type
string
Requerido
Description
Proporcione un modelo 3D para que Meshy lo texturice. Formatos admitidos: .glb, .gltf, .obj, .fbx, .stl.
Hay dos formas de proporcionar el modelo:
URL de acceso público: una URL accesible desde internet público.
Data URI: un data URI del modelo codificado en base64. Use el MIME type application/octet-stream. Ejemplo: data:application/octet-stream;base64,<sus datos de modelo codificados en base64>.
Se requiere exactamente una entrada de estilo: text_style_prompt, image_style_url, o multiview_image_urls. multiview_image_urls no puede combinarse con ninguna de las otras dos; si se proporcionan tanto text_style_prompt como image_style_url, image_style_url tiene prioridad.
Name
text_style_prompt
Type
string
Requerido
Description
Describa el estilo de textura deseado para el objeto usando texto. Máximo 800 caracteres.
Name
image_style_url
Type
string
Requerido
Description
Proporcione una imagen 2D para guiar el proceso de texturizado. Actualmente admitimos los formatos .jpg, .jpeg y .png.
Hay dos formas de proporcionar la imagen:
URL de acceso público: una URL 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,<sus datos de imagen codificados en base64>
El texturizado de imagen puede no funcionar de manera óptima si hay diferencias sustanciales de geometría entre el asset original y la imagen subida.
Name
multiview_image_urls
Type
string[]
Requerido
Description
Proporcione 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, atrás, derecha) no importa.
Cada elemento acepta los mismos formatos que image_style_url (una URL de acceso público o un data URI en base64, .jpg/.jpeg/.png).
Requiere un ai_model: "meshy-7" explícito.
Name
ai_model
Type
string
predeterminado latest
Description
ID del modelo de IA a usar para el retexturizado. Valores disponibles: meshy-6-lite, meshy-6, meshy-7, latest (Meshy 7).
Name
enable_original_uv
Type
boolean
predeterminado false
Description
Mantiene la distribución UV existente del modelo en lugar de generar una nueva.
Si está retexturizando un modelo que Meshy generó (mediante input_task_id, o un model_url que apunta a una salida de Meshy), establezca esto en true para reutilizar su distribución UV optimizada.
Si está retexturizando un modelo de terceros que usted subió, establezca true cuando ya tenga buenas UV que desee conservar, o déjelo en false para que Meshy despliegue nuevas UV (lo mejor para modelos que carecen de un mapeo UV adecuado).
Name
enable_pbr
Type
boolean
predeterminado false
Description
Genera mapas PBR (metallic, roughness, normal) además del color base. También se incluye un mapa de emisión cuando ai_model es meshy-6, excepto en texture_resolution: 8k. meshy-6-lite, meshy-7 y latest no producen un mapa de emisión.
Name
texture_resolution
Type
string
predeterminado 2k
Description
Resolución de la textura de color base. Uno de 2k (2048×2048), 4k (4096×4096), u 8k (8192×8192). Resoluciones más altas capturan más detalle de superficie.
4k y 8k requieren que ai_model sea meshy-6, meshy-7 o latest. En 8k, no se produce ningún mapa de emisión.
Name
hd_texture
Type
boolean
⚠ obsoleto
predeterminado false
Description
Use texture_resolution en su lugar — equivalente a texture_resolution: "4k". Cuando se establecen ambos, texture_resolution tiene prioridad.
Name
remove_lighting
Type
boolean
predeterminado true
Description
Elimina los reflejos y sombras de la textura de color base, produciendo un resultado más limpio que funciona mejor con configuraciones de iluminación personalizadas.
Solo se admite 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. Si se omite, se incluyen todos los formatos admitidos.
Si 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 renderiza adicionalmente una versión con fondo transparente (RGBA) de la vista previa y la devuelve como alpha_thumbnail_url en la respuesta GET. El campo existente thumbnail_url no se modifica.
Devuelve
La propiedad result de la respuesta contiene el id de la tarea de la tarea de Retexturizar recién creada.
Modos de fallo
Name
400 - Bad Request
Description
La solicitud fue inaceptable. Causas comunes:
Parámetro faltante: Debe proporcionarse model_url o input_task_id.
Estilo faltante: Debe proporcionarse uno de text_style_prompt, image_style_url o multiview_image_urls.
Entradas de estilo en conflicto: multiview_image_urls no puede combinarse con text_style_prompt o image_style_url.
Modelo no compatible para multivista: multiview_image_urls requiere un ai_model: "meshy-7" explícito.
Modelo no disponible: ai_model: "meshy-7" y ai_model: "meshy-6-lite" se están implementando de forma progresiva y es posible que aún no estén habilitados para su cuenta.
Tarea de entrada inválida: input_task_id debe hacer referencia a una tarea exitosa de un modelo compatible.
Formato de modelo inválido: model_url apunta a un archivo con una extensión no compatible.
URL inalcanzable: no se pudo descargar model_url, image_style_url o un elemento de multiview_image_urls.
Name
401 - Unauthorized
Description
Falló la autenticación. Por favor verifique su clave de API.
Name
402 - Payment Required
Description
Créditos insuficientes para realizar esta tarea.
Name
429 - Too Many Requests
Description
Ha excedido su límite de tasa.
Request
POST
/openapi/v1/retexture
# Retexture with text promptcurlhttps://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": "red fangs, Samurai outfit that fused with japanese batik style", "enable_original_uv": true, "enable_pbr": true }'# Retexture with image style and 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 permite recuperar una tarea de Retexturizar dado un id de tarea válido.
Consulta El objeto de tarea de Retexturizar para ver qué
propiedades se incluyen en el objeto de tarea de Retexturizar.
Parámetros
Name
id
Type
path
Description
Identificador único de la tarea de Retexturizar que se desea recuperar.
{"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":"red fangs, Samurai outfit that fused with japanese batik style","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}
Este endpoint elimina de forma permanente una tarea de retexturizado, incluidos todos los modelos y datos asociados. Esta acción es irreversible.
Parámetros de ruta
Name
id
Type
path
Description
El ID de la tarea de retexturizado que se va a eliminar.
Estado de la tarea
Una tarea que todavía está en PENDING se elimina y los créditos consumidos
en el momento de su creación se reembolsan.
Una tarea que ya está en IN_PROGRESS no se puede eliminar: la solicitud se
rechaza con 409 Conflict y la tarea sigue ejecutándose. Los créditos de una
tarea que el worker ya ha empezado a procesar no son reembolsables, por lo que
eliminarla en mitad de la ejecución te costaría tanto los créditos como el
resultado. Espera a que alcance el estado SUCCEEDED, FAILED o CANCELED,
y entonces elimínala.
Una tarea en un estado terminal (SUCCEEDED, FAILED o CANCELED) se
elimina sin reembolso.
Devuelve
Devuelve 200 OK en caso de éxito, o 409 Conflict cuando la tarea está en
IN_PROGRESS.
// 200 OK on success, with an empty body.//// 409 Conflict when the task is IN_PROGRESS — the task is left running:{"message":"Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."}
[ {"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":"red fangs, Samurai outfit that fused with japanese batik style","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 Retexturizar es una unidad de trabajo que Meshy utiliza para generar una textura 3D a partir de entradas de texto o de imagen.
El modelo tiene las siguientes propiedades:
Propiedades
Name
id
Type
string
Description
Identificador único de la tarea. Aunque usamos un UUID k-sortable para los id de las tareas
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 Retexturizar. El valor es retexture.
Name
model_urls
Type
object
Description
URL descargable al archivo del modelo 3D texturizado generado por Meshy.
Name
glb
Type
string
Description
URL descargable al archivo GLB.
Name
fbx
Type
string
Description
URL descargable al archivo FBX.
Name
obj
Type
string
Description
URL descargable al archivo OBJ.
Name
usdz
Type
string
Description
URL descargable al archivo USDZ.
Name
mtl
Type
string
Description
URL descargable al archivo MTL, devuelto junto con las exportaciones OBJ cuando hay texturas presentes.
Name
stl
Type
string
Description
URL descargable al archivo STL.
Name
3mf
Type
string
Description
URL descargable al archivo 3MF. Solo está presente cuando se solicitó 3mf mediante 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 a las imágenes de referencia de Multivista que se utilizaron para crear la tarea de texturizado. Solo está presente cuando la tarea se creó con multiview_image_urls.
Name
thumbnail_url
Type
string
Description
URL descargable a la imagen de miniatura del archivo del modelo.
Name
alpha_thumbnail_url
Type
string
Description
URL descargable a una versión con fondo transparente (RGBA) de thumbnail_url. Solo está presente cuando la tarea se creó con alpha_thumbnail: true y la vista previa transparente se renderizó correctamente; en caso contrario, este campo se omite.
Name
progress
Type
integer
Description
Progreso de la tarea. Si la tarea aún no ha comenzado, esta propiedad será 0. Una vez que la tarea haya tenido éxito, se convertirá en 100.
Name
started_at
Type
timestamp
Description
Marca de tiempo de cuándo se inició la tarea, en milisegundos. Si la tarea aún no ha comenzado, 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 cuándo se creó la tarea, en milisegundos.
Name
expires_at
Type
timestamp
Description
Marca de tiempo de cuándo expira el resultado de la tarea, en milisegundos.
Name
finished_at
Type
timestamp
Description
Marca de tiempo de cuándo finalizó la tarea, 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 arreglo de objetos de URL de textura generados a partir de la tarea. Normalmente esto solo contiene un objeto de URL de textura. Cada URL de textura tiene las siguientes propiedades:
Name
base_color
Type
string
Description
URL descargable a la imagen del mapa de color base.
Name
metallic
Type
string
Description
URL descargable a la imagen del mapa metálico.
Si la tarea se crea con enable_pbr: false, esta propiedad se omitirá.
Name
normal
Type
string
Description
URL descargable a la imagen del mapa de normales.
Si la tarea se crea con enable_pbr: false, esta propiedad se omitirá.
Name
roughness
Type
string
Description
URL descargable a la imagen del mapa de rugosidad.
Si la tarea se crea con enable_pbr: false, esta propiedad se omitirá.
Name
emission
Type
string
Description
URL descargable a la imagen del mapa de emisión.
Si la tarea se crea con enable_pbr: false, o ai_model es meshy-6-lite, esta propiedad se omitirá.
Name
preceding_tasks
Type
integer
Description
El número de tareas precedentes.
Esta propiedad solo está presente cuando el estado de la tarea es PENDING.
Name
task_error
Type
object
Description
Detalles del 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. Está presente cuando el estado de la tarea es PENDING, IN_PROGRESS o SUCCEEDED. Devuelve 0 para las tareas FAILED (los créditos se reembolsan 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":"red fangs, Samurai outfit that fused with japanese batik style","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}