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 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.


POST/openapi/v1/image-to-3d

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

POST
/openapi/v1/image-to-3d
# 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 statut SUCCEEDED, 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, comme data:image/jpeg;base64,<vos données d'image encodées en base64>. Si vous envoyez les deux, Meshy utilise input_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écision
    • smart-topology : un maillage provenant d'un modèle Smart Topology, que vous choisissez avec ai_model (meshy-t2 ou meshy-t2.5)

    Avec smart-topology, Meshy ignore should_remesh, save_pre_remeshed_model 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) :

    • latest : Meshy 7.1
    • meshy-7.1
    • meshy-6
    • meshy-6-lite
    • meshy-7 (obsolète) : utilisez meshy-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 avec target_polycount :

    • meshy-t2 : topology plus propre et parties nativement séparées
    • meshy-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 :

    • standard
    • 2k : exécute la passe Ultra à 2048³
    • 4k : exécute la passe Ultra à 4096³, pour le plus de détails de surface

    2k nécessite meshy-7.1, latest, ou le modèle obsolète meshy-7. 4k nécessite meshy-7.1 ou latest.

  • 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. true renvoie un modèle texturé, et false ignore la texturation et renvoie un maillage non texturé.

S'applique uniquement quand 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'à 8K
    • meshy-n1 : Meshy N1, une texture de couleur de base 2K à partir des images de référence uniquement
    • meshy-6-lite : Meshy 6 Lite, une texture 2K au coût le plus bas
    • meshy-6 : Meshy 6, uniquement comme valeur par défaut pour ai_model: meshy-6

    Chaque ai_model accepte meshy-7, meshy-n1 et meshy-6-lite. Une option que le modèle de texture choisi ne prend pas en charge renvoie 400. Avec meshy-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. Avec should_texture: false, Meshy ignore texture_model, mais une valeur inconnue renvoie quand même 400.

    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. true nécessite should_texture: true, et renvoie 400 avec should_texture: false. Avec texture_model: meshy-n1, true renvoie 400.

    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×2048
    • 4k : 4096×4096
    • 8k : 8192×8192

    4k et 8k nécessitent le modèle de texture Meshy 7 ou Meshy 6, et renvoient 400 avec 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 utilise texture_resolution.

  • Name
    texture_prompt
    Type
    string
    Description

    Texte qui guide la texture, jusqu'à 800 caractères. Un texte plus long renvoie 400. Avec texture_model: meshy-n1, l'envoyer renvoie 400.

  • 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_prompt et texture_image_url. Si vous envoyez les deux, Meshy utilise texture_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.

  • 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.

