API de Despliegue UV

Genera un Despliegue UV para un modelo 3D existente. Ejecútalo antes de texturizar el modelo, o cuando una herramienta como Blender, Substance Painter o Unreal necesite una distribución UV limpia y sin solapamientos.

El resultado es un modelo blanco UV. Tiene la misma forma que la entrada, coordenadas UV nuevas y ninguna textura real. Incluye un material de marcador de posición gris de 2×2 para que la ranura de material de glTF siga siendo válida, y las herramientas estándar lo tratan como no texturizado.

Despliegue UV admite mallas de hasta 40,000 caras. Un modelo más grande devuelve 400. Para reducir el número de caras, ejecuta primero Remallado.

Meshy triangula las mallas con cuadriláteros y n-gonos durante la generación de UV, por lo que el resultado siempre es una malla triangular.

POST/openapi/v1/uv-unwrap

Crear una tarea de Despliegue UV

Crea una tarea de Despliegue UV.

La tarea se ejecuta en segundo plano. Para saber cuánto suele tardar una tarea, consulta Tiempos de procesamiento.

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

Parámetros

Name
input_task_id
Type
string
Requerido
Description
Obligatorio a menos que envíes model_url. El ID de una tarea de Meshy API cuya salida GLB quieres desplegar, por ejemplo una tarea de Imagen a 3D, Texto a 3D o Remallado. La tarea debe tener el estado SUCCEEDED y haber generado un archivo GLB.
La malla puede tener como máximo 40,000 caras. Una malla con más devuelve 400. Para reducir el número de caras, ejecuta primero Remallado.

Name
model_url
Type
string
Requerido
Description
Obligatorio a menos que envíes input_task_id. El modelo a desplegar, como una URL pública o un Data URI. Si envías ambos, Meshy usa input_task_id.
El modelo debe ser un archivo .glb. Para desplegar otro formato, conviértelo a GLB primero con la API de Convertir.
El archivo puede tener como máximo 400 MB desde una URL http o https, o 100 MB como Data URI. Para un Data URI, usa el MIME type application/octet-stream. Un GLB de más de 100 MB no debe usar compresión Draco.
Se aplica el mismo límite de 40,000 caras que para input_task_id. Una malla con más devuelve 400, así que ejecuta primero Remallado.

Devuelve

El campo result de la respuesta contiene el ID de la nueva tarea de Despliegue UV.

Modos de error

Name
400 - Bad Request
Description
La solicitud no se puede ejecutar. El mensaje de error indica qué problema encontró. Por ejemplo:
- Parámetro faltante: No se envió ni input_task_id ni model_url.
- Tarea de entrada inválida: input_task_id no es una tarea de API exitosa con un resultado GLB.
- Límite de caras superado: La malla tiene más caras de las que permite Despliegue UV. Ejecuta primero Remallado.
- Formato de modelo inválido: El archivo de model_url tiene una extensión no admitida.
- URL inaccesible: Meshy no puede descargar el archivo de model_url.
- Archivo de modelo demasiado grande: El archivo de model_url supera los 400 MB desde una URL http o https, o supera los 100 MB como Data URI.
- Demasiadas caras: El archivo de model_url supera los 100 MB y tiene más de 10,000,000 de caras. Reduce el número de caras y vuelve a enviar el archivo.
- Archivo de modelo ilegible: El archivo de model_url supera los 100 MB y Meshy no puede leer su encabezado. Por ejemplo, es un GLB comprimido con Draco.
- Encabezado de modelo demasiado complejo: El archivo de model_url supera los 100 MB y su encabezado tiene demasiadas mallas, nodos o registros para verificar. Reduce el número de objetos en el archivo y vuelve a enviarlo.
Corrige la solicitud y vuelve a enviarla. Consulta Errores.
Name
401 - Unauthorized
Description
Falta la clave de API o no es válida. Verifica el encabezado Authorization.
Name
402 - Payment Required
Description
Por ejemplo:
- Créditos insuficientes: La cuenta no tiene suficientes créditos para esta tarea, o la cuenta alcanzó un límite de créditos. Una tarea de Despliegue UV cuesta 5 créditos. Verifica tu saldo de créditos y vuelve a intentarlo.
- Plan gratuito: Crear una tarea requiere un plan de pago. Mejora tu plan en tu configuración de suscripción y vuelve a intentarlo.
Name
403 - Forbidden
Description
input_task_id es un modelo de bajorrelieve, que este endpoint no puede desplegar. El mensaje es This model type does not support this operation. Envía un modelo diferente.
Name
404 - Not Found
Description
input_task_id no coincide con ninguna de tus tareas. Verifica el ID de la tarea y vuelve a enviar la solicitud.
Name
429 - Too Many Requests
Description
Superaste tu límite de tasa. Espera y vuelve a intentarlo. Consulta Límites de tasa.

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

