API Texte en 3D

Générez des modèles 3D à partir d'invites textuelles dans votre propre application.

Texte en 3D fonctionne en deux étapes. Tout d'abord, créez une tâche preview (mode: "preview") pour générer un maillage 3D sans texture, afin de pouvoir vérifier la forme. Ensuite, envoyez l'ID de la tâche preview réussie à une tâche refine (mode: "refine") pour texturer le maillage. Les deux étapes utilisent le même point de terminaison.

POST/openapi/v2/text-to-3d

Créer une tâche de prévisualisation Texte en 3D

Crée une tâche de prévisualisation Texte en 3D, qui génère un maillage 3D non texturé (géométrie uniquement) à partir d'un prompt textuel. Il s'agit de la première étape du flux de travail en deux étapes. Une fois la prévisualisation réussie, envoyez son ID de tâche dans une tâche refine pour texturer le maillage. Voir Créer une tâche refine Texte en 3D. Pour le schéma de réponse complet, voir L'objet de tâche Texte en 3D.

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

Request

POST

/openapi/v2/text-to-3d

# Simple preview with required params only
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a monster mask"
}'

# Preview with Ultra 4K geometry, remesh, and A-pose
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a futuristic robot warrior",
  "ai_model": "meshy-7.1",
  "geometry_resolution": "4k",
  "should_remesh": true,
  "target_polycount": 100000,
  "pose_mode": "a-pose",
  "target_formats": ["glb"]
}'

Response

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

Paramètres

Name
mode
Type
string
Requis
Description
L'étape du flux de travail en deux étapes. Envoyez preview pour créer une tâche de prévisualisation.
Name
prompt
Type
string
Requis
Description
Texte décrivant l'objet à générer, jusqu'à 800 caractères. Un texte plus long renvoie 400.
Name
model_type
Type
string
défaut standard
Description
Le type de maillage 3D à générer.
Valeurs disponibles :
- standard : un maillage 3D haute précision
- smart-topology : un maillage Smart Topology. Choisissez le modèle avec ai_model (meshy-t2 ou meshy-t2.5).
Avec smart-topology, Meshy ignore should_remesh et decimation_mode, et n'accepte que topology: triangle.
Name
ai_model
Type
string
défaut latest
Description
Le modèle d'IA qui génère le modèle 3D. Les valeurs disponibles dépendent de model_type.
Modèles standard (model_type: standard) :
- meshy-6-lite
- meshy-6
- meshy-7.1
- latest : Meshy 7.1
- meshy-7 (obsolète) : envoyez meshy-7.1 à la place
Modèles Smart Topology (model_type: smart-topology) :
- meshy-t2 : topology plus propre, parties nativement séparées, sortie en triangles, et un nombre de faces que vous définissez avec target_polycount
- meshy-t2.5 (par défaut) : détail plus précis pour les assets de jeu, sortie en triangles, et un nombre de faces que vous définissez avec target_polycount
Name
geometry_resolution
Type
string
défaut standard
Description
La passe de génération de la géométrie. S'applique uniquement aux tâches de prévisualisation. Un refine avec ce paramètre renvoie 400.
Valeurs disponibles :
- standard
- 2k : exécute la passe Ultra à 2048³
- 4k : exécute la passe Ultra à 4096³, pour un détail de surface plus fin
2k nécessite meshy-7.1, latest, ou le modèle obsolète meshy-7. 4k nécessite meshy-7.1 ou latest. Les autres modèles renvoient 400.
Name
ultra_mode
Type
boolean
⚠ obsolète
défaut false
Description
Envoyez geometry_resolution à la place. ultra_mode: true équivaut à geometry_resolution: "2k".
Name
should_remesh
Type
boolean
défaut true (meshy-6-lite), false (other models)
Description
Indique s'il faut remailler le modèle après la génération. Pour le modèle 3D de la plus haute qualité, envoyez false.

S'applique uniquement quand should_remesh = true

Name
topology
Type
string
défaut triangle
Description
Le type de faces du modèle remaillé.
Valeurs disponibles :
- quad : un maillage à dominante de quadrilatères
- triangle : un maillage triangulaire décimé
La sortie Smart Topology est uniquement en triangles. Envoyer quad avec ai_model meshy-t2 ou meshy-t2.5 renvoie 400.
Name
decimation_mode
Type
integer
Description
Nombre de faces adaptatif, par niveau. Lorsque vous le définissez, Meshy ignore target_polycount.
Valeurs disponibles :
- 1 : ultra
- 2 : élevé
- 3 : moyen
- 4 : faible