S'applique uniquement quand 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ères
    • triangle : un maillage triangulaire décimé

    La sortie Smart Topology est uniquement en triangles, donc quad avec meshy-t2 ou meshy-t2.5 renvoie 400. Avec texture_model: meshy-n1, quad renvoie 400 lorsque le modèle est remaillé, ce que fait meshy-6-lite par 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 : ultra
    • 2 : élevé
    • 3 : moyen
    • 4 : 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_remesh vaut true sur un modèle standard, Meshy décime le maillage à environ ce nombre. Si vous définissez decimation_mode, Meshy l'utilise et ignore target_polycount.
    • Smart Topology : Lorsque model_type vaut smart-topology et que ai_model vaut meshy-t2 ou meshy-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 de should_remesh.

    La plage et la valeur par défaut dépendent du cas :

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

    Une 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.

  • 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étrie
    • auto : symétrie choisie à partir de la géométrie d'entrée
    • on : symétrie imposée
  • Name
    pose_mode
    Type
    string
    Description

    La pose pour un modèle de personnage, a-pose ou t-pose. Pour n'avoir aucune pose, omettez pose_mode et is_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 organic et hard. Toute autre valeur renvoie 400.

  • Name
    image_enhancement
    Type
    boolean
    défaut true
    Description

    Indique s'il faut optimiser l'image d'entrée avant la génération. false conserve l'aspect exact de l'image d'entrée, sans aucun traitement de style.

    Cela fonctionne uniquement avec meshy-6, meshy-7.1, ou latest. Avec meshy-6-lite ou model_type: smart-topology, cela renvoie 400.

  • 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 400 pour true. Avec model_type: smart-topology, ou avec ai_model: meshy-6-lite et son modèle de texture par défaut, l'envoyer renvoie 400.

  • 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_url
    • texture_image_url
    • texture_prompt

    Si Meshy détecte du 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 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 :

    • glb
    • obj
    • fbx
    • stl
    • usdz
    • 3mf
  • 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_url lorsque vous récupérez la tâche. thumbnail_url ne 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_urls lorsque vous récupérez la tâche. thumbnail_url ne change pas et montre toujours la vue de face. Cela ajoute environ 5 secondes à la tâche.

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 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_url ni input_task_id n'a été envoyé.
    • Tâche d'entrée invalide : input_task_id n'est pas une tâche Texte en image ou Image en image avec le statut SUCCEEDED ayant produit exactement une image.
    • Format d'image invalide : L'image image_url n'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 renvoie 404 ou expire.
    • Image trop grande : L'image image_url ou texture_image_url dépasse 20 Mo.
    • Taille d'image invalide : L'image image_url ou texture_image_url a 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_pbr vaut true, et should_texture vaut false.
    • 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.
    • Modèle non pris en charge pour les options d'image : l'un des cas suivants :
      • image_enhancement a été envoyé avec ai_model: "meshy-6-lite" ou model_type: "smart-topology".
      • remove_lighting a été envoyé avec model_type: "smart-topology", ou avec ai_model: "meshy-6-lite" et son modèle de texture par défaut.
    • Modèle de texture invalide : texture_model ne correspond à aucune des valeurs disponibles.
    • Modèle de texture non disponible : texture_model vaut meshy-6 avec un ai_model autre que meshy-6. Envoyez meshy-7, meshy-n1, ou meshy-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: true avec meshy-n1 ou une texture 4k avec meshy-6-lite. Consultez Modèles.

    Corrigez la requête, puis envoyez-la à nouveau. Consultez 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.
    • 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_id ne 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.


GET/openapi/v1/image-to-3d/:id

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

Renvoie une tâche Image en 3D à partir de son ID.

Request

GET
/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578
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

L'objet tâche Image en 3D.


DELETE/openapi/v1/image-to-3d/:id

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

DELETE
/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578
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.


GET/openapi/v1/image-to-3d

Liste des tâches Image en 3D

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

Request

GET
/openapi/v1/image-to-3d
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 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 : 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.


GET/openapi/v1/image-to-3d/:id/stream

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

GET
/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream
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_formats inclut 3mf.

    • 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: true et save_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_urls est présent, il s'agit de la même image que thumbnail_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_url avec un fond transparent (RGBA). Présent uniquement lorsque vous avez créé la tâche avec alpha_thumbnail: true et 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: true et que la tâche a atteint SUCCEEDED. Les tâches créées sans multi_view_thumbnails: true n'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, 2k ou 4k. Une tâche standard n'inclut pas ce champ.

  • Name
    progress
    Type
    integer
    Description

    La part de la tâche terminée, exprimée en pourcentage. Elle est à 0 tant que la tâche n'a pas démarré et à 100 quand elle réussit.

  • Name
    started_at
    Type
    timestamp
    Description

    L'heure de démarrage de la tâche, en millisecondes Unix. Elle est à 0 tant 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 à 0 tant 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, FAILED ou CANCELED.

  • 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éfaut
      • enable_pbr: true
      • une texture_resolution de 2k ou 4k
  • 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 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 est à 0 pour une tâche FAILED, car Meshy rembourse les crédits lorsqu'une tâche échoue.