lowpoly sera retiré le 30 oct. 2026. meshy-7 sera retiré en tant que modèle de génération 3D le 31 déc. 2026 ; il reste disponible en tant que modèle de texture. Changez de modèle avant ces dates pour éviter les erreurs de requête. Voir toutes les dépréciations

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

Create a Text to 3D preview task

Crée une tâche de prévisualisation Texte en 3D, qui génère un maillage 3D sans texture (géométrie uniquement) à partir d'un prompt textuel. C'est 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 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 Temps 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 définition
    • 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 plutôt meshy-7.1. Il sera retiré le 31 décembre 2026.

    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 net pour les assets de jeu, sortie en triangles, et un nombre de faces que vous définissez avec target_polycount

    Voir Modèles pour savoir quel modèle convient à votre projet, comme un personnage de jeu ou une impression 3D.

  • Name
    geometry_resolution
    Type
    string
    défaut standard
    Description

    La passe de génération de 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 l'ancien meshy-7 obsolète. 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 plutôt geometry_resolution. 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 à 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 :

    CasPlageValeur par défaut
    Remaillage100 à 30000030000
    meshy-t2100 à 150004000
    meshy-t2.5100 à 3000015000

    Une valeur hors de la plage renvoie 400.

    Pour un asset de jeu low-poly, utilisez un modèle Smart Topology plutôt que de remailler un modèle standard. Voir Modèles.

  • Name
    symmetry_mode
    Type
    string
    ⚠ obsolète
    défaut auto
    Description

    Ne l'incluez pas. Ce paramètre n'affecte pas la sortie.

    Valeurs disponibles :

    • off : désactive la symétrie
    • auto : applique la symétrie selon la géométrie d'entrée
    • on : impose la symétrie pendant la génération
  • Name
    pose_mode
    Type
    string
    Description

    La pose pour un modèle de personnage, a-pose ou t-pose. Pour n'avoir aucune pose, n'incluez pas pose_mode ni is_a_t_pose.

  • Name
    is_a_t_pose
    Type
    boolean
    ⚠ obsolète
    défaut false
    Description

    Envoyez plutôt pose_mode. 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 vérifier 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 ne l'incluez pas, 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 générer une prévisualisation avec un fond 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.

Retours

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 quel problème a été 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 n'a pas assez 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.
    • 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
    403 - Forbidden
    Description

    La modération de contenu a bloqué le prompt ou une image d'entrée. Modifiez l'entrée, 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 dans preview_task_id. Voir Créer une tâche preview Texte en 3D. Il s'agit de la deuxième é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
}'

# Refine with Meshy N1 from the preview's stored reference image
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",
  "ai_model": "meshy-n1"
}'

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 avec texture_resolution: 8k. meshy-6-lite, meshy-7 et latest ne génèrent pas de carte d'émission. Il en va de même pour un refine d'une preview meshy-t2 ou meshy-t2.5 qui ne définit pas ai_model. Avec ai_model: meshy-n1, true renvoie 400.

  • 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 ou latest. Avec meshy-n1, elles renvoient 400. En 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. Avec ai_model: meshy-n1, l'envoyer renvoie 400.

  • 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, d'au moins 32 pixels de chaque côté, et d'au plus 178 956 970 pixels (largeur × hauteur).

    Avec ai_model: meshy-n1, Meshy texture à partir de cette image en tant que vue de face.

  • Name
    ai_model
    Type
    string
    défaut hérité de la tâche preview
    Description

    Le modèle d'IA qui texture le maillage. Le maillage provient de la preview, donc pour un refine, ai_model ne sélectionne que le modèle de texture.

    Valeurs disponibles :

    • meshy-7 : Meshy 7
    • latest : le modèle de texture le plus récent, actuellement Meshy 7
    • meshy-6 : Meshy 6
    • meshy-6-lite : Meshy 6 Lite
    • meshy-n1 : une texture de couleur de base en 2K à partir d'une image de référence uniquement. Pas de prompt textuel, pas de cartes PBR, pas de 4K ni 8K.

    Les valeurs ci-dessus sont des modèles de texture. Omettez-le pour texturer avec le modèle correspondant à la preview. Envoyez une valeur pour le remplacer.

    Avec meshy-n1, Meshy texture à partir de texture_image_url. Sans cela, Meshy utilise l'image de référence qu'une preview meshy-7.1 ou latest stocke. Toute autre preview renvoie 400 sauf si vous envoyez texture_image_url. La preview peut comporter au plus 7 999 999 triangles. Une preview remeshée en quads renvoie 400.

  • Name
    moderation
    Type
    boolean
    défaut false
    Description

    Indique s'il faut contrôler texture_prompt et texture_image_url pour détecter tout contenu préjudiciable avant la génération. Si Meshy détecte un 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é.

    Ne prend effet que lorsque ai_model est meshy-6. meshy-7 et latest l'acceptent et l'ignorent, tout comme un 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. Avec meshy-n1, true renvoie 400.

  • 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 aussi rendre un aperçu avec un arrière-plan transparent (RGBA), renvoyé 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 par vision 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.