Name
target_polycount
Type
integer
Description
Le nombre de faces visé. Le résultat peut différer de la cible, selon la géométrie. Il s'applique dans deux cas distincts :
- Remaillage : avec should_remesh: true sur un modèle standard. Meshy remaille (décime) le maillage pour atteindre environ ce nombre. Si vous définissez decimation_mode, Meshy l'utilise et ignore target_polycount.
- Smart Topology : avec model_type: smart-topology et ai_model meshy-t2 ou meshy-t2.5. Meshy génère le modèle directement avec ce nombre de faces. Aucun remaillage ne s'exécute, et vous n'avez pas besoin de should_remesh.
Le tableau suivant indique la plage et la valeur par défaut pour chaque cas :
Cas Plage Par défaut
Remaillage 100 à 300000 30000
meshy-t2 100 à 15000 4000
meshy-t2.5 100 à 30000 15000
Une valeur en dehors de la plage renvoie 400.

Cas	Plage	Par défaut
Remaillage	`100` à `300000`	`30000`
`meshy-t2`	`100` à `15000`	`4000`
`meshy-t2.5`	`100` à `30000`	`15000`

Name
symmetry_mode
Type
string
⚠ obsolète
défaut auto
Description
Ne l'incluez pas. Ce paramètre n'affecte pas le résultat.
Valeurs disponibles :
- off : désactive la symétrie
- auto : applique la symétrie en fonction de la géométrie d'entrée
- on : impose la symétrie pendant la génération
Name
pose_mode
Type
string
défaut ""
Description
La pose du modèle généré.
Valeurs disponibles :
- a-pose : une pose en A
- t-pose : une pose en T
- "" (chaîne vide) : aucune pose spécifique
Name
is_a_t_pose
Type
boolean
⚠ obsolète
défaut false
Description
Envoyez pose_mode à la place. Indique s'il faut générer le modèle en pose A ou en pose T.
Name
art_style
Type
string
⚠ obsolète
défaut realistic
Description
Ne l'incluez pas. Meshy l'ignore.
Name
moderation
Type
boolean
défaut false
Description
Indique s'il faut filtrer prompt pour détecter tout contenu nuisible avant la génération. Si Meshy détecte un contenu nuisible, la requête renvoie 400 et Meshy ne crée pas de tâche.
Name
target_formats
Type
string[]
Description
Les formats de fichiers à générer. Meshy génère et renvoie uniquement ces formats, ce qui peut raccourcir la tâche. Si vous l'omettez, Meshy génère tous les formats sauf 3mf, qu'il ne génère que si vous le demandez.
Valeurs disponibles :
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
alpha_thumbnail
Type
boolean
défaut false
Description
Indique s'il faut également rendre une prévisualisation avec un arrière-plan transparent (RGBA), renvoyée dans alpha_thumbnail_url lorsque vous récupérez la tâche. thumbnail_url ne change pas.
Name
auto_size
Type
boolean
défaut false
Description
Indique s'il faut estimer la hauteur réelle de l'objet grâce à la vision par IA et redimensionner le modèle en conséquence. Meshy place l'origine en bas, sauf si vous définissez origin_at.

S'applique uniquement quand auto_size = true

Name
origin_at
Type
string
défaut bottom
Description
Où placer l'origine du modèle, bottom ou center.

Retour

Le champ result de la réponse contient l'ID de la nouvelle tâche Texte en 3D.

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 : un paramètre requis, comme prompt ou mode, est manquant.
- Prompt trop long : prompt dépasse la limite de caractères.
- Modèle non pris en charge pour Ultra : geometry_resolution vaut 2k ou 4k, avec un ai_model qui ne peut pas l'exécuter.
Corrigez la requête, puis renvoyez-la. Voir 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 ne dispose pas de crédits suffisants pour cette tâche, ou le compte a atteint une limite de crédits. Vérifiez votre solde de crédits, puis réessayez.
- Plan gratuit : la création d'une tâche nécessite un plan payant. Mettez à niveau votre plan dans vos paramètres d'abonnement, puis réessayez.
Name
429 - Too Many Requests
Description
Vous avez dépassé votre limite de débit. Attendez, puis réessayez. Voir Limites de débit.

POST/openapi/v2/text-to-3d

Créer une tâche refine Texte en 3D

Crée une tâche refine Texte en 3D, qui texture le maillage d'une tâche preview terminée. Envoyez l'ID d'une tâche preview réussie en tant que preview_task_id. Voir Créer une tâche preview Texte en 3D. Il s'agit de la seconde étape du flux de travail en deux étapes.

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

Request

POST

/openapi/v2/text-to-3d

# Basic refine task
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "enable_pbr": true
}'

