API de Despliegue UV

La API de Despliegue UV genera automáticamente un despliegue UV de alta calidad para un modelo 3D existente. Úselo como el paso previo antes de texturizar, o en cualquier momento que necesite una distribución UV limpia y sin superposiciones para herramientas posteriores (Blender, Substance Painter, Unreal).

La salida es un "modelo blanco UV" — misma forma que la entrada pero con coordenadas UV completamente nuevas y sin textura real (se incluye un material de marcador de posición gris de 2×2 para mantener válida la ranura de material glTF; las herramientas estándar tratan esto como no texturizado).

Limitaciones. Auto UV actualmente admite mallas de hasta 40,000 caras — los modelos más grandes son rechazados con un 400; ejecute Remallado primero para reducir el recuento de polígonos. Las mallas de cuadriláteros y n-gon se triangulan durante la generación UV, por lo que la salida siempre es una malla de triángulos.

POST/openapi/v1/uv-unwrap

Crear una Tarea de Despliegue UV

Este endpoint crea una nueva tarea de Despliegue UV.

Parámetros

Se requiere exactamente 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 una tarea completada de Meshy API cuyo resultado GLB deseas desplegar en UV (por ejemplo, un resultado de Imagen a 3D, Texto a 3D o Remallado). La tarea de origen debe tener un estado de SUCCEEDED y haber producido un archivo GLB.
Si la malla de origen supera el límite de 40,000 caras, la solicitud será rechazada con un 400 y deberías ejecutar Remallado primero para reducir el recuento de polígonos.

Name
model_url
Type
string
Requerido
Description
Proporciona un modelo 3D directamente a través de una URL accesible públicamente o un Data URI. Solo se admite .glb — la API lee binarios glTF y no analiza otros formatos. Para desplegar en UV un modelo en otro formato (.fbx, .obj, .stl, .gltf), conviértelo a .glb primero a través de la Convert API, luego pasa el ID de tarea resultante como input_task_id o su URL de salida GLB aquí.
Para Data URIs, usa el MIME type application/octet-stream.
El mismo límite de 40,000 caras se aplica como para input_task_id: las mallas de gran tamaño son rechazadas con un 400 — ejecuta Remallado primero.

Retornos

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

Modos de Fallo

Name
400 - Bad Request
Description
La solicitud no fue aceptable. Causas comunes:
- Parámetro faltante: Se debe proporcionar input_task_id o model_url.
- Tarea de entrada inválida: El input_task_id debe referirse a una tarea exitosa con un resultado GLB.
- Recuento de caras excedido: La malla de origen tiene más caras que el límite de Despliegue UV. Ejecuta Remallado primero.
- Formato de modelo inválido: El model_url apunta a un archivo con una extensión no soportada.
- URL inaccesible: No se pudo descargar el model_url.
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. El Despliegue UV cuesta 5 créditos por llamada.
Name
404 - Not Found
Description
La función no está habilitada para tu cuenta. El Despliegue UV está limitado por una bandera de Statsig durante el despliegue — contacta al soporte de Meshy si necesitas acceso.
Name
429 - Too Many Requests
Description
Has excedido tu límite de tasa.

Request

POST

/openapi/v1/uv-unwrap

# Chain from an existing Meshy task
curl https://api.meshy.ai/openapi/v1/uv-unwrap \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
      "input_task_id": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
    }'

# Or from a publicly accessible model URL
curl https://api.meshy.ai/openapi/v1/uv-unwrap \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
      "model_url": "https://example.com/path/to/model.glb"
    }'

Response

{
  "result": "019361c6-9b34-7b23-bef2-d0107c4d92e2"
}

GET/openapi/v1/uv-unwrap/:id

Recuperar una Tarea de Despliegue UV

Este endpoint recupera el estado actual de una tarea de Despliegue UV por ID.

Devuelve

Devuelve un objeto de Tarea de Despliegue UV.

Solicitud

GET

/openapi/v1/uv-unwrap/:id

curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Vea el ejemplo de objeto de tarea a continuación.

DELETE/openapi/v1/uv-unwrap/:id

Eliminar una Tarea de Despliegue UV

Eliminar permanentemente una tarea de Despliegue UV. La tarea y sus resultados se vuelven inaccesibles.

Request

DELETE

/openapi/v1/uv-unwrap/:id

curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-X DELETE \
-H "Authorization: Bearer ${YOUR_API_KEY}"

GET/openapi/v1/uv-unwrap

Listar Tareas de Despliegue UV

Devuelve una lista paginada de las tareas de Despliegue UV del solicitante, comenzando por las más recientes. Paginación estándar mediante page_num y page_size.

Request

GET

/openapi/v1/uv-unwrap

curl "https://api.meshy.ai/openapi/v1/uv-unwrap?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

GET/openapi/v1/uv-unwrap/:id/stream

Transmitir una Tarea de Despliegue UV

Suscríbete al progress de la tarea como Eventos Enviados por el Servidor. Cada evento message lleva un objeto de Tarea de Despliegue UV; el flujo se cierra una vez que la tarea alcanza SUCCEEDED, FAILED, o CANCELED.

Usa esto en lugar de sondear GET /openapi/v1/uv-unwrap/:id para una menor latencia en la finalización.

Request

GET

/openapi/v1/uv-unwrap/:id/stream

curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-N

El Objeto de Tarea de Despliegue UV

Name
id
Type
string
Description
Identificador único para la tarea.
Name
type
Type
string
Description
Siempre uv-unwrap.
Name
model_urls
Type
object
Description
URLs de descarga pre-firmadas para el modelo blanco UV generado. Despliegue UV siempre devuelve una única entrada glb — la salida preserva la geometría de entrada, intercambia nuevas coordenadas UV y utiliza un material gris por defecto en lugar de cualquier textura.
Name
thumbnail_url
Type
string
Description
URL pre-firmada para una vista previa PNG del modelo blanco UV.
Name
progress
Type
integer
Description
Progreso de la tarea, de 0 a 100.
Name
status
Type
string
Description
Uno de PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
preceding_tasks
Type
integer
Description
Número de tareas en cola antes de esta. Presente mientras el estado es PENDING.
Name
created_at
Type
timestamp
Description
Marca de tiempo de la creación de la tarea, en milisegundos.
Name
started_at
Type
timestamp
Description
Marca de tiempo de cuando comenzó el procesamiento, en milisegundos. 0 hasta que comience.
Name
finished_at
Type
timestamp
Description
Marca de tiempo de finalización, en milisegundos. 0 hasta que termine.
Name
expires_at
Type
timestamp
Description
Marca de tiempo después de la cual expiran las URLs de descarga firmadas, en milisegundos.
Name
task_error
Type
object
Description
Detalles del error para tareas fallidas. Consulte Errores para la referencia completa del objeto task_error.
Name
consumed_credits
Type
integer
Description
Créditos consumidos por esta tarea. Devuelve 0 para tareas FAILED (los créditos se reembolsan en caso de fallo). Despliegue UV cobra 5 créditos en caso de éxito.

Ejemplo de Objeto de Tarea de Despliegue UV

{
  "id": "019361c6-9b34-7b23-bef2-d0107c4d92e2",
  "type": "uv-unwrap",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019361c6-9b34-7b23-bef2-d0107c4d92e2/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019361c6-9b34-7b23-bef2-d0107c4d92e2/output/preview.png?Expires=***",
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1716579120000,
  "started_at": 1716579122000,
  "finished_at": 1716579180000,
  "expires_at": 1716665580000,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 5
}