API de Despliegue UV

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

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

Limitaciones. Auto UV actualmente admite mallas de hasta 40,000 caras; los modelos más grandes se rechazan con un 400; ejecuta Remallado primero para reducir el recuento de polígonos. Las mallas de quads y n-gons 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 cuya salida GLB deseas aplicar Despliegue 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 máximo de recuento de caras 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 mediante una URL de acceso público o Data URI. Solo se admite .glb — la API lee binario glTF y no analiza otros formatos. Para aplicar Despliegue UV a un modelo en otro formato (.fbx, .obj, .stl, .gltf), conviértelo primero a .glb mediante la API de Convertir, luego pasa el ID de la tarea resultante como input_task_id o su URL de salida GLB aquí.

    Para Data URIs, usa el MIME type application/octet-stream.

    Se aplica el mismo límite máximo de 40.000 caras que para input_task_id: las mallas sobredimensionadas se rechazan con un 400 — ejecuta Remallado primero.

Devuelve

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 no válida: El input_task_id debe hacer referencia a una tarea correcta con un resultado GLB.
    • Recuento de caras excedido: La malla de origen tiene más caras que el límite máximo de Despliegue UV. Ejecuta Remallado primero.
    • 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.
  • 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. Despliegue UV cuesta 5 créditos por llamada.

  • Name
    404 - Not Found
    Description

    La función no está habilitada para tu cuenta. Despliegue UV está restringido por una marca de Statsig durante el despliegue — contacta con el 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.

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

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

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

Eliminar una tarea de Despliegue UV

Elimina permanentemente una tarea de Despliegue UV. La tarea y sus resultados dejan de ser accesibles.

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, primero 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 en streaming

Suscríbete al progress de la tarea como eventos enviados por el servidor. Cada evento message incluye un objeto de tarea de Despliegue UV; el stream 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 obtener una menor latencia al completarse.

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 de la tarea.

  • Name
    type
    Type
    string
    Description

    Siempre uv-unwrap.

  • Name
    model_urls
    Type
    object
    Description

    URL de descarga prefirmadas para el modelo blanco UV generado. Despliegue UV siempre devuelve una única entrada glb: la salida conserva la geometría de entrada, incorpora coordenadas UV nuevas y usa un material gris predeterminado en lugar de cualquier textura.

  • Name
    thumbnail_url
    Type
    string
    Description

    URL prefirmada a una vista previa PNG del modelo blanco UV.

  • Name
    progress
    Type
    integer
    Description

    progress 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 por delante de esta. Está presente mientras el estado es PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Marca de tiempo de 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 se inicia.

  • Name
    finished_at
    Type
    timestamp
    Description

    Marca de tiempo de finalización, en milisegundos. 0 hasta que finaliza.

  • Name
    expires_at
    Type
    timestamp
    Description

    Marca de tiempo tras la cual expiran las URL de descarga firmadas, en milisegundos.

  • Name
    task_error
    Type
    object
    Description

    Detalles del error para tareas fallidas. Consulta Errores para ver 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 cuando se completa correctamente.

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
}