Obtener una tarea de Despliegue UV

Devuelve el estado actual de una tarea de Despliegue UV según su ID.

Request

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

Para ver un ejemplo de respuesta, consulta el ejemplo de objeto de tarea de Despliegue UV.

Devuelve

El objeto de tarea de Despliegue UV.

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

Eliminar una tarea de Despliegue UV

Elimina permanentemente una tarea de Despliegue UV, incluidos sus resultados. No puedes deshacer una eliminación.

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

Estado de la tarea

Eliminar una tarea PENDING reembolsa los créditos que usó al crearla.

Una tarea IN_PROGRESS no se puede eliminar. La solicitud devuelve 409 Conflict, y la tarea sigue ejecutándose. Meshy no reembolsa una tarea que ya ha comenzado, por lo que eliminarla te costaría tanto los créditos como el resultado. Espera a que alcance el estado SUCCEEDED, FAILED o CANCELED, y luego elimínala.

Eliminar una tarea en un estado final (SUCCEEDED, FAILED o CANCELED) no reembolsa sus créditos.

GET/openapi/v1/uv-unwrap

Listar tareas de Despliegue UV

Devuelve una lista paginada de tus tareas de Despliegue UV, con las más recientes primero. Para recorrer la lista, usa 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

Stream de una tarea de Despliegue UV

Transmite las actualizaciones de una tarea de Despliegue UV como Server-Sent Events (SSE). Cada evento message contiene un objeto de tarea de Despliegue UV. El stream se cierra cuando la tarea alcanza el estado SUCCEEDED, FAILED o CANCELED.

Para saber antes que la tarea ha finalizado, utiliza este endpoint en lugar de consultar repetidamente GET /openapi/v1/uv-unwrap/:id.

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

Un objeto de tarea de Despliegue UV describe un despliegue UV de un modelo 3D. Contiene el estado, el progress y el archivo del modelo cuando la tarea tiene éxito.

Example UV Unwrap Task Object

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

Name
id
Type
string
Description
El ID de la tarea. Trátelo como una cadena opaca y no dependa de su formato.
Name
type
Type
string
Description
El tipo de tarea, siempre uv-unwrap.
Name
model_urls
Type
object
Description
URLs de descarga firmadas para el modelo blanco UV. Despliegue UV siempre devuelve una única clave glb. El modelo conserva la geometría de entrada, tiene coordenadas UV nuevas y usa un material gris predeterminado en lugar de una textura.
Name
thumbnail_url
Type
string
Description
URL de descarga firmada para una imagen de vista previa PNG del modelo blanco UV.
Name
progress
Type
integer
Description
Cuánto se ha completado la tarea, como un porcentaje de 0 a 100.
Name
status
Type
string
Description
El estado de la tarea, uno de PENDING, IN_PROGRESS, SUCCEEDED, FAILED o CANCELED.
Name
preceding_tasks
Type
integer
Description
La cantidad de tareas por delante de esta en la cola. Está presente mientras la tarea está PENDING.
Name
created_at
Type
timestamp
Description
Hora en que se creó la tarea, en milisegundos Unix.
Name
started_at
Type
timestamp
Description
Hora en que la tarea comenzó, en milisegundos Unix. Es 0 hasta que la tarea comienza.
Name
finished_at
Type
timestamp
Description
Hora en que la tarea finalizó, en milisegundos Unix. Es 0 hasta que la tarea finaliza.
Name
expires_at
Type
timestamp
Description
Hora en que expiran las URLs de descarga firmadas, en milisegundos Unix.
Name
task_error
Type
object
Description
Los detalles del error cuando la tarea falla. Consulte Errores.
Name
consumed_credits
Type
integer
Description
La cantidad de créditos que usó la tarea. Una tarea de Despliegue UV exitosa cuesta 5 créditos. Es 0 para una tarea FAILED, porque Meshy reembolsa los créditos cuando una tarea falla.