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 le texturage — ou chaque fois que vous avez besoin d'une disposition UV propre et sans chevauchement pour des outils en aval (Blender, Substance Painter, Unreal).

La sortie est un "modèle blanc UV" — même forme que l'entrée mais avec de toutes nouvelles coordonnées UV et pas de texture réelle (un matériau de remplacement gris 2×2 est inclus pour garder l'emplacement du matériau glTF valide ; les outils standards traitent cela comme non texturé).

Limitations. L'Auto UV prend actuellement en charge les maillages jusqu'à 40 000 faces — les modèles plus grands sont rejetés avec un 400; exécutez d'abord le Remaillage pour réduire le nombre de polygones. Les maillages en quad et en n-gon sont triangulés lors de la génération UV, donc 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 complétée dont vous souhaitez déplier le GLB (par exemple un résultat Image en 3D, Texte en 3D, ou Remaillage). La tâche source doit avoir un statut de SUCCEEDED et avoir produit un fichier GLB.
Si le maillage source dépasse le plafond de 40 000 faces, la demande sera rejetée avec un 400 et vous devriez exécuter Remaillage d'abord pour réduire le nombre de polygones.

Name
model_url
Type
string
Requis
Description
Fournissez un modèle 3D directement via une URL accessible publiquement ou un Data URI. Seul .glb est pris en charge — l'API lit le binaire glTF et ne parse pas d'autres formats. Pour déplier un modèle dans un autre format (.fbx, .obj, .stl, .gltf), convertissez-le d'abord en .glb via l'API Convertir, puis passez l'ID de tâche résultant comme input_task_id ou son URL de sortie GLB ici.
Pour les Data URIs, utilisez le MIME type application/octet-stream.
Le même plafond de 40 000 faces s'applique que pour input_task_id : les maillages surdimensionnés sont rejetés avec un 400 — exécutez Remaillage d'abord.

Retours

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

Modes d'échec

Name
400 - Bad Request
Description
La demande était inacceptable. Causes courantes :
- Paramètre manquant : Soit input_task_id soit model_url doit être fourni.
- Tâche d'entrée invalide : Le input_task_id doit se référer à une tâche réussie avec un résultat GLB.
- Nombre de faces dépassé : Le maillage source a plus de faces que le plafond de Dépliage UV. Exécutez Remaillage d'abord.
- Format de modèle invalide : Le model_url pointe vers un fichier avec une extension non prise en charge.
- URL inaccessible : Le 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 drapeau Statsig lors du déploiement — contactez le support Meshy si vous avez besoin d'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 Tâche de Dépliage UV.

Requête

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

Voir l'exemple d'objet tâche ci-dessous.

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

Supprimer une tâche de Dépliage UV

Supprimez définitivement une tâche de Dépliage UV. La tâche et ses résultats 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, les plus récentes en premier. Pagination standard via page_num et page_size.

Requête

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 à la progress de la tâche en tant qu'événements envoyés par le serveur. Chaque événement message transporte un objet 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 de sonder 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 Tâche de Dépliage UV

Name
id
Type
string
Description
Identifiant unique pour 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é. Le Dépliage UV retourne 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
Progression 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 la création de la tâche, en millisecondes.
Name
started_at
Type
timestamp
Description
Horodatage du début du traitement, en millisecondes. 0 jusqu'à ce qu'il commence.
Name
finished_at
Type
timestamp
Description
Horodatage de la fin, en millisecondes. 0 jusqu'à ce qu'il soit terminé.
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 échouées. Voir 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. Retourne 0 pour les tâches FAILED (les crédits sont remboursés en cas d'échec). Le Dépliage UV coûte 5 crédits en cas de succès.

Exemple d'Objet Tâche de Dépliage 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
}