API de Retexturizar

La API de Retexturizar 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 empezar a usar esta API.

POST/openapi/v1/retexture

Crear una tarea de Retexturizar

Este endpoint te permite crear una nueva tarea de Retexturizar. Consulta El objeto de tarea de Retexturizar para ver qué propiedades se incluyen con el objeto de tarea de Retexturizar.

Parámetros

Solo uno de input_task_id o model_url es obligatorio. 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: vista previa de Texto a 3D, refinamiento de 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 textura. Formatos compatibles: .glb, .gltf, .obj, .fbx, .stl.
Hay dos formas de proporcionar el modelo:
- URL de acceso público: una URL accesible desde Internet pública.
- Data URI: una Data URI codificada en base64 del modelo. Usa el MIME type application/octet-stream. Ejemplo: data:application/octet-stream;base64,<your base64-encoded model data>.

Solo uno de text_style_prompt o image_style_url es obligatorio. Si se proporcionan ambos, image_style_url tiene prioridad.

Name
text_style_prompt
Type
string
Requerido
Description
Describe con texto el estilo de textura deseado para el objeto. Máximo 600 caracteres.

Name
image_style_url
Type
string
Requerido
Description
Proporciona 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ública
- Data URI: una Data URI codificada en base64 de la imagen. Ejemplo de una Data URI: data:image/jpeg;base64,<your base64-encoded image data>
Es posible que el texturizado con imagen no funcione de forma óptima si hay diferencias sustanciales de geometría entre el asset original y la imagen cargada.

Name
ai_model
Type
string
predeterminado latest
Description
ID del modelo de IA que se usará para retexturizar. Valores disponibles: meshy-5, meshy-6, latest (Meshy 6).
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 (mediante input_task_id, o un model_url que apunta a una salida de Meshy), establece esto en true para reutilizar su distribución UV optimizada.
- Si estás retexturizando un modelo de terceros que has cargado, establece true cuando ya tenga buenas UV que quieras conservar, o déjalo en false para permitir que Meshy despliegue UV nuevas (lo mejor para modelos que carecen de un mapeado UV adecuado).
Name
enable_pbr
Type
boolean
predeterminado false
Description
Genera mapas PBR (metálico, rugosidad, normal) además del color base. También se incluye un mapa de emisión cuando ai_model es meshy-6 o latest.
Name
hd_texture
Type
boolean
predeterminado false
Description
Genera la textura de color base a resolución 4K (4096×4096) para un mayor nivel de detalle.
Solo es compatible cuando ai_model es meshy-6 o latest. Los mapas PBR siempre se generan a 2K.
Name
remove_lighting
Type
boolean
predeterminado true
Description
Elimina brillos y sombras de la textura de color base, produciendo un resultado más limpio que funciona mejor con configuraciones de iluminación personalizadas.
Solo es compatible cuando ai_model es meshy-6 o latest.
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 compatibles.
Valores disponibles: glb, obj, fbx, stl, usdz, 3mf
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 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 thumbnail_url existente no cambia.

Devuelve

La propiedad result de la respuesta contiene el id de la tarea de Retexturizar recién creada.

Modos de fallo

Name
400 - Bad Request
Description
La solicitud no fue aceptable. Causas comunes:
- Parámetro faltante: se debe proporcionar model_url o input_task_id.
- Estilo faltante: se debe proporcionar text_style_prompt o image_style_url.
- Tarea de entrada no válida: el input_task_id debe hacer referencia a una tarea correcta de un modelo compatible.
- Formato de modelo no válido: el model_url apunta a un archivo con una extensión no compatible.
- URL inaccesible: no se pudo descargar el model_url o image_style_url.
Name
401 - Unauthorized
Description
La autenticación falló. Comprueba tu clave de API.
Name
402 - Payment Required
Description
Créditos insuficientes para realizar esta tarea.
Name
429 - Too Many Requests
Description
Has superado tu límite de tasa.

Request

POST

/openapi/v1/retexture

# Retexture with text prompt
curl https://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 PBR
curl https://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
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

