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.
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
# 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
previewpour 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éfinitionsmart-topology: un maillage Smart Topology. Choisissez le modèle avecai_model(meshy-t2oumeshy-t2.5).
Avec
smart-topology, Meshy ignoreshould_remeshetdecimation_mode, et n'accepte quetopology: 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-litemeshy-6meshy-7.1latest: Meshy 7.1meshy-7(obsolète) : envoyez plutôtmeshy-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 avectarget_polycountmeshy-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 avectarget_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 :
standard2k: exécute la passe Ultra à 2048³4k: exécute la passe Ultra à 4096³, pour un détail de surface plus fin
2knécessitemeshy-7.1,latest, ou l'ancienmeshy-7obsolète.4knécessitemeshy-7.1oulatest. Les autres modèles renvoient400.
- 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.
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èrestriangle: un maillage triangulaire décimé
La sortie Smart Topology est uniquement en triangles. Envoyer
quadavecai_modelmeshy-t2oumeshy-t2.5renvoie400.
- Name
- decimation_mode
- Type
- integer
- Description
Nombre de faces adaptatif, par niveau. Lorsque vous le définissez, Meshy ignore
target_polycount.Valeurs disponibles :
1: ultra2: élevé3: moyen4: 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: truesur un modèlestandard. Meshy remaille (décime) le maillage à environ ce nombre. Si vous définissezdecimation_mode, Meshy l'utilise et ignoretarget_polycount. - Smart Topology : avec
model_type: smart-topologyetai_modelmeshy-t2oumeshy-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 deshould_remesh.
Le tableau suivant indique la plage et la valeur par défaut pour chaque cas :
Cas Plage Valeur par défaut Remaillage 100à30000030000meshy-t2100à150004000meshy-t2.5100à3000015000Une 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.
- Remaillage : avec
- 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étrieauto: applique la symétrie selon la géométrie d'entréeon: impose la symétrie pendant la génération
- Name
- pose_mode
- Type
- string
- Description
La pose pour un modèle de personnage,
a-poseout-pose. Pour n'avoir aucune pose, n'incluez paspose_modeniis_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
promptpour détecter tout contenu nuisible avant la génération. Si Meshy détecte un contenu nuisible, la requête renvoie400et 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 :
glbobjfbxstlusdz3mf
- 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_urllorsque vous récupérez la tâche.thumbnail_urlne 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.
auto_size = true- Name
- origin_at
- Type
- string
- défaut bottom
- Description
Où placer l'origine du modèle,
bottomoucenter.
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
promptoumode, est manquant. - Prompt trop long :
promptdépasse la limite de caractères. - Modèle non pris en charge pour Ultra :
geometry_resolutionvaut2kou4k, avec unai_modelqui ne peut pas l'exécuter.
Corrigez la requête, puis renvoyez-la. Voir Erreurs.
- Paramètre manquant : un paramètre requis, comme
- 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.
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
# 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
refinepour 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_modelmeshy-6, Meshy génère aussi une carte d'émission, sauf avectexture_resolution: 8k.meshy-6-lite,meshy-7etlatestne génèrent pas de carte d'émission. Il en va de même pour un refine d'une previewmeshy-t2oumeshy-t2.5qui ne définit pasai_model. Avecai_model: meshy-n1,truerenvoie400.
- 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×20484k: 4096×40968k: 8192×8192
Des résolutions plus élevées capturent davantage de détails de surface.
4ket8knécessitentai_modelmeshy-6,meshy-7oulatest. Avecmeshy-n1, elles renvoient400. En8k, 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 utilisetexture_resolution.
- Name
- texture_prompt
- Type
- string
- Description
Texte qui guide la texturation, jusqu'à 800 caractères. Un texte plus long renvoie
400. Envoyeztexture_promptoutexture_image_url, pas les deux. Si vous envoyez les deux, Meshy utilisetexture_prompt. Avecai_model: meshy-n1, l'envoyer renvoie400.
- 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,.pngou.webpd'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.La texturation à partir d'une image peut mal fonctionner lorsque la forme de l'image diffère beaucoup du modèle.
- 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_modelne sélectionne que le modèle de texture.Valeurs disponibles :
meshy-7: Meshy 7latest: le modèle de texture le plus récent, actuellement Meshy 7meshy-6: Meshy 6meshy-6-lite: Meshy 6 Litemeshy-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 detexture_image_url. Sans cela, Meshy utilise l'image de référence qu'une previewmeshy-7.1oulateststocke. Toute autre preview renvoie400sauf si vous envoyeztexture_image_url. La preview peut comporter au plus 7 999 999 triangles. Une preview remeshée en quads renvoie400.
- Name
- moderation
- Type
- boolean
- défaut false
- Description
Indique s'il faut contrôler
texture_promptettexture_image_urlpour détecter tout contenu préjudiciable avant la génération. Si Meshy détecte un contenu préjudiciable, la requête renvoie400et 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_modelestmeshy-6.meshy-7etlatestl'acceptent et l'ignorent, tout comme un refine d'une previewmeshy-t2oumeshy-t2.5qui ne définit pasai_model. L'envoyer avecmeshy-6-literenvoie400. Avecmeshy-n1,truerenvoie400.
- 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 :
glbobjfbxstlusdz3mf
- 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_urllorsque vous récupérez la tâche.thumbnail_urlne 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.
auto_size = true- Name
- origin_at
- Type
- string
- défaut bottom
- Description
Où placer l'origine du modèle,
bottomoucenter.
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_idest 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_lightinga été envoyé avecai_model: "meshy-6-lite". - Aucune image de référence pour Meshy N1 :
ai_model: meshy-n1a été envoyé sanstexture_image_url, et la preview ne possède aucune image de référence utilisable par Meshy N1. Envoyeztexture_image_url. - Preview en quads pour Meshy N1 :
ai_model: meshy-n1a été envoyé pour une preview remeshée en quads. Effectuez le refine avec un autreai_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 autreai_model. - Option non prise en charge pour Meshy N1 :
ai_model: meshy-n1a été envoyé avec l'une de ces options :texture_promptenable_pbr: truetexture_resolutionde4kou8khd_texture: truesanstexture_resolutionremove_lighting: true
Corrigez la requête, puis renvoyez-la. Voir Erreurs.
- ID de tâche invalide :
- 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.
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
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
Exemples
Le tableau suivant présente un modèle d'exemple pour chaque mode.
| Mode | Modèle d'exemple |
|---|---|
| Prévisualisation | ![]() |
| Refine | ![]() |
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
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.
Lister les tâches Texte en 3D
Renvoie une liste de vos tâches Texte en 3D.
Request
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 renvoie400.
- 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.
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
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-previewpour une tâche preview outext-to-3d-refinepour 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_formatsinclut3mf.
- Name
- prompt
- Type
- string
- Description
Le
promptque 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,
2kou4k. Le champ est absent pourstandard.
- 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_urlavec un fond transparent (RGBA). Présent uniquement lorsque vous avez créé la tâche avecalpha_thumbnail: trueet 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
0jusqu'au démarrage de la tâche et100lorsqu'elle réussit.
- Name
- started_at
- Type
- timestamp
- Description
Heure de démarrage de la tâche, en millisecondes Unix. Elle vaut
0jusqu'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
0jusqu'à 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,FAILEDouCANCELED.
- 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_modelvautmeshy-6-lite,meshy-7,meshy-7.1, oulatest.texture_resolutionvaut8k.- La tâche affine (refine) une preview
meshy-t2oumeshy-t2.5sans définirai_model.
- Vous avez créé la tâche avec
- 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
nullsauf si le statut estFAILED. 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_PROGRESSouSUCCEEDED. Il vaut0pour une tâcheFAILED, car Meshy rembourse les crédits lorsqu'une tâche échoue.

