API Image en 3D
Transformez une image en modèle 3D, texturé ou non texturé, dans les formats de votre choix. Envoyez l'image, ou utilisez le résultat d'une tâche Texte en image ou Image en image.
Créer une tâche Image en 3D
Crée une tâche Image en 3D. La tâche s'exécute en arrière-plan. Pour connaître la durée habituelle d'une tâche, consultez Temps de traitement.
Request
# Simple request with required params
curl https://api.meshy.ai/openapi/v1/image-to-3d \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"image_url": "<your publicly accessible image url or base64-encoded data URI>"
}'
# With Ultra 4K geometry, remesh, PBR, and A-pose
curl https://api.meshy.ai/openapi/v1/image-to-3d \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"image_url": "<your publicly accessible image url or base64-encoded data URI>",
"ai_model": "meshy-7.1",
"geometry_resolution": "4k",
"enable_pbr": true,
"should_remesh": true,
"target_polycount": 100000,
"should_texture": true,
"pose_mode": "a-pose",
"target_formats": ["glb"]
}'
# Textured with Meshy N1 from the input image
curl https://api.meshy.ai/openapi/v1/image-to-3d \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"image_url": "<your publicly accessible image url or base64-encoded data URI>",
"ai_model": "meshy-7.1",
"texture_model": "meshy-n1"
}'
Response
{
"result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
Paramètres
- Name
- input_task_id
- Type
- string
- Requis
- Description
Requis sauf si vous envoyez
image_url. L'ID d'une tâche Texte en image ou Image en image dont vous souhaitez utiliser l'image comme entrée. La tâche doit être une tâche que vous avez créée avec l'API, avoir le statutSUCCEEDED, et avoir produit exactement une image.
- Name
- image_url
- Type
- string
- Requis
- Description
Requis sauf si vous envoyez
input_task_id. L'image à transformer en modèle 3D, sous forme d'URL publique ou de Data URI encodée en base64, commedata:image/jpeg;base64,<vos données d'image encodées en base64>. Si vous envoyez les deux, Meshy utiliseinput_task_id.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).
- Name
- model_type
- Type
- string
- défaut standard
- Description
Le type de maillage 3D à générer.
Valeurs disponibles :
standard: un maillage haute précisionsmart-topology: un maillage provenant d'un modèle Smart Topology, que vous choisissez avecai_model(meshy-t2oumeshy-t2.5)
Avec
smart-topology, Meshy ignoreshould_remesh,save_pre_remeshed_modeletdecimation_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) :latest: Meshy 7.1meshy-7.1meshy-6meshy-6-litemeshy-7(obsolète) : utilisezmeshy-7.1à la place. Il sera retiré le 31 décembre 2026.
Les modèles Smart Topology (
model_type: smart-topology) produisent des triangles, avec un nombre de faces que vous pouvez définir avectarget_polycount:meshy-t2: topology plus propre et parties nativement séparéesmeshy-t2.5(par défaut) : détails plus nets pour les assets de jeu
Consultez 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.
Valeurs disponibles :
standard2k: exécute la passe Ultra à 2048³4k: exécute la passe Ultra à 4096³, pour le plus de détails de surface
2knécessitemeshy-7.1,latest, ou le modèle obsolètemeshy-7.4knécessitemeshy-7.1oulatest.
- Name
- ultra_mode
- Type
- boolean
- ⚠ obsolète
- défaut false
- Description
Utilisez
geometry_resolutionà la place.ultra_mode: trueéquivaut àgeometry_resolution: "2k".
- Name
- should_texture
- Type
- boolean
- défaut true
- Description
Indique s'il faut générer des textures.
truerenvoie un modèle texturé, etfalseignore la texturation et renvoie un maillage non texturé.
should_texture = true- Name
- texture_model
- Type
- string
- défaut depends on ai_model
- Description
Le modèle d'IA qui texture le modèle 3D, dans la même tâche. Omettez-le pour utiliser le modèle de texture par défaut pour votre
ai_model. Cela ne change pas le coût en crédits.Valeurs disponibles :
meshy-7: Meshy 7, avec cartes PBR et textures jusqu'à 8Kmeshy-n1: Meshy N1, une texture de couleur de base 2K à partir des images de référence uniquementmeshy-6-lite: Meshy 6 Lite, une texture 2K au coût le plus basmeshy-6: Meshy 6, uniquement comme valeur par défaut pourai_model: meshy-6
Chaque
ai_modelacceptemeshy-7,meshy-n1etmeshy-6-lite. Une option que le modèle de texture choisi ne prend pas en charge renvoie400. Avecmeshy-n1, un modèle généré de plus de 7 999 999 triangles fait échouer la tâche, et Meshy rembourse ses crédits. Avecshould_texture: false, Meshy ignoretexture_model, mais une valeur inconnue renvoie quand même400.Consultez Modèles pour savoir ce que fait chaque modèle de texture et lequel choisir.
- 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.
truenécessiteshould_texture: true, et renvoie400avecshould_texture: false. Avectexture_model: meshy-n1,truerenvoie400.Le modèle de texture Meshy 6 génère aussi une carte d'émission, sauf à
texture_resolution: 8k.
- Name
- texture_resolution
- Type
- string
- défaut 2k
- Description
La taille de la texture de couleur de base. Une texture plus grande capture plus de détails de surface.
Valeurs disponibles :
2k: 2048×20484k: 4096×40968k: 8192×8192
4ket8knécessitent le modèle de texture Meshy 7 ou Meshy 6, et renvoient400avec les autres. À8k, Meshy ne produit pas de carte d'émission.
- Name
- hd_texture
- Type
- boolean
- ⚠ obsolète
- défaut false
- Description
Utilisez
texture_resolutionà la place.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 texture, jusqu'à 800 caractères. Un texte plus long renvoie
400. Avectexture_model: meshy-n1, l'envoyer renvoie400.
- Name
- texture_image_url
- Type
- string
- Description
Une image qui guide la texture, 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).Meshy guide la texture avec un seul de
texture_promptettexture_image_url. Si vous envoyez les deux, Meshy utilisetexture_prompt. Pour le coût en crédits de la texturation, consultez Tarification.Avec
texture_model: meshy-n1, Meshy texture à partir de cette image comme vue de face, ou à partir de l'image d'entrée lorsque vous l'omettez.La texturation à partir d'une image peut ne pas bien fonctionner lorsque la forme de l'image diffère beaucoup de la géométrie du modèle 3D.
- Name
- should_remesh
- Type
- boolean
- défaut true (meshy-6-lite), false (other models)
- Description
Indique s'il faut exécuter la phase de remaillage. Pour le modèle 3D de la plus haute qualité, définissez-le sur
false.
should_remesh = true- Name
- topology
- Type
- string
- défaut triangle
- Description
Le type de face 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, donc
quadavecmeshy-t2oumeshy-t2.5renvoie400. Avectexture_model: meshy-n1,quadrenvoie400lorsque le modèle est remaillé, ce que faitmeshy-6-litepar défaut.
- 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
- save_pre_remeshed_model
- Type
- boolean
- défaut false
- Description
Indique s'il faut aussi stocker un GLB du modèle d'avant la phase de remaillage. Meshy le renvoie dans
model_urls.pre_remeshed_glb.
- 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 du modèle.
Il s'applique dans deux cas distincts :
- Remaillage : Lorsque
should_remeshvauttruesur un modèlestandard, Meshy décime le maillage à environ ce nombre. Si vous définissezdecimation_mode, Meshy l'utilise et ignoretarget_polycount. - Smart Topology : Lorsque
model_typevautsmart-topologyet queai_modelvautmeshy-t2oumeshy-t2.5, Meshy génère le modèle avec ce nombre de faces. Aucun remaillage n'est exécuté, et vous n'avez pas besoin deshould_remesh.
La plage et la valeur par défaut dépendent du cas :
Cas Plage Par défaut Remaillage 100à30000030000meshy-t2100à150004000meshy-t2.5100à3000015000Une valeur hors de cette 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. Consultez Modèles.
- Remaillage : Lorsque
- Name
- symmetry_mode
- Type
- string
- ⚠ obsolète
- défaut auto
- Description
Omettez-le, car il n'affecte pas la sortie. Ses valeurs contrôlaient la symétrie pendant la génération :
off: aucune symétrieauto: symétrie choisie à partir de la géométrie d'entréeon: symétrie imposée
- Name
- pose_mode
- Type
- string
- Description
La pose pour un modèle de personnage,
a-poseout-pose. Pour n'avoir aucune pose, omettezpose_modeetis_a_t_pose.
- Name
- is_a_t_pose
- Type
- boolean
- ⚠ obsolète
- défaut false
- Description
Utilisez
pose_modeà la place. Indique s'il faut générer le modèle en pose A ou T.
- Name
- surface_mode
- Type
- string
- ⚠ obsolète
- Description
Utilisez
ai_modelà la place. Cela n'affecte pas la sortie, car la génération de modèle qu'il sélectionnait est retirée.Les valeurs acceptées sont
organicethard. Toute autre valeur renvoie400.
- Name
- image_enhancement
- Type
- boolean
- défaut true
- Description
Indique s'il faut optimiser l'image d'entrée avant la génération.
falseconserve l'aspect exact de l'image d'entrée, sans aucun traitement de style.Cela fonctionne uniquement avec
meshy-6,meshy-7.1, oulatest. Avecmeshy-6-liteoumodel_type: smart-topology, cela renvoie400.
- Name
- remove_lighting
- Type
- boolean
- défaut true
- Description
Indique s'il faut retirer les reflets et les ombres de la texture de couleur de base. Le résultat est plus propre et fonctionne mieux sous votre propre éclairage.
Cela ne prend effet qu'avec le modèle de texture Meshy 6, et un modèle de texture qui ne le prend pas en charge renvoie
400pourtrue. Avecmodel_type: smart-topology, ou avecai_model: meshy-6-liteet son modèle de texture par défaut, l'envoyer renvoie400.
- Name
- moderation
- Type
- boolean
- défaut false
- Description
Indique s'il faut filtrer ces entrées pour détecter du contenu nuisible avant la génération :
image_urltexture_image_urltexture_prompt
Si Meshy détecte du contenu nuisible, la requête renvoie
400et Meshy ne crée pas de tâche.
- Name
- target_formats
- Type
- string[]
- Description
Les formats de fichier à générer. Meshy génère et renvoie uniquement les formats que vous listez, ce qui peut raccourcir la tâche. Si vous l'omettez, Meshy génère tous les formats sauf
3mf, que vous n'obtenez que si vous le listez.Valeurs disponibles :
glbobjfbxstlusdz3mf
- Name
- auto_size
- Type
- boolean
- défaut false
- Description
Indique s'il faut estimer la hauteur réelle de l'objet avec 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.
- Name
- alpha_thumbnail
- Type
- boolean
- défaut false
- Description
Indique s'il faut aussi générer un aperçu avec un fond transparent (RGBA), renvoyé dans
alpha_thumbnail_urllorsque vous récupérez la tâche.thumbnail_urlne change pas.
- Name
- multi_view_thumbnails
- Type
- boolean
- défaut false
- Description
Indique s'il faut aussi générer des aperçus avant, droit, arrière et gauche, renvoyés dans
thumbnail_urlslorsque vous récupérez la tâche.thumbnail_urlne change pas et montre toujours la vue de face. Cela ajoute environ 5 secondes à la tâche.
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 Image 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 : Ni
image_urlniinput_task_idn'a été envoyé. - Tâche d'entrée invalide :
input_task_idn'est pas une tâche Texte en image ou Image en image avec le statutSUCCEEDEDayant produit exactement une image. - Format d'image invalide : L'image
image_urln'est pas un fichier JPG, JPEG, PNG ou WebP. - URL inaccessible : Meshy ne peut pas télécharger l'image
image_url, car l'URL renvoie404ou expire. - Image trop grande : L'image
image_urloutexture_image_urldépasse 20 Mo. - Taille d'image invalide : L'image
image_urloutexture_image_urla un côté inférieur à 32 pixels, ou dépasse 178 956 970 pixels (largeur × hauteur). - Data URI invalide : La chaîne base64 est mal formée.
- Combinaison de paramètres invalide :
enable_pbrvauttrue, etshould_texturevautfalse. - Modèle non pris en charge pour Ultra :
geometry_resolutionvaut2kou4k, avec unai_modelqui ne peut pas l'exécuter. - Modèle non pris en charge pour les options d'image : l'un des cas suivants :
image_enhancementa été envoyé avecai_model: "meshy-6-lite"oumodel_type: "smart-topology".remove_lightinga été envoyé avecmodel_type: "smart-topology", ou avecai_model: "meshy-6-lite"et son modèle de texture par défaut.
- Modèle de texture invalide :
texture_modelne correspond à aucune des valeurs disponibles. - Modèle de texture non disponible :
texture_modelvautmeshy-6avec unai_modelautre quemeshy-6. Envoyezmeshy-7,meshy-n1, oumeshy-6-lite, ou omettez-le. - Option non prise en charge pour le modèle de texture : La requête demande au modèle de texture une option qu'il ne prend pas en charge, comme
enable_pbr: trueavecmeshy-n1ou une texture4kavecmeshy-6-lite. Consultez Modèles.
Corrigez la requête, puis envoyez-la à nouveau. Consultez Erreurs.
- Paramètre manquant : Ni
- 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.
- Offre gratuite : La création d'une tâche nécessite un abonnement payant. Mettez à niveau votre abonnement 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
404 - Not Found- Description
input_task_idne correspond à aucune de vos tâches. Vérifiez l'ID de la tâche, puis envoyez à nouveau la requête.
- Name
429 - Too Many Requests- Description
Vous avez dépassé votre limite de débit. Patientez, puis réessayez. Consultez Limites de débit.
Récupérer une tâche Image en 3D
Renvoie une tâche Image en 3D à partir de son ID.
Request
curl https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "image-to-3d",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
"fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
"obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
"usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
"stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
"pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"thumbnail_urls": {
"front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
"right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
"back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
"left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
},
"texture_prompt": "",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"expires_at": 1692771679037,
"finished_at": 1692771669037,
"status": "SUCCEEDED",
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
"metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
"normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
"roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
"emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 30
}
Paramètres
- Name
- id
- Type
- path
- Description
L'ID de la tâche provenant de la réponse de création.
Retourne
Supprimer une tâche Image en 3D
Supprime définitivement une tâche Image 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/v1/image-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 ferait perdre à 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.
Liste des tâches Image en 3D
Renvoie une liste de vos tâches Image en 3D.
Request
curl https://api.meshy.ai/openapi/v1/image-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
[
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "image-to-3d",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
"fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
"obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
"usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
"pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"thumbnail_urls": {
"front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
"right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
"back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
"left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
},
"texture_prompt": "",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"expires_at": 1692771679037,
"finished_at": 1692771669037,
"status": "SUCCEEDED",
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
"metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
"normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
"roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
"emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 30
}
]
Paramètres
- Name
- page_num
- Type
- integer
- défaut 1
- Description
Le numéro de page à renvoyer, jusqu'à
255. Une valeur plus élevée 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: 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 Image en 3D.
Diffuser les mises à jour d'une tâche Image en 3D
Diffuse les mises à jour d'une tâche Image en 3D sous forme d'événements envoyés par le serveur (Server-Sent Events, SSE).
Request
curl -N https://api.meshy.ai/openapi/v1/image-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",
"type": "image-to-3d",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
"fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
"obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
"usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
"stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
"pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"thumbnail_urls": {
"front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
"right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
"back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
"left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
},
"texture_prompt": "",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"expires_at": 1692771679037,
"finished_at": 1692771669037,
"status": "SUCCEEDED",
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
"metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
"normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
"roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
"emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 30
}
Paramètres
- Name
- id
- Type
- path
- Description
L'ID de la tâche renvoyé par la réponse de création.
Retours
Un flux d'objets de tâche Image en 3D sous forme d'événements envoyés par le serveur.
Chaque événement contient l'objet de tâche complet, selon le même format que celui renvoyé 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 Image en 3D
Un objet de tâche Image en 3D décrit une génération d'un modèle 3D à partir d'une image. Il contient le statut, la progression et les fichiers du modèle lorsque la tâche réussit.
Propriétés
Example Image to 3D Task Object
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "image-to-3d",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
"fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
"obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
"usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
"stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
"pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"thumbnail_urls": {
"front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
"right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
"back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
"left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
},
"texture_prompt": "",
"texture_image_url": "",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"expires_at": 1692771679037,
"finished_at": 1692771669037,
"status": "SUCCEEDED",
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
"metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
"normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
"roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
"emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 30
}
- 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, toujours
image-to-3d.
- 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
obj- Type
- string
- Description
Le fichier OBJ.
- Name
usdz- Type
- string
- Description
Le fichier USDZ.
- Name
mtl- Type
- string
- Description
Le fichier MTL, renvoyé avec un fichier OBJ lorsque le modèle possède des textures.
- Name
stl- Type
- string
- Description
Le fichier STL.
- Name
3mf- Type
- string
- Description
Le fichier 3MF. Présent uniquement lorsque
target_formatsinclut3mf.
- Name
pre_remeshed_glb- Type
- string
- Description
Le fichier GLB d'avant le remaillage. Présent uniquement lorsque vous avez créé la tâche avec à la fois
should_remesh: trueetsave_pre_remeshed_model: true.
- Name
- thumbnail_url
- Type
- string
- Description
L'URL de téléchargement d'une image d'aperçu du modèle 3D. Lorsque
thumbnail_urlsest présent, il s'agit de la même image quethumbnail_urls.front. Meshy la conserve pour des raisons de rétrocompatibilité.
- Name
- alpha_thumbnail_url
- Type
- string
- Description
L'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 généré l'aperçu transparent.
- Name
- thumbnail_urls
- Type
- object
- Description
Les URL de téléchargement des aperçus du modèle 3D depuis quatre côtés. Chaque valeur est une URL signée vers un PNG de 512×512, rendu avec les mêmes matériaux et le même éclairage que
thumbnail_url. Utilisez-les pour prévisualiser le modèle sous plusieurs angles, par exemple dans un pipeline de traitement par lots, sans télécharger le GLB.Présent uniquement lorsque vous avez créé la tâche avec
multi_view_thumbnails: trueet que la tâche a atteintSUCCEEDED. Les tâches créées sansmulti_view_thumbnails: truen'incluent pas ce champ.- Name
- front
- Type
- string
- Description
La vue de face, à 0° autour de l'axe vertical. Elle correspond à
thumbnail_url.
- Name
- right
- Type
- string
- Description
La vue de droite, à 90°.
- Name
- back
- Type
- string
- Description
La vue arrière, à 180°.
- Name
- left
- Type
- string
- Description
La vue de gauche, à 270°.
- Name
- texture_prompt
- Type
- string
- Description
Le prompt textuel qui a guidé la texture.
- Name
- texture_image_url
- Type
- string
- Description
L'URL de téléchargement de l'image qui a guidé la texture.
- Name
- ultra_mode
- Type
- boolean
- ⚠ obsolète
- Description
Consultez plutôt
geometry_resolution.
- Name
- geometry_resolution
- Type
- string
- Description
Le palier Ultra dans lequel la tâche s'est exécutée,
2kou4k. Une tâchestandardn'inclut pas ce champ.
- Name
- progress
- Type
- integer
- Description
La part de la tâche terminée, exprimée en pourcentage. Elle est à
0tant que la tâche n'a pas démarré et à100quand elle réussit.
- Name
- started_at
- Type
- timestamp
- Description
L'heure de démarrage de la tâche, en millisecondes Unix. Elle est à
0tant que la tâche n'a pas démarré.
- Name
- created_at
- Type
- timestamp
- Description
L'heure de création de la tâche, en millisecondes Unix.
- Name
- expires_at
- Type
- timestamp
- Description
L'heure d'expiration du résultat de la tâche, en millisecondes Unix.
- Name
- finished_at
- Type
- timestamp
- Description
L'heure de fin de la tâche, en millisecondes Unix. Elle est à
0tant que la tâche n'est pas terminée.
- Name
- status
- Type
- string
- Description
Le statut de la tâche, l'un des suivants :
PENDING,IN_PROGRESS,SUCCEEDED,FAILEDouCANCELED.
- Name
- texture_urls
- Type
- array
- Description
Les textures générées par la tâche, sous forme de tableau d'objets. Il contient généralement un seul objet, avec ces champs :
- Name
base_color- Type
- string
- Description
L'URL de téléchargement de la carte de couleur de base.
- Name
metallic- Type
- string
- Description
L'URL de téléchargement de la carte métallique. Le champ est absent lorsque vous avez créé la tâche avec
enable_pbr: false.
- Name
normal- Type
- string
- Description
L'URL de téléchargement de la normal map. Le champ est absent lorsque vous avez créé la tâche avec
enable_pbr: false.
- Name
roughness- Type
- string
- Description
L'URL de téléchargement de la carte de rugosité. Le champ est absent lorsque vous avez créé la tâche avec
enable_pbr: false.
- Name
emission- Type
- string
- Description
L'URL de téléchargement de la carte d'émission. Meshy ne l'inclut que lorsque vous avez créé la tâche avec tous les éléments suivants :
ai_model: meshy-6, avec son modèle de texture par défautenable_pbr: true- une
texture_resolutionde2kou4k
- Name
- preceding_tasks
- Type
- integer
- Description
Le nombre de tâches devançant 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 en cas d'échec de la tâche. Elle 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 est à0pour une tâcheFAILED, car Meshy rembourse les crédits lorsqu'une tâche échoue.