# Refine with auto-size and GLB format
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "target_formats": ["glb"],
  "auto_size": true
}'

Response

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

Paramètres

Name
mode
Type
string
Requis
Description
L'étape du flux de travail en deux étapes. Envoyez refine pour créer une tâche refine.
Name
preview_task_id
Type
string
Requis
Description
L'ID de la tâche preview à texturer. La tâche preview doit avoir le statut SUCCEEDED.
Name
enable_pbr
Type
boolean
défaut false
Description
Indique s'il faut aussi générer des cartes PBR (métallique, rugosité et normale) en plus de la couleur de base.
Avec ai_model meshy-6, Meshy génère aussi une carte d'émission, sauf à texture_resolution: 8k. meshy-6-lite, meshy-7, meshy-7.1 et latest ne génèrent pas de carte d'émission. Il en va de même pour le refine d'une preview meshy-t2 ou meshy-t2.5 qui ne définit pas ai_model.
Name
texture_resolution
Type
string
défaut 2k
Description
La résolution de la texture de couleur de base. S'applique uniquement aux tâches refine. Une preview avec ce paramètre renvoie 400.
Valeurs disponibles :
- 2k : 2048×2048
- 4k : 4096×4096
- 8k : 8192×8192
Des résolutions plus élevées capturent davantage de détails de surface. 4k et 8k nécessitent ai_model meshy-6, meshy-7.1 ou latest. À 8k, Meshy ne génère pas de carte d'émission.
Name
hd_texture
Type
boolean
⚠ obsolète
défaut false
Description
Envoyez plutôt texture_resolution. hd_texture: true équivaut à texture_resolution: "4k". Si vous envoyez les deux, Meshy utilise texture_resolution.
Name
texture_prompt
Type
string
Description
Texte qui guide la texturation, jusqu'à 800 caractères. Un texte plus long renvoie 400. Envoyez texture_prompt ou texture_image_url, pas les deux. Si vous envoyez les deux, Meshy utilise texture_prompt.
Name
texture_image_url
Type
string
Description
Une image 2D qui guide la texturation, sous forme d'URL publique ou de Data URI encodée en base64, comme data:image/jpeg;base64,<vos données d'image encodées en base64>.
L'image doit être un fichier .jpg, .jpeg, .png ou .webp d'au plus 20 Mo.
La texturation à partir d'une image peut mal fonctionner lorsque la forme présente dans l'image diffère beaucoup du modèle.
Name
ai_model
Type
string
défaut inherited from the preview task
Description
Le modèle d'IA qui texture le maillage.
Valeurs disponibles :
- meshy-6-lite
- meshy-6
- meshy-7.1
- latest : Meshy 7.1
- meshy-7 (obsolète) : envoyez plutôt meshy-7.1
Omettez-le pour utiliser le modèle de la tâche preview, afin que la preview et son refine s'exécutent de bout en bout sur le même modèle. Envoyez une valeur pour le remplacer. Un latest explicite se résout de la même façon que sur la tâche preview, de sorte qu'une preview latest et son refine latest utilisent toujours le même modèle de texture.
Name
moderation
Type
boolean
défaut false
Description
Indique s'il faut vérifier texture_prompt et texture_image_url à la recherche de contenu préjudiciable avant la génération. Si Meshy détecte du contenu préjudiciable, la requête renvoie 400 et Meshy ne crée pas de tâche.
Name
remove_lighting
Type
boolean
défaut true
Description
Indique s'il faut supprimer les reflets et les ombres de la texture de couleur de base. Le résultat plus propre fonctionne mieux sous un éclairage personnalisé.
N'a d'effet que lorsque ai_model vaut meshy-6. meshy-7.1 et latest l'acceptent et l'ignorent, tout comme le refine d'une preview meshy-t2 ou meshy-t2.5 qui ne définit pas ai_model. L'envoyer avec meshy-6-lite renvoie 400.
Name
target_formats
Type
string[]
Description
Les formats de fichier à générer. Meshy génère et renvoie uniquement ces formats, ce qui peut raccourcir la tâche. Si vous l'omettez, Meshy génère tous les formats sauf 3mf, qu'il ne génère que sur demande.
Valeurs disponibles :
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
alpha_thumbnail
Type
boolean
défaut false
Description
Indique s'il faut aussi rendre un aperçu avec un fond transparent (RGBA), renvoyé dans alpha_thumbnail_url lors de la récupération de la tâche. thumbnail_url ne change pas.
Name
auto_size
Type
boolean
défaut false
Description
Indique s'il faut estimer la hauteur réelle de l'objet à l'aide de la vision par IA et redimensionner le modèle en conséquence. Meshy place l'origine en bas, sauf si vous définissez origin_at.

