API de Dépliage UV

Générez un dépliage UV pour un modèle 3D existant. Exécutez-le avant de texturer le modèle, ou lorsqu'un outil tel que Blender, Substance Painter ou Unreal a besoin d'une disposition UV propre et sans chevauchement.

Le résultat est un modèle blanc UV. Il a la même forme que l'entrée, de nouvelles coordonnées UV, et aucune texture réelle. Il inclut un matériau gris de remplacement 2×2 afin que l'emplacement de matériau glTF reste valide, et les outils standards le traitent comme non texturé.

Le Dépliage UV prend en charge les maillages comportant jusqu'à 40 000 faces. Un modèle plus grand renvoie 400. Pour réduire le nombre de faces, exécutez d'abord Remaillage.

Meshy triangule les maillages constitués de quadrilatères et de n-gones lors de la génération UV, de sorte que le résultat est toujours un maillage triangulaire.

POST/openapi/v1/uv-unwrap

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

Crée une tâche de Dépliage UV.

La tâche s'exécute en arrière-plan. Pour connaître la durée habituelle d'une tâche, consultez Durées de traitement.

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

Paramètres

Name
input_task_id
Type
string
Requis
Description
Requis sauf si vous envoyez model_url. L'ID d'une tâche Meshy API dont vous souhaitez déplier la sortie GLB, par exemple une tâche Image en 3D, Texte en 3D ou Remaillage. La tâche doit avoir le statut SUCCEEDED et avoir produit un fichier GLB.
Le maillage peut comporter au maximum 40 000 faces. Un maillage en comportant davantage renvoie 400. Pour réduire le nombre de faces, exécutez d'abord Remaillage.

Name
model_url
Type
string
Requis
Description
Requis sauf si vous envoyez input_task_id. Le modèle à déplier, sous forme d'URL publique ou de Data URI. Si vous envoyez les deux, Meshy utilise input_task_id.
Le modèle doit être un fichier .glb. Pour déplier un autre format, convertissez-le d'abord en GLB avec l'API de conversion.
Le fichier peut peser au maximum 400 Mo depuis une URL http ou https, ou 100 Mo sous forme de Data URI. Pour un Data URI, utilisez le MIME type application/octet-stream. Un GLB de plus de 100 Mo ne doit pas utiliser la compression Draco.
La même limite de 40 000 faces s'applique que pour input_task_id. Un maillage en comportant davantage renvoie 400 ; exécutez donc d'abord Remaillage.

Retours

Le champ result de la réponse contient l'ID de la nouvelle tâche de Dépliage UV.

Modes d'échec

Name
400 - Bad Request
Description
La requête ne peut pas s'exécuter. Le message d'erreur indique le problème détecté. Par exemple :
- Paramètre manquant : ni input_task_id ni model_url n'ont été envoyés.
- Tâche d'entrée invalide : input_task_id n'est pas une tâche API réussie avec un résultat GLB.
- Nombre de faces dépassé : le maillage comporte plus de faces que ce que le Dépliage UV autorise. Exécutez d'abord Remaillage.
- Format de modèle invalide : le fichier model_url a une extension non prise en charge.
- URL inaccessible : Meshy ne peut pas télécharger le fichier model_url.
- Fichier modèle trop volumineux : le fichier model_url dépasse 400 Mo depuis une URL http ou https, ou 100 Mo en tant que Data URI.
- Trop de faces : le fichier model_url dépasse 100 Mo et comporte plus de 10 000 000 de faces. Réduisez le nombre de faces, puis renvoyez le fichier.
- Fichier modèle illisible : le fichier model_url dépasse 100 Mo et Meshy ne peut pas lire son en-tête. Par exemple, il s'agit d'un GLB compressé avec Draco.
- En-tête du modèle trop complexe : le fichier model_url dépasse 100 Mo et son en-tête comporte trop de maillages, de nœuds ou d'enregistrements à vérifier. Réduisez le nombre d'objets dans le fichier, puis renvoyez-le.
Corrigez la requête, puis renvoyez-la. Consultez Erreurs.
Name
401 - Unauthorized
Description
La clé API est manquante ou invalide. Vérifiez l'en-tête Authorization.
Name
402 - Payment Required
Description
Par exemple :
- Crédits insuffisants : le compte n'a pas assez de crédits pour cette tâche, ou a atteint une limite de crédits. Une tâche de Dépliage UV coûte 5 crédits. Vérifiez votre solde de crédits, puis réessayez.
- Forfait gratuit : la création d'une tâche nécessite un forfait payant. Mettez à niveau votre forfait dans vos paramètres d'abonnement, puis réessayez.
Name
403 - Forbidden
Description
input_task_id est un modèle bas-relief, que ce point de terminaison ne peut pas déplier. Le message est This model type does not support this operation. Envoyez un modèle différent.
Name
404 - Not Found
Description
input_task_id ne correspond à aucune de vos tâches. Vérifiez l'ID de la tâche, puis renvoyez la requête.
Name
429 - Too Many Requests
Description
Vous avez dépassé votre limite de débit. Patientez, puis réessayez. Consultez Limites de débit.

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

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

