API Image en 3D

Transformez une image en modèle 3D, texturé ou non, 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"]
  }'

Response

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

Paramètres

Name
input_task_id
Type
string
Requis
Description
Obligatoire sauf si vous envoyez image_url. L'ID d'une tâche Texte en image ou Image en image dont vous voulez utiliser l'image comme entrée. La tâche doit avoir été créée par vous avec l'API, avoir le statut SUCCEEDED, et avoir produit exactement une image.

Name
image_url
Type
string
Requis
Description
Obligatoire 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 de 20 Mo maximum.

Name
model_type
Type
string
défaut standard
Description
Le type de maillage 3D à générer.
Valeurs disponibles :
- standard : un maillage à haut niveau de détail
- smart-topology : un maillage issu 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
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 : topologie plus propre et parties nativement séparées
- meshy-t2.5 (par défaut) : détail plus net pour les assets de jeu
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 un détail de surface maximal
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
enable_pbr
Type
boolean
défaut false
Description
Indique s'il faut aussi générer des cartes PBR (metallic, roughness et normal) en plus de la couleur de base. true nécessite should_texture: true, et renvoie 400 avec should_texture: false.
Avec meshy-6, Meshy génère aussi une carte d'émission, sauf à texture_resolution: 8k. Ces modèles ne produisent pas de carte d'émission :
- meshy-6-lite
- meshy-7
- meshy-7.1
- meshy-t2
- meshy-t2.5
- latest
Name
texture_resolution
Type
string
défaut 2k
Description
La taille de la texture de couleur de base. Une texture plus grande capture davantage de détail de surface.
Valeurs disponibles :
- 2k : 2048×2048
- 4k : 4096×4096
- 8k : 8192×8192
4k et 8k ne sont pas disponibles avec meshy-6-lite, et renvoient 400 dans ce cas. À 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
Un texte qui guide la texture, jusqu'à 800 caractères. Un texte plus long 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 de 20 Mo maximum.
Meshy guide la texture avec un seul des deux paramètres 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.
La texturation à partir d'une image peut mal 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 obtenir 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 de Smart Topology est uniquement en triangles, donc quad avec meshy-t2 ou meshy-t2.5 renvoie 400.
Name
decimation_mode
Type
integer
Description
Nombre de faces adaptatif, par niveau. Lorsque vous le définissez, Meshy ignore target_polycount.
Valeurs disponibles :
- 1 : ultra
- 2 : élevé
- 3 : moyen
- 4 : faible
Name
save_pre_remeshed_model
Type
boolean
défaut false
Description
Indique s'il faut aussi conserver 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 pour atteindre 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 est meshy-t2 ou meshy-t2.5, Meshy génère le modèle avec ce nombre de faces. Aucun remaillage ne s'exécute, et should_remesh n'est pas nécessaire.
La plage et la valeur par défaut dépendent du cas :
Cas Plage Par défaut
Remaillage 100 à 300000 30000
meshy-t2 100 à 15000 4000
meshy-t2.5 100 à 30000 15000
Une valeur hors plage renvoie 400.

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

Name
symmetry_mode
Type
string
⚠ obsolète
défaut auto
Description
Ne l'incluez pas, car il n'a aucun effet sur le résultat. 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
défaut ""
Description
La pose du modèle généré.
Valeurs disponibles :
- a-pose : une pose en A
- t-pose : une pose en T
- "" (chaîne vide) : aucune pose particulière
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. Il n'a aucun effet sur le résultat, car le mode de génération de modèle qu'il sélectionnait est retiré.
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 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 avec votre propre éclairage.
Cela ne prend effet qu'avec meshy-6. meshy-7.1 et latest l'acceptent et l'ignorent. Avec meshy-6-lite ou model_type: smart-topology, cela renvoie 400.
Name
moderation
Type
boolean
défaut false
Description
Indique s'il faut examiner ces entrées pour détecter un contenu nuisible avant la génération :
- image_url
- texture_image_url
- texture_prompt
Si Meshy détecte un contenu nuisible, la requête renvoie 400 et Meshy ne crée pas de tâche.
Name
target_formats
Type
string[]
Description
Les formats de 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 obtenez uniquement 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 rendre un aperçu avec un arrière-plan transparent (RGBA), renvoyé dans alpha_thumbnail_url lorsque vous récupérez la tâche. thumbnail_url ne change pas.
Name
multi_view_thumbnails
Type
boolean
défaut false
Description
Indique s'il faut aussi rendre 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 affiche toujours la vue avant. 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.

