L'API de Retexturisation est une fonctionnalité qui vous permet d'intégrer les capacités de retouchage de texture IA de Meshy dans votre propre application. Dans cette section, vous trouverez toutes les informations
dont vous avez besoin pour commencer avec cette API.
Ce point de terminaison vous permet de créer une nouvelle tâche de retexturisation. Reportez-vous à
L'objet Tâche de Retexturisation pour voir quelles
propriétés sont incluses avec l'objet de tâche de retexturisation.
Paramètres
Seulement 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 de la tâche Image en 3D ou Texte en 3D terminée que vous souhaitez retexturiser.
Cette tâche doit être l'une des tâches suivantes : Texte en 3D Aperçu, Texte en 3D Affiner, Image en 3D ou Remaillage. De plus, elle doit avoir un statut de SUCCEEDED.
Name
model_url
Type
string
Requis
Description
Fournir un modèle 3D à Meshy pour la texturer. Formats pris en charge : .glb, .gltf, .obj, .fbx, .stl.
Il y a deux façons de fournir le modèle :
URL publiquement accessible : Une URL accessible depuis l'Internet public.
Data URI : Une URI de données encodées en base64 du modèle. Utilisez le type MIME application/octet-stream. Exemple : data:application/octet-stream;base64,<your base64-encoded model data>.
Exactement une entrée de style est requise : text_style_prompt, image_style_url ou multiview_image_urls. multiview_image_urls ne peut pas être combiné avec l'un des deux autres ; si text_style_prompt et image_style_url sont fournis, image_style_url prend la priorité.
Name
text_style_prompt
Type
string
Requis
Description
Décrivez votre style de texture souhaité de l'objet à l'aide de texte. Maximum 600 caractères.
Name
image_style_url
Type
string
Requis
Description
Fournissez une image 2D pour guider le processus de texturisation. Nous prenons actuellement en charge les formats .jpg, .jpeg et .png.
Il y a deux façons de fournir l'image :
URL publiquement accessible : Une URL accessible depuis l'Internet public.
Data URI : Une URI de données encodées en base64 de l'image. Exemple d'une URI de données : data:image/jpeg;base64,<your base64-encoded image data>.
La texturisation par image peut ne pas fonctionner de manière optimale s'il y a des différences de géométrie importantes entre l'actif original et l'image téléchargée.
Name
multiview_image_urls
Type
string[]
Requis
Description
Fournissez de 1 à 4 images montrant le même objet sous différents angles pour guider la texturisation. La première image est la vue principale (avant) ; l'ordre des vues restantes (gauche, arrière, droite) n'a pas d'importance.
Chaque élément accepte les mêmes formats que image_style_url (une URL publiquement accessible ou une URI de données base64, .jpg/.jpeg/.png).
Nécessite ai_model: "meshy-7" (ou latest).
Name
ai_model
Type
string
défaut latest
Description
ID du modèle IA à utiliser pour la retexturisation. Valeurs disponibles : meshy-5, meshy-6, meshy-7, latest (Meshy 7).
Name
enable_original_uv
Type
boolean
défaut false
Description
Conservez la disposition UV existante du modèle au lieu d'en générer une nouvelle.
Si vous retravaillez un modèle que Meshy a généré (via input_task_id, ou une model_url qui pointe vers une sortie Meshy), réglez-le sur true pour réutiliser sa disposition UV optimisée.
Si vous retexturez un modèle tiers que vous avez téléchargé, réglez true lorsqu'il a déjà de bons UV que vous souhaitez conserver, ou laissez-le false pour que Meshy développe de nouveaux UV (idéal pour les modèles qui manquent de cartographie UV appropriée).
Name
enable_pbr
Type
boolean
défaut false
Description
Générer des cartes PBR (métallique, rugosité, normal) en plus de la couleur de base. Une carte d'émission est également incluse lorsque ai_model est meshy-6, sauf à texture_resolution: 8k. meshy-7 et latest ne produisent pas de carte d'émission.
Name
texture_resolution
Type
string
défaut 2k
Description
Résolution de la texture de couleur de base. Un des 2k (2048×2048), 4k (4096×4096), ou 8k (8192×8192). Les résolutions plus élevées capturent plus de détails de surface.
4k et 8k nécessitent ai_modelmeshy-6, meshy-7 ou latest. À 8k, aucune carte d'émission n'est produite.
Name
hd_texture
Type
boolean
⚠ obsolète
défaut false
Description
Utilisez texture_resolution à la place — équivalent à texture_resolution: "4k". Lorsqu'ils sont tous deux définis, texture_resolution a la priorité.
Name
remove_lighting
Type
boolean
défaut true
Description
Supprime les reflets et les ombres de la texture de couleur de base, produisant un résultat plus propre qui fonctionne mieux dans des configurations d'éclairage personnalisées.
Uniquement pris en charge lorsque ai_model est meshy-6.
Name
target_formats
Type
string[]
Description
Spécifie quels formats de fichiers 3D inclure dans la sortie. Seuls les formats demandés seront générés et retournés, ce qui peut réduire le temps de réalisation de la tâche. Lorsqu'il est omis, tous les formats pris en charge sont inclus.
Lorsqu'il est omis, tous les formats sauf 3mf sont générés. 3mf n'est inclus que lorsqu'il est explicitement spécifié.
Name
alpha_thumbnail
Type
boolean
défaut false
Description
Lorsqu'il est réglé sur true, la tâche rend également une version avec fond transparent (RGBA) de l'aperçu et la renvoie sous forme de alpha_thumbnail_url sur la réponse GET. Le champ thumbnail_url existant est inchangé.
Renvois
La propriété result de la réponse contient l'id de la tâche de retouchage nouvellement créée.
Modes d'Échec
Name
400 - Bad Request
Description
La requête était inacceptable. Causes communes :
Paramètre manquant : Soit model_url soit input_task_id doit être fourni.
Style manquant : L'un de text_style_prompt, image_style_url ou multiview_image_urls doit être fourni.
Entrées de style conflictuelles : multiview_image_urls ne peut pas être combiné avec text_style_prompt ou image_style_url.
Modèle non pris en charge pour la vue multiple : multiview_image_urls nécessite ai_model: "meshy-7" (ou latest).
Modèle non disponible : ai_model: "meshy-7" est déployé progressivement et n'est pas encore activé pour votre compte.
Tâche d'entrée invalide : Le input_task_id doit se référer à une tâche réussie d'un modèle pris en charge.
Format de modèle invalide : model_url pointe vers un fichier avec une extension non prise en charge.
URL inaccessible : model_url, image_style_url ou un élément multiview_image_urls 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.
Name
429 - Too Many Requests
Description
Vous avez dépassé votre limite de débit.
Request
POST
/openapi/v1/retexture
# Retexturisation avec prompt textuelcurlhttps://api.meshy.ai/openapi/v1/retexture \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "model_url": "https://cdn.meshy.ai/model/example_model_2.glb", "text_style_prompt": "crocs rouges, tenue de samouraï fusionnée avec un style batik japonais", "enable_original_uv": true, "enable_pbr": true }'# Retexturisation avec style d'image et PBRcurlhttps://api.meshy.ai/openapi/v1/retexture \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "model_url": "https://cdn.meshy.ai/model/example_model_2.glb", "image_style_url": "https://cdn.meshy.ai/image/example_image.jpg", "ai_model": "latest", "enable_pbr": true, "enable_original_uv": true }'
Ce point de terminaison vous permet de récupérer une tâche de retexturisation étant donné un id de tâche valide.
Reportez-vous à L'objet Tâche de Retexturisation pour voir quelles
propriétés sont incluses avec l'objet de tâche de retexturisation.
Paramètres
Name
id
Type
path
Description
Identifiant unique pour la tâche de retexturisation à récupérer.
Renvois
La réponse contient l'objet tâche de Retexturisation. Consultez la section
L'objet Tâche de Retexturisation pour plus de détails.
{"id":"018a210d-8ba4-705c-b111-1f1776f7f578","type":"retexture","model_urls": {"glb":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***","fbx":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***","obj":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***","usdz":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***","mtl":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***","stl":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***" },"thumbnail_url":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***","text_style_prompt":"crocs rouges, tenue de samouraï fusionnée avec un style batik japonais","texture_image_url":"","progress":100,"started_at":1692771667037,"created_at":1692771650657,"expires_at":1692771679037,"finished_at":1692771669037,"status":"SUCCEEDED","texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***","metallic":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX","normal":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX","roughness":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX","emission":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX" } ],"task_error": {"message":"" },"consumed_credits":10}
Ce point de terminaison supprime définitivement une tâche de retexturisation, y compris tous les modèles et les données associés. Cette action est irréversible.
Ce point de terminaison diffuse des mises à jour en temps réel pour une tâche de retexturisation en utilisant les événements envoyés par le serveur (SSE).
Paramètres
Name
id
Type
path
Description
Identifiant unique pour la tâche de retexturisation à diffuser.
// Exemples d'événements d'erreurevent: errordata: {"status_code": 404,"message": "Tâche non trouvée"}// Les exemples d'événements de message illustrent la progression de la tâche.// Pour les tâches PENDING ou IN_PROGRESS, le flux de réponse n'inclura pas tous les champs.event: messagedata: {"id": "018a210d-8ba4-705c-b111-1f1776f7f578","progress": 0,"status": "PENDING"}event: messagedata: {"id": "018a210d-8ba4-705c-b111-1f1776f7f578","progress": 50,"status": "IN_PROGRESS"}event: messagedata: {"id": "018a210d-8ba4-705c-b111-1f1776f7f578","type": "retexture","progress": 100,"status": "SUCCEEDED","created_at": 1692771650657,"started_at": 1692771667037,"finished_at": 1692771669037,"model_urls": {"glb":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***","fbx":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***","obj":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***","usdz":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***","mtl":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***","stl":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***" },"texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***","metallic":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX","normal":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX","roughness":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX","emission":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX" } ],"preceding_tasks": 0,"task_error": {"message":"" },"consumed_credits": 10}
L'objet Tâche de Retexturisation est une unité de travail que Meshy utilise pour générer une texture 3D à partir d'entrées de texte ou d'image.
Le modèle a les propriétés suivantes :
Propriétés
Name
id
Type
string
Description
Identifiant unique pour la tâche. Bien que nous utilisions un UUID triable k pour les identifiants de tâche en tant que détail de la mise en œuvre, vous ne devez pas faire d'hypothèses sur le format de l'id.
Name
type
Type
string
Description
Type de la tâche de Retexturisation. La valeur est retexture.
Name
model_urls
Type
object
Description
URL téléchargeable vers le fichier modèle 3D texturé généré par Meshy.
Name
glb
Type
string
Description
URL téléchargeable vers le fichier GLB.
Name
fbx
Type
string
Description
URL téléchargeable vers le fichier FBX.
Name
obj
Type
string
Description
URL téléchargeable vers le fichier OBJ.
Name
usdz
Type
string
Description
URL téléchargeable vers le fichier USDZ.
Name
mtl
Type
string
Description
URL téléchargeable vers le fichier MTL, retourné avec les exportations OBJ lorsque des textures sont présentes.
Name
stl
Type
string
Description
URL téléchargeable vers le fichier STL.
Name
3mf
Type
string
Description
URL téléchargeable vers le fichier 3MF. Présent uniquement lorsque 3mf a été demandé via target_formats.
Name
text_style_prompt
Type
string
Description
Ceci est le prompt textuel qui a été utilisé pour créer la tâche de texturisation.
Name
image_style_url
Type
string
Description
Ceci est l'image d'entrée qui a été utilisée pour créer la tâche de texturisation.
Name
multiview_image_urls
Type
string[]
Description
URLs téléchargeables vers les images de référence multi-vues qui ont été utilisées pour créer la tâche de texturisation. Présent uniquement lorsque la tâche a été créée avec multiview_image_urls.
Name
thumbnail_url
Type
string
Description
URL téléchargeable vers l'image miniature du fichier modèle.
Name
alpha_thumbnail_url
Type
string
Description
URL téléchargeable vers une version avec fond transparent (RGBA) de thumbnail_url. Présent uniquement lorsque la tâche a été créée avec alpha_thumbnail: true et que l'aperçu transparent a été rendu avec succès ; sinon ce champ est omis.
Name
progress
Type
integer
Description
Progression de la tâche. Si la tâche n'est pas encore commencée, cette propriété sera 0. Une fois que la tâche a réussi, ceci devient 100.
Name
started_at
Type
timestamp
Description
Horodatage du début de la tâche, en millisecondes. Si la tâche n'est pas encore commencée, cette propriété sera 0.
Un horodatage représente le nombre de millisecondes écoulées depuis le 1er janvier 1970 UTC, suivant
la norme RFC 3339.
Par exemple, le vendredi 1er septembre 2023 à 12:00:00 GMT est représenté par 1693569600000. Cela s'applique
à tous les horodatages de Meshy API.
Name
created_at
Type
timestamp
Description
Horodatage de la création de la tâche, en millisecondes.
Name
expires_at
Type
timestamp
Description
Horodatage de l'expiration du résultat de la tâche, en millisecondes.
Name
finished_at
Type
timestamp
Description
Horodatage de la fin de la tâche, en millisecondes. Si la tâche n'est pas encore terminée, cette propriété sera 0.
Name
status
Type
string
Description
Statut de la tâche. Les valeurs possibles sont l'un de PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Un tableau d'objets URL de texture générés par la tâche. Normalement, cela ne contient qu'un seul objet URL de texture. Chaque URL de texture a les propriétés suivantes :
Name
base_color
Type
string
Description
URL téléchargeable vers l'image de la carte de couleur de base.
Name
metallic
Type
string
Description
URL téléchargeable vers l'image de la carte métallique.
Si la tâche est créée avec enable_pbr: false, cette propriété sera omise.
Name
normal
Type
string
Description
URL téléchargeable vers l'image de la carte normale.
Si la tâche est créée avec enable_pbr: false, cette propriété sera omise.
Name
roughness
Type
string
Description
URL téléchargeable vers l'image de la carte de rugosité.
Si la tâche est créée avec enable_pbr: false, cette propriété sera omise.
Name
emission
Type
string
Description
URL téléchargeable vers l'image de la carte d'émission.
Si la tâche est créée avec enable_pbr: false, ou que ai_model est meshy-5, cette propriété sera omise.
Name
preceding_tasks
Type
integer
Description
Le nombre de tâches précédentes.
Cette propriété est uniquement présente lorsque le statut de la tâche est PENDING.
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
Le nombre de crédits consommés par cette tâche. Présent lorsque le statut de la tâche est PENDING, IN_PROGRESS, ou SUCCEEDED. Renvoie 0 pour les tâches FAILED (les crédits sont remboursés en cas d'échec).
Example Retexture Task Model
{"id":"018a210d-8ba4-705c-b111-1f1776f7f578","type":"retexture","model_urls": {"glb":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***","fbx":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***","usdz":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***" },"text_style_prompt":"crocs rouges, tenue de samouraï fusionnée avec un style batik japonais","image_style_url":"https://assets.meshy.ai/***/image/example_image.jpg?Expires=***","thumbnail_url":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***","progress":100,"started_at":1692771667037,"created_at":1692771650657,"expires_at":1692771679037,"finished_at":1692771669037,"status":"SUCCEEDED","texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***","metallic":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX","normal":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX","roughness":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX","emission":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX" } ],"preceding_tasks":0,"task_error": {"message":"" },"consumed_credits":10}