S'applique uniquement quand auto_size = true

Name
origin_at
Type
string
défaut bottom
Description
Où placer l'origine du modèle, bottom ou center.

Résultats retournés

Le champ result de la réponse contient l'ID de la nouvelle tâche Texte en 3D.

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 rencontré. Par exemple :
- ID de tâche invalide : preview_task_id est invalide, ou ne correspond à aucune de vos tâches preview.
- Tâche non prête : La tâche preview n'a pas encore réussi.
- Incompatibilité de modèle : Le modèle d'IA de la tâche preview ne fonctionne pas avec le modèle refine demandé.
- Modèle non pris en charge pour remove_lighting : remove_lighting a été envoyé avec ai_model: "meshy-6-lite".
Corrigez la requête, puis envoyez-la à nouveau. Voir 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 ne dispose pas de suffisamment de crédits pour cette tâche, ou le compte a atteint une limite de 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
429 - Too Many Requests
Description
Vous avez dépassé votre limite de débit. Attendez, puis réessayez. Voir Limites de débit.

GET/openapi/v2/text-to-3d/:id

Récupérer une tâche Texte en 3D

Retourne une tâche Texte en 3D à partir de son ID. Cela fonctionne aussi bien pour les tâches de prévisualisation que pour les tâches refine.

Request

GET

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "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=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?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=***",
  "prompt": "a monster mask",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 20
}

Paramètres

Name
id
Type
path
Description
L'ID de la tâche issu de la réponse de création.

Retour

L'objet tâche Texte en 3D.

Exemples

Le tableau suivant présente un modèle d'exemple pour chaque mode.

Mode	Modèle d'exemple
Prévisualisation
Refine

DELETE/openapi/v2/text-to-3d/:id

Supprimer une tâche Texte en 3D

Supprime définitivement une tâche Texte en 3D, y compris ses modèles et ses données. Vous ne pouvez pas annuler une suppression.

Request

DELETE

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS. The task keeps running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

Paramètres de chemin

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

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 coûterait à 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.

Retours

200 OK lorsque la tâche est supprimée, ou 409 Conflict lorsque la tâche est IN_PROGRESS.

GET/openapi/v2/text-to-3d

Lister les tâches Texte en 3D

Renvoie une liste de vos tâches Texte en 3D.

Request

GET

/openapi/v2/text-to-3d

curl https://api.meshy.ai/openapi/v2/text-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "text-to-3d-preview",
    "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=***",
      "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?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=***",
    "prompt": "a monster mask",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "finished_at": 1692771669037,
    "status": "SUCCEEDED",
    "texture_urls": [
      {
        "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
      }
    ],
    "preceding_tasks": 0,
    "task_error": {

      "message": ""

    },

    "consumed_credits": 20
  }
]

Paramètres

Name
page_num
Type
integer
défaut 1
Description
Le numéro de page à renvoyer.
Name
page_size
Type
integer
défaut 10
Description
Le nombre de tâches par page, jusqu'à 100.
Name
sort_by
Type
string
Description
L'ordre de tri.
Valeurs disponibles :
- +created_at : du plus ancien au plus récent
- -created_at : du plus récent au plus ancien

Retours

Une liste paginée d'objets de tâche Texte en 3D.

GET/openapi/v2/text-to-3d/:id/stream

Diffuser un flux de tâche Texte en 3D

Diffuse les mises à jour d'une tâche Texte en 3D sous forme d'événements envoyés par le serveur (SSE).

Request

GET

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v2/text-to-3d/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.
// These examples are shortened. Each event holds the full task object.
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": "text-to-3d-preview",
"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=***"
},
"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": 20
}

Paramètres

Name
id
Type
path
Description
L'ID de la tâche provenant de la réponse de création.

Retours

Un flux d'objets de tâche Texte en 3D sous forme d'événements envoyés par le serveur.

Chaque événement contient l'objet de tâche complet, dans la même forme que celle retournée par le point de terminaison Get. Tant que la tâche est PENDING ou IN_PROGRESS, ses champs de résultat n'ont pas encore de valeurs.

L'objet de tâche Texte en 3D

Un objet de tâche Texte en 3D décrit une tâche qui génère un modèle 3D à partir d'un prompt texte. Il contient le statut, la progression, et les fichiers du modèle lorsque la tâche réussit. Texte en 3D comporte deux étapes, preview et refine. Une tâche preview génère un modèle 3D composé uniquement d'un maillage, et une tâche refine génère un modèle 3D texturé à partir du résultat de la preview.

Propriétés