Retour

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 trouvé. Par exemple :
- Paramètre manquant : ni image_url ni input_task_id n'ont été envoyés.
- Tâche d'entrée invalide : input_task_id n'est pas une tâche Texte en image ou Image en image au 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 dépasse le délai d'attente.
- Image trop volumineuse : l'image image_url ou texture_image_url dépasse 20 Mo.
- 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 incapable de l'exécuter.
- Modèle non pris en charge pour les options d'image : image_enhancement ou remove_lighting a été envoyé avec ai_model: "meshy-6-lite" ou model_type: "smart-topology".
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.
- 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
404 - Not Found
Description
input_task_id ne correspond à aucune de vos tâches. Vérifiez l'ID de la tâche, puis envoyez la requête à nouveau.
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

Retourne 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": {
    "message": ""
  },
  "consumed_credits": 30
}

Paramètres

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

Retours

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 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 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": {
      "message": ""
    },
    "consumed_credits": 30
  }
]

Paramètres

Name
page_num
Type
integer
défaut 1
Description
Le numéro de page à renvoyer. Les pages commencent à 1.
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

Renvoie

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

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

Diffuser une tâche Image en 3D en flux

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": {
    "message": ""
  },
  "consumed_credits": 30
}

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 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 retourné 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": {
    "message": ""
  },
  "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 pour le modèle 3D généré, une par format de fichier. Un format que la tâche n'a pas généré n'a pas de clé, plutôt qu'une chaîne vide.
- Name
  glb
  Type
  string
  Description
  Le fichier GLB.
- Name
  fbx
  Type
  string
  Description
  Le fichier FBX.
- Name
  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 comporte 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
URL de téléchargement pour 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
URL de téléchargement pour une version de thumbnail_url avec un arrière-plan transparent (RGBA). Présent uniquement lorsque vous avez créé la tâche avec alpha_thumbnail: true et que Meshy a rendu l'aperçu transparent.
Name
thumbnail_urls
Type
object
Description
Les URL de téléchargement pour des aperçus du modèle 3D vus sous quatre angles. 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 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
URL de téléchargement pour 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 niveau Ultra sur 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 déjà accomplie, en pourcentage. Elle vaut 0 jusqu'au démarrage de la tâche et 100 lorsqu'elle réussit.
Name
started_at
Type
timestamp
Description
Heure de démarrage de la tâche, en millisecondes Unix. Elle vaut 0 jusqu'au démarrage de la tâche.
Name
created_at
Type
timestamp
Description
Heure de création de la tâche, en millisecondes Unix.
Name
expires_at
Type
timestamp
Description
Heure d'expiration du résultat de la tâche, en millisecondes Unix.
Name
finished_at
Type
timestamp
Description
Heure de fin de la tâche, en millisecondes Unix. Elle vaut 0 jusqu'à la fin de la tâche.
Name
status
Type
string
Description
Le statut de la tâche, l'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 les champs suivants :
- Name
  base_color
  Type
  string
  Description
  URL de téléchargement pour la carte de couleur de base.
- Name
  metallic
  Type
  string
  Description
  URL de téléchargement pour la carte métallique. Le champ est absent lorsque vous avez créé la tâche avec enable_pbr: false.
- Name
  normal
  Type
  string
  Description
  URL de téléchargement pour la normal map. Le champ est absent lorsque vous avez créé la tâche avec enable_pbr: false.
- Name
  roughness
  Type
  string
  Description
  URL de téléchargement pour la carte de rugosité. Le champ est absent lorsque vous avez créé la tâche avec enable_pbr: false.
- Name
  emission
  Type
  string
  Description
  URL de téléchargement pour la carte d'émission. Le champ est absent lorsque vous avez créé la tâche avec enable_pbr: false ou texture_resolution: 8k, ou lorsque ai_model est l'un des modèles suivants :
  
  meshy-6-lite
  
  meshy-7
  
  meshy-7.1
  
  meshy-t2
  
  meshy-t2.5
  
  latest
Name
preceding_tasks
Type
integer
Description
Le nombre de tâches qui précèdent celle-ci dans la file d'attente. La valeur n'est pertinente 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. Voir Erreurs.
Name
consumed_credits
Type
integer
Description
Le nombre de crédits consommés par la tâche. Présent lorsque le statut est PENDING, IN_PROGRESS, ou SUCCEEDED. Il vaut 0 pour une tâche FAILED, car Meshy rembourse les crédits lorsqu'une tâche échoue.