Renvoie l'état actuel d'une tâche de Dépliage UV à partir de son 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}"

Pour un exemple de réponse, consultez l'exemple d'objet tâche de Dépliage UV.

Retours

L'objet tâche de Dépliage UV.

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

Supprimer une tâche de dépliage UV

Supprime définitivement une tâche de dépliage UV, y compris ses résultats. Vous ne pouvez pas annuler une suppression.

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

Statut de la tâche

Supprimer une tâche PENDING rembourse les crédits utilisés lors de sa création.

Une tâche IN_PROGRESS ne peut pas être supprimée. La requête renvoie 409 Conflict, et la tâche continue de s'exécuter. Meshy ne rembourse pas une tâche qui a démarré, donc la supprimer vous ferait perdre à la fois les crédits et le résultat. Attendez qu'elle atteigne le statut SUCCEEDED, FAILED ou CANCELED, puis supprimez-la.

Supprimer une tâche dans un statut final (SUCCEEDED, FAILED ou CANCELED) ne rembourse pas ses crédits.

GET/openapi/v1/uv-unwrap

Lister les tâches de Dépliage UV

Renvoie une liste paginée de vos tâches de Dépliage UV, de la plus récente à la plus ancienne. Pour parcourir la liste, utilisez 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 les mises à jour d'une tâche de Dépliage UV

Diffuse les mises à jour d'une tâche de Dépliage UV sous forme d'événements envoyés par le serveur (SSE). Chaque événement message transporte un objet tâche de Dépliage UV. Le flux se ferme lorsque la tâche atteint l'état SUCCEEDED, FAILED ou CANCELED.

Pour être informé plus tôt de la fin de la tâche, utilisez ce point de terminaison plutôt que d'interroger régulièrement 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

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

Un objet de tâche de Dépliage UV décrit un dépliage UV d'un modèle 3D. Il contient le statut, la progression et le fichier du modèle lorsque la tâche réussit.

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
L'ID de la tâche. Traitez-le comme une chaîne opaque et ne vous fiez pas à son format.
Name
type
Type
string
Description
Le type de tâche, toujours uv-unwrap.
Name
model_urls
Type
object
Description
URL de téléchargement signées pour le modèle blanc UV. Le Dépliage UV retourne toujours une seule clé glb. Le modèle conserve la géométrie d'entrée, possède de nouvelles coordonnées UV, et utilise un matériau gris par défaut au lieu d'une texture.
Name
thumbnail_url
Type
string
Description
URL de téléchargement signée pour une image d'aperçu PNG du modèle blanc UV.
Name
progress
Type
integer
Description
La part de la tâche réalisée, exprimée en pourcentage de 0 à 100.
Name
status
Type
string
Description
Le statut de la tâche, l'une des valeurs suivantes : PENDING, IN_PROGRESS, SUCCEEDED, FAILED ou CANCELED.
Name
preceding_tasks
Type
integer
Description
Le nombre de tâches qui précèdent celle-ci dans la file d'attente. Présent tant que la tâche est PENDING.
Name
created_at
Type
timestamp
Description
Heure de création de la tâche, en millisecondes Unix.
Name
started_at
Type
timestamp
Description
Heure de démarrage de la tâche, en millisecondes Unix. Elle vaut 0 tant que la tâche n'a pas démarré.
Name
finished_at
Type
timestamp
Description
Heure de fin de la tâche, en millisecondes Unix. Elle vaut 0 tant que la tâche n'est pas terminée.
Name
expires_at
Type
timestamp
Description
Heure d'expiration des URL de téléchargement signées, en millisecondes Unix.
Name
task_error
Type
object
Description
Les détails de l'erreur lorsque la tâche échoue. Voir Erreurs.
Name
consumed_credits
Type
integer
Description
Le nombre de crédits utilisés par la tâche. Une tâche de Dépliage UV réussie coûte 5 crédits. Il vaut 0 pour une tâche FAILED, car Meshy rembourse les crédits lorsqu'une tâche échoue.