Example Text to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "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=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?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=***"
  },
  "prompt": "a monster mask",
  "texture_prompt": "green slimy skin with scales and warts",
  "texture_image_url": "",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "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": 20
}

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, text-to-3d-preview pour une tâche preview ou text-to-3d-refine pour une tâche refine.
Name
model_urls
Type
object
Description
Les URL de téléchargement pour le modèle 3D généré, une par format de fichier. Un format que la tâche n'a pas généré n'a pas de clé, plutôt qu'une chaîne vide.
- Name
  glb
  Type
  string
  Description
  Le fichier GLB.
- Name
  fbx
  Type
  string
  Description
  Le fichier FBX.
- Name
  usdz
  Type
  string
  Description
  Le fichier USDZ.
- Name
  obj
  Type
  string
  Description
  Le fichier OBJ.
- Name
  mtl
  Type
  string
  Description
  Le fichier MTL.
- Name
  stl
  Type
  string
  Description
  Le fichier STL.
- Name
  3mf
  Type
  string
  Description
  Le fichier 3MF. Présent uniquement lorsque target_formats inclut 3mf.
Name
prompt
Type
string
Description
Le prompt que vous avez envoyé pour créer la tâche, non modifié.
Name
texture_prompt
Type
string
Description
Le prompt texte que vous avez envoyé pour guider la texturation lors de l'étape refine.
Name
ultra_mode
Type
boolean
⚠ obsolète
Description
Consultez plutôt geometry_resolution.
Name
geometry_resolution
Type
string
Description
Le palier Ultra sur lequel la tâche preview s'est exécutée, 2k ou 4k. Le champ est absent pour standard.
Name
texture_image_url
Type
string
Description
URL de téléchargement pour l'image que vous avez envoyée pour guider la texturation.
Name
thumbnail_url
Type
string
Description
URL de téléchargement pour une image miniature du modèle 3D.
Name
alpha_thumbnail_url
Type
string
Description
URL de téléchargement pour une version de thumbnail_url avec un arrière-plan transparent (RGBA). Présent uniquement lorsque vous avez créé la tâche avec alpha_thumbnail: true et que Meshy a rendu l'aperçu transparent.
Name
video_url
Type
string
⚠ obsolète
Description
Ne vous fiez pas à ce champ, car une future version le supprimera. URL de téléchargement pour la vidéo d'aperçu.
Name
progress
Type
integer
Description
La part de la tâche déjà effectuée, en pourcentage. C'est 0 jusqu'à ce que la tâche démarre et 100 quand elle réussit.
Name
started_at
Type
timestamp
Description
L'heure de démarrage de la tâche, en millisecondes Unix. C'est 0 jusqu'à ce que la tâche démarre.
Name
created_at
Type
timestamp
Description
L'heure de création de la tâche, en millisecondes Unix.
Name
finished_at
Type
timestamp
Description
L'heure de fin de la tâche, en millisecondes Unix. C'est 0 jusqu'à ce que la tâche se termine.
Name
status
Type
string
Description
Le statut de la tâche, l'un de PENDING, IN_PROGRESS, SUCCEEDED, FAILED, ou CANCELED.
Name
texture_urls
Type
array
Description
Les URL de téléchargement pour les cartes de texture générées, sous forme d'un tableau d'objets. Il contient généralement un seul objet. Chaque objet possède les champs suivants :
- Name
  base_color
  Type
  string
  Description
  La carte de couleur de base.
- Name
  metallic
  Type
  string
  Description
  La carte métallique. Absente lorsque vous avez créé la tâche avec enable_pbr: false.
- Name
  normal
  Type
  string
  Description
  La normal map. Absente lorsque vous avez créé la tâche avec enable_pbr: false.
- Name
  roughness
  Type
  string
  Description
  La carte de rugosité. Absente lorsque vous avez créé la tâche avec enable_pbr: false.
- Name
  emission
  Type
  string
  Description
  La carte d'émission. Absente dans l'un de ces cas :
  
  Vous avez créé la tâche avec enable_pbr: false.
  
  ai_model vaut meshy-6-lite, meshy-7, meshy-7.1, ou latest.
  
  texture_resolution vaut 8k.
  
  La tâche affine (refine) une preview meshy-t2 ou meshy-t2.5 sans définir ai_model.
Name
preceding_tasks
Type
integer
Description
Le nombre de tâches qui précèdent celle-ci dans la file d'attente. La valeur n'a de sens que tant que la tâche est PENDING.
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. Présent lorsque le statut est PENDING, IN_PROGRESS, ou SUCCEEDED. C'est 0 pour une tâche FAILED, car Meshy rembourse les crédits lorsqu'une tâche échoue.