API de Dépliage UV

L’API de Dépliage UV génère automatiquement un dépliage UV de haute qualité pour un modèle 3D existant. Utilisez-la comme étape préalable avant l’application de textures — ou chaque fois que vous avez besoin d’une disposition UV propre et sans chevauchement pour les outils en aval (Blender, Substance Painter, Unreal).

La sortie est un « modèle blanc UV » — la même forme que l’entrée, mais avec des coordonnées UV entièrement nouvelles et sans véritable texture (un matériau de substitution gris 2×2 est inclus pour que l’emplacement de matériau glTF reste valide ; les outils standard le traitent comme non texturé).

Limitations. L’UV automatique prend actuellement en charge les maillages comportant jusqu’à 40 000 faces — les modèles plus grands sont rejetés avec un 400 ; exécutez d’abord Remaillage pour réduire le nombre de polygones. Les maillages en quadrilatères et en n-gones sont triangulés lors de la génération UV, de sorte que la sortie est toujours un maillage triangulaire.

POST/openapi/v1/uv-unwrap

Créer une tâche de Dépliage UV

Ce point de terminaison crée une nouvelle tâche de Dépliage UV.

Paramètres

Exactement l’un des deux, input_task_id ou model_url, est requis. Si les deux sont fournis, input_task_id prend la priorité.

  • Name
    input_task_id
    Type
    string
    Requis
    Description

    L’ID d’une tâche Meshy API terminée dont vous souhaitez effectuer le Dépliage UV de la sortie GLB (par exemple un résultat Image en 3D, Texte en 3D ou Remaillage). La tâche source doit avoir le statut SUCCEEDED et avoir produit un fichier GLB.

    Si le maillage source dépasse le plafond de 40 000 faces, la requête sera rejetée avec un 400 et vous devrez d’abord exécuter Remaillage afin de réduire le nombre de polygones.

  • Name
    model_url
    Type
    string
    Requis
    Description

    Fournissez directement un modèle 3D via une URL accessible publiquement ou une Data URI. Seul .glb est pris en charge — l’API lit le binaire glTF et n’analyse pas les autres formats. Pour effectuer le Dépliage UV d’un modèle dans un autre format (.fbx, .obj, .stl, .gltf), convertissez-le d’abord en .glb via l’API Convertir, puis transmettez ici l’ID de tâche obtenu comme input_task_id ou l’URL de sa sortie GLB.

    Pour les Data URIs, utilisez le MIME type application/octet-stream.

    Le même plafond de 40 000 faces s’applique comme pour input_task_id : les maillages trop volumineux sont rejetés avec un 400 — exécutez d’abord Remaillage.

Retours

La propriété result de la réponse contient l’id de la tâche de Dépliage UV nouvellement créée.

Modes d’échec

  • Name
    400 - Bad Request
    Description

    La requête était inacceptable. Causes courantes :

    • Paramètre manquant : input_task_id ou model_url doit être fourni.
    • Tâche d’entrée invalide : input_task_id doit faire référence à une tâche réussie avec un résultat GLB.
    • Nombre de faces dépassé : Le maillage source comporte plus de faces que le plafond de Dépliage UV. Exécutez d’abord Remaillage.
    • Format de modèle invalide : model_url pointe vers un fichier avec une extension non prise en charge.
    • URL inaccessible : model_url n’a pas pu être téléchargé.
  • Name
    401 - Unauthorized
    Description

    L’authentification a échoué. Veuillez vérifier votre clé API.

  • Name
    402 - Payment Required
    Description

    Crédits insuffisants pour effectuer cette tâche. Le Dépliage UV coûte 5 crédits par appel.

  • Name
    404 - Not Found
    Description

    La fonctionnalité n’est pas activée pour votre compte. Le Dépliage UV est contrôlé par un indicateur Statsig pendant le déploiement — contactez le support Meshy si vous avez besoin d’un accès.

  • Name
    429 - Too Many Requests
    Description

    Vous avez dépassé votre limite de débit.

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

Récupérer une tâche de Dépliage UV

Ce point de terminaison récupère l’état actuel d’une tâche de Dépliage UV par ID.

Renvoie

Renvoie un objet de tâche de Dépliage 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}"

Consultez l’exemple d’objet de tâche ci-dessous.

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

Supprimer une tâche de Dépliage UV

Supprime définitivement une tâche de Dépliage UV. La tâche et ses sorties deviennent inaccessibles.

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

Lister les tâches de Dépliage UV

Renvoie une liste paginée des tâches de Dépliage UV de l’appelant, de la plus récente à la plus ancienne. Pagination standard via page_num et 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

Diffuser une tâche de Dépliage UV

Abonnez-vous au progress de la tâche sous forme de Server-Sent Events. Chaque événement message contient un objet de tâche de Dépliage UV ; le flux se ferme une fois que la tâche atteint SUCCEEDED, FAILED ou CANCELED.

Utilisez ceci au lieu d’interroger GET /openapi/v1/uv-unwrap/:id pour une latence plus faible à l’achèvement.

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

L’objet de tâche de Dépliage UV

  • Name
    id
    Type
    string
    Description

    Identifiant unique de la tâche.

  • Name
    type
    Type
    string
    Description

    Toujours uv-unwrap.

  • Name
    model_urls
    Type
    object
    Description

    URL de téléchargement présignées pour le modèle blanc UV généré. Dépliage UV renvoie toujours une seule entrée glb — la sortie préserve la géométrie d’entrée, remplace par de nouvelles coordonnées UV et utilise un matériau gris par défaut à la place de toute texture.

  • Name
    thumbnail_url
    Type
    string
    Description

    URL présignée vers un aperçu PNG du modèle blanc UV.

  • Name
    progress
    Type
    integer
    Description

    progress de la tâche, de 0 à 100.

  • Name
    status
    Type
    string
    Description

    L’un de PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Nombre de tâches en file d’attente avant celle-ci. Présent lorsque le statut est PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Horodatage de création de la tâche, en millisecondes.

  • Name
    started_at
    Type
    timestamp
    Description

    Horodatage du début du traitement, en millisecondes. 0 jusqu’au démarrage.

  • Name
    finished_at
    Type
    timestamp
    Description

    Horodatage de fin, en millisecondes. 0 jusqu’à la fin.

  • Name
    expires_at
    Type
    timestamp
    Description

    Horodatage après lequel les URL de téléchargement signées expirent, en millisecondes.

  • Name
    task_error
    Type
    object
    Description

    Détails de l’erreur pour les tâches ayant échoué. Consultez Erreurs pour la référence complète de l’objet task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    Crédits consommés par cette tâche. Renvoie 0 pour les tâches FAILED (les crédits sont remboursés en cas d’échec). Dépliage UV facture 5 crédits en cas de réussite.

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
}