Retours

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 quel problème a été détecté. 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".
    • Aucune image de référence pour Meshy N1 : ai_model: meshy-n1 a été envoyé sans texture_image_url, et la preview ne possède aucune image de référence utilisable par Meshy N1. Envoyez texture_image_url.
    • Preview en quads pour Meshy N1 : ai_model: meshy-n1 a été envoyé pour une preview remeshée en quads. Effectuez le refine avec un autre ai_model.
    • Trop de triangles pour Meshy N1 : Avec ai_model: meshy-n1, la preview comporte plus de 7 999 999 triangles. Effectuez le refine avec un autre ai_model.
    • Option non prise en charge pour Meshy N1 : ai_model: meshy-n1 a été envoyé avec l'une de ces options :
      • texture_prompt
      • enable_pbr: true
      • texture_resolution de 4k ou 8k
      • hd_texture: true sans texture_resolution
      • remove_lighting: true

    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 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.
    • Formule gratuite : La création d'une tâche nécessite une formule payante. Mettez à niveau votre formule dans vos paramètres d'abonnement, puis réessayez.
  • Name
    403 - Forbidden
    Description

    La modération de contenu a bloqué le prompt ou une image d'entrée. Modifiez l'entrée, puis réessayez.

  • Name
    429 - Too Many Requests
    Description

    Vous avez dépassé votre limite de débit. Patientez, puis réessayez. Voir Limites de débit.


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

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

Renvoie 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": null,

  "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 de tâche Texte en 3D.

Exemples

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

ModeModèle d'exemple
PrévisualisationPreview model
RefineRefined model

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": null,

    "consumed_credits": 20
  }
]

Paramètres

  • Name
    page_num
    Type
    integer
    défaut 1
    Description

    Le numéro de page à renvoyer, jusqu'à 255. Une valeur plus grande renvoie 400.

  • 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 : les plus anciennes en premier
    • -created_at : les plus récentes en premier

Retours

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


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

Diffuser en continu une 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": null,

"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, sous la même forme que celle renvoyé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 textuel. Il contient le statut, la progression, ainsi que 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": null,

  "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 du 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 textuel que vous avez envoyé pour guider la création de texture 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 a été exécutée, 2k ou 4k. Le champ est absent pour standard.

  • Name
    texture_image_url
    Type
    string
    Description

    URL de téléchargement de l'image que vous avez envoyée pour guider la création de texture.

  • Name
    thumbnail_url
    Type
    string
    Description

    URL de téléchargement d'une image miniature du modèle 3D.

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    URL de téléchargement d'une version de thumbnail_url avec un fond 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
    progress
    Type
    integer
    Description

    La part de la tâche réalisée, en pourcentage. Elle vaut 0 jusqu'au démarrage de la tâche et 100 lorsqu'elle réussit.

  • Name
    started_at
    Type
    timestamp
    Description

    Heure de démarrage de la tâche, en millisecondes Unix. Elle vaut 0 jusqu'au démarrage de la tâche.

  • Name
    created_at
    Type
    timestamp
    Description

    Heure de création de la tâche, en millisecondes Unix.

  • Name
    finished_at
    Type
    timestamp
    Description

    Heure de fin de la tâche, en millisecondes Unix. Elle vaut 0 jusqu'à la fin de la tâche.

  • Name
    status
    Type
    string
    Description

    Le statut de la tâche, l'une des valeurs PENDING, IN_PROGRESS, SUCCEEDED, FAILED ou CANCELED.

  • Name
    texture_urls
    Type
    array
    Description

    Les URL de téléchargement des cartes de texture générées, sous forme de 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 metallic. 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 roughness. Absente lorsque vous avez créé la tâche avec enable_pbr: false.

    • Name
      emission
      Type
      string
      Description

      La carte emission. Absente dans l'un des cas suivants :

      • 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. Cette valeur n'a de sens que lorsque la tâche est PENDING.

  • Name
    task_error
    Type
    object
    Description

    Les détails de l'erreur lorsque la tâche échoue. La valeur est null sauf si le statut est FAILED. 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. Il vaut 0 pour une tâche FAILED, car Meshy rembourse les crédits lorsqu'une tâche échoue.