GET/openapi/v1/retexture/:id

Recuperar una tarea de Retexturizar

Este endpoint te 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 con el objeto de tarea de Retexturizar.

Parámetros

Name
id
Type
path
Description
Identificador único de la tarea de Retexturizar que se desea recuperar.

Devuelve

La respuesta contiene el objeto de tarea de Retexturizar. Consulta la sección El objeto de tarea de Retexturizar para obtener detalles.

Request

GET

/openapi/v1/retexture/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/openapi/v1/retexture/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "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
}

DELETE/openapi/v1/retexture/:id

Eliminar una tarea de Retexturizar

Este endpoint elimina permanentemente una tarea de retexturización, 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 retexturización que se va a eliminar.

Devuelve

Devuelve 200 OK en caso de éxito.

Request

DELETE

/openapi/v1/retexture/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/retexture/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 200 Ok on success.

GET/openapi/v1/retexture

Listar tareas de Retexturizar

Este endpoint te permite recuperar una lista de tareas de Retexturizar.

Parámetros

Name
page_num
Type
integer
predeterminado 1
Description
Número de página para la paginación.
Name
page_size
Type
integer
predeterminado 10
Description
Límite de tamaño de página. El máximo permitido es de 50 elementos.
Name
sort_by
Type
string
Description
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.

Devuelve

Devuelve una lista paginada de los objetos de tarea de Retexturizar.

Request

GET

/openapi/v1/retexture

curl https://api.meshy.ai/openapi/v1/retexture?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "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
  }
]

GET/openapi/v1/retexture/:id/stream

Transmitir una tarea de Retexturizar

Este endpoint transmite actualizaciones en tiempo real para una tarea de Retexturizar mediante Server-Sent Events (SSE).

Parámetros

Name
id
Type
path
Description
Identificador único de la tarea de Retexturizar que se va a transmitir.

Devuelve

Devuelve un stream de los objetos de tarea de Retexturizar como Server-Sent Events.

Para tareas PENDING o IN_PROGRESS, el stream de respuesta solo incluirá los campos necesarios progress y status.

Request

GET

/openapi/v1/retexture/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v1/retexture/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "retexture",
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1692771650657,
  "started_at": 1692771667037,
  "finished_at": 1692771669037,
  "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=***"
  },
  "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 Retexturizar

El objeto de tarea Retexturizar es una unidad de trabajo que Meshy usa 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 de 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 Retexturizar. El valor es retexture.
Name
model_urls
Type
object
Description
URL descargable del archivo de modelo 3D con textura 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, devuelta junto con las 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 está presente cuando se solicitó 3mf mediante target_formats.
Name
text_style_prompt
Type
string
Description
Este es el prompt de texto que se usó para crear la tarea de texturizado.
Name
image_style_url
Type
string
Description
Esta es la entrada de imagen que se usó para crear la tarea de texturizado.
Name
thumbnail_url
Type
string
Description
URL descargable de la imagen de miniatura del archivo de modelo.
Name
alpha_thumbnail_url
Type
string
Description
URL descargable de 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; 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 se haya completado correctamente, pasará a ser 100.
Name
started_at
Type
timestamp
Description
Marca de tiempo de cuando se inició la tarea, 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, viernes, 1 de septiembre de 2023 12:00:00 PM GMT se representa como 1693569600000. Esto se aplica a todas las marcas de tiempo en Meshy API.
Name
created_at
Type
timestamp
Description
Marca de tiempo de cuando se creó la tarea, en milisegundos.
Name
expires_at
Type
timestamp
Description
Marca de tiempo de cuando expira el resultado de la tarea, en milisegundos.
Name
finished_at
Type
timestamp
Description
Marca de tiempo de cuando 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 array de objetos de URL de textura que se generan 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 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 se omitirá.
- 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 se omitirá.
- 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 se omitirá.
- 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 se omitirá.
Name
preceding_tasks
Type
integer
Description
El recuento 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 ver 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. Devuelve 0 para 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
}