API de Retexturisation

L’API de Retexturisation est une fonctionnalité qui vous permet d’intégrer les capacités de retexturisation par IA de Meshy dans votre propre application. Dans cette section, vous trouverez toutes les informations dont vous avez besoin pour commencer à utiliser cette API.

POST/openapi/v1/retexture

Créer une tâche de Retexturisation

Ce point de terminaison vous permet de créer une nouvelle tâche de Retexturisation. Consultez L’objet de tâche de Retexturisation pour voir quelles propriétés sont incluses avec l’objet de tâche de Retexturisation.

Paramètres

Un seul des deux paramètres input_task_id ou model_url est requis. Si les deux sont fournis, input_task_id est prioritaire.

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 : aperçu Texte en 3D, affinage Texte en 3D, Image en 3D ou Remaillage. De plus, elle doit avoir un statut SUCCEEDED.

Name
model_url
Type
string
Requis
Description
Fournissez un modèle 3D à Meshy pour qu’il applique une texture. Formats pris en charge : .glb, .gltf, .obj, .fbx, .stl.
Il existe deux façons de fournir le modèle :
- URL accessible publiquement : une URL accessible depuis l’Internet public.
- Data URI : une Data URI du modèle encodée en base64. Utilisez le MIME type application/octet-stream. Exemple : data:application/octet-stream;base64,<your base64-encoded model data>.

Un seul des deux paramètres text_style_prompt ou image_style_url est requis. Si les deux sont fournis, image_style_url est prioritaire.

Name
text_style_prompt
Type
string
Requis
Description
Décrivez le style de texture souhaité pour 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 existe deux façons de fournir l’image :
- URL accessible publiquement : une URL accessible depuis l’Internet public
- Data URI : une Data URI de l’image encodée en base64. Exemple de Data URI : data:image/jpeg;base64,<your base64-encoded image data>
La texturisation à partir d’une image peut ne pas fonctionner de manière optimale s’il existe des différences importantes de géométrie entre l’asset d’origine et l’image téléversée.

Name
ai_model
Type
string
défaut latest
Description
ID du modèle d’IA à utiliser pour la retexturisation. Valeurs disponibles : meshy-5, meshy-6, latest (Meshy 6).
Name
enable_original_uv
Type
boolean
défaut false
Description
Conserve la disposition UV existante du modèle au lieu d’en générer une nouvelle.
- Si vous retexturisez un modèle généré par Meshy (via input_task_id, ou un model_url qui pointe vers une sortie Meshy), définissez ce paramètre sur true pour réutiliser sa disposition UV optimisée.
- Si vous retexturisez un modèle tiers que vous avez téléversé, définissez true lorsqu’il possède déjà de bons UV que vous souhaitez conserver, ou laissez-le sur false pour laisser Meshy déplier de nouveaux UV (idéal pour les modèles qui ne disposent pas d’un mappage UV approprié).
Name
enable_pbr
Type
boolean
défaut false
Description
Génère des cartes PBR (métallique, rugosité, normale) en plus de la couleur de base. Une carte d’émission est également incluse lorsque ai_model est meshy-6 ou latest.
Name
hd_texture
Type
boolean
défaut false
Description
Génère la texture de couleur de base en résolution 4K (4096×4096) pour un niveau de détail plus élevé.
Pris en charge uniquement lorsque ai_model est meshy-6 ou latest. Les cartes PBR sont toujours générées en 2K.
Name
remove_lighting
Type
boolean
défaut true
Description
Supprime les hautes lumières et les ombres de la texture de couleur de base, produisant un résultat plus propre qui fonctionne mieux avec des configurations d’éclairage personnalisées.
Pris en charge uniquement lorsque ai_model est meshy-6 ou latest.
Name
target_formats
Type
string[]
Description
Spécifie les formats de fichier 3D à inclure dans la sortie. Seuls les formats demandés seront générés et renvoyés, ce qui peut réduire le temps d’exécution de la tâche. S’il est omis, tous les formats pris en charge sont inclus.
Valeurs disponibles : glb, obj, fbx, stl, usdz, 3mf
S’il est omis, tous les formats sauf 3mf sont générés. 3mf est inclus uniquement lorsqu’il est explicitement spécifié.
Name
alpha_thumbnail
Type
boolean
défaut false
Description
Lorsqu’il est défini sur true, la tâche rend également une version avec arrière-plan transparent (RGBA) de l’aperçu et la renvoie en tant que alpha_thumbnail_url dans la réponse GET. Le champ thumbnail_url existant reste inchangé.

Retours

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

Modes d’échec

Name
400 - Bad Request
Description
La requête était inacceptable. Causes courantes :
- Paramètre manquant : model_url ou input_task_id doit être fourni.
- Style manquant : text_style_prompt ou image_style_url doit être fourni.
- Tâche d’entrée invalide : input_task_id doit faire référence à une tâche réussie provenant 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 ou image_style_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.
Name
429 - Too Many Requests
Description
Vous avez dépassé votre limite de débit.

Request

POST

/openapi/v1/retexture

# Retexture with text prompt
curl https://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": "red fangs, Samurai outfit that fused with japanese batik style",
    "enable_original_uv": true,
    "enable_pbr": true
  }'

# Retexture with image style and PBR
curl https://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
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

GET/openapi/v1/retexture/:id

Récupérer une tâche de Retexturisation

Ce point de terminaison vous permet de récupérer une tâche de Retexturisation à partir d’un id de tâche valide. Consultez L’objet de 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 de la tâche de Retexturisation à récupérer.

Retours

La réponse contient l’objet de tâche de Retexturisation. Consultez la section L’objet de tâche de Retexturisation pour plus de détails.

Request

GET

/openapi/v1/retexture/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/openapi/v1/retexture/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "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": "red fangs, Samurai outfit that fused with japanese batik style",
  "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
}

DELETE/openapi/v1/retexture/:id

Supprimer une tâche de Retexturisation

Ce point de terminaison supprime définitivement une tâche de retexturisation, y compris tous les modèles et données associés. Cette action est irréversible.

Paramètres de chemin

Name
id
Type
path
Description
L’ID de la tâche de retexturisation à supprimer.

Retours

Renvoie 200 OK en cas de succès.

Request

DELETE

/openapi/v1/retexture/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/retexture/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 200 Ok on success.

GET/openapi/v1/retexture

Répertorier les tâches de Retexturisation

Ce point de terminaison vous permet de récupérer une liste de tâches de Retexturisation.

Paramètres

Name
page_num
Type
integer
défaut 1
Description
Numéro de page pour la pagination.
Name
page_size
Type
integer
défaut 10
Description
Limite de taille de page. Le maximum autorisé est de 50 éléments.
Name
sort_by
Type
string
Description
Champ selon lequel trier.
Valeurs disponibles :
- +created_at: Trier par date de création dans l’ordre croissant.
- -created_at: Trier par date de création dans l’ordre décroissant.

Retours

Retourne une liste paginée des objets de tâche de Retexturisation.

Request

GET

/openapi/v1/retexture

curl https://api.meshy.ai/openapi/v1/retexture?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "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=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "text_style_prompt": "red fangs, Samurai outfit that fused with japanese batik style",
    "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
  }
]

GET/openapi/v1/retexture/:id/stream

Diffuser en flux une tâche de Retexturisation

Ce point de terminaison diffuse des mises à jour en temps réel pour une tâche de Retexturisation à l’aide de Server-Sent Events (SSE).

Paramètres

Name
id
Type
path
Description
Identifiant unique de la tâche de Retexturisation à diffuser en flux.

Retours

Retourne un flux de Les objets de tâche de Retexturisation sous forme de Server-Sent Events.

Pour les tâches PENDING ou IN_PROGRESS, le flux de réponse inclura uniquement les champs nécessaires progress et status.

Request

GET

/openapi/v1/retexture/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v1/retexture/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: {
  "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 de tâche de Retexturisation

L’objet de tâche de Retexturisation est une unité de travail que Meshy utilise pour générer une texture 3D à partir d’entrées textuelles ou d’images. Le modèle possède les propriétés suivantes:

Propriétés

Name
id
Type
string
Description
Identifiant unique de la tâche. Bien que nous utilisions un UUID k-sortable pour les identifiants de tâche comme détail d’implémentation, vous ne devez pas faire d’hypothèses sur le format de l’identifiant.
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 de 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, renvoyé avec les exports 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ésente uniquement lorsque 3mf a été demandé via target_formats.
Name
text_style_prompt
Type
string
Description
Il s’agit du prompt texte qui a été utilisé pour créer la tâche de texturisation.
Name
image_style_url
Type
string
Description
Il s’agit de l’image d’entrée qui a été utilisée pour créer la tâche de texturisation.
Name
thumbnail_url
Type
string
Description
URL téléchargeable vers l’image miniature du fichier de modèle.
Name
alpha_thumbnail_url
Type
string
Description
URL téléchargeable vers une version à arrière-plan transparent (RGBA) de thumbnail_url. Présente 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’a pas encore démarré, cette propriété sera 0. Une fois la tâche réussie, elle deviendra 100.
Name
started_at
Type
timestamp
Description
Horodatage du démarrage de la tâche, en millisecondes. Si la tâche n’a pas encore démarré, cette propriété sera 0.
Un horodatage représente le nombre de millisecondes écoulées depuis le 1er janvier 1970 UTC, conformément à 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 dans 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’une des suivantes : PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Un tableau d’objets d’URL de texture générés à partir de la tâche. Normalement, il ne contient qu’un objet d’URL de texture. Chaque URL de texture possède les propriétés suivantes :
- Name
  base_color
  Type
  string
  Description
  URL téléchargeable vers l’image de texture de couleur de base.
- Name
  metallic
  Type
  string
  Description
  URL téléchargeable vers l’image de texture 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 normal map.
  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 texture 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 texture d’émission.
  Si la tâche est créée avec enable_pbr: false, ou si 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é n’est présente que 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. Consultez 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": "red fangs, Samurai outfit that fused with japanese batik style",
  "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
}