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 Redimensionner

Redimensionner un modèle 3D à une taille réelle, en mètres. Définissez sa hauteur ou la longueur de son côté le plus long, ou laissez Meshy estimer la hauteur réelle de l'objet.


POST/openapi/v1/resize

Créer une tâche de redimensionnement

Crée une tâche de redimensionnement. 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/resize
# Simple: resize to a specific height
curl https://api.meshy.ai/openapi/v1/resize \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "resize_height": 1.8
  }'

# Advanced: resize longest side with custom origin
curl https://api.meshy.ai/openapi/v1/resize \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "model_url": "https://example.com/model.glb",
    "resize_longest_side": 2.0,
    "origin_at": "center"
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

Paramètres

  • Name
    input_task_id
    Type
    string
    Requis
    Description

    Obligatoire sauf si vous envoyez model_url. L'ID d'une tâche ayant produit un modèle 3D, par exemple une tâche Texte en 3D, Image en 3D, Remaillage ou Retexturisation. La tâche doit provenir de l'API et avoir le statut SUCCEEDED. Meshy renvoie le modèle redimensionné sous forme de fichier GLB.

  • Name
    model_url
    Type
    string
    Requis
    Description

    Obligatoire sauf si vous envoyez input_task_id. Le modèle à redimensionner, sous forme d'URL publique ou de Data URI. Si vous envoyez les deux, Meshy utilise input_task_id.

    Le modèle doit être un fichier GLB, glTF, OBJ, FBX ou STL d'au plus 400 Mo provenant d'une URL http ou https, ou de 100 Mo au maximum sous forme de Data URI. Pour une Data URI, utilisez le MIME type application/octet-stream.

    Un fichier de plus de 100 Mo doit également respecter ces règles :

    • Un fichier GLB, glTF, FBX ou OBJ peut avoir au maximum 10 000 000 faces. Meshy compte les faces en triangles, donc un quadrilatère compte pour 2, et un maillage dessiné plusieurs fois compte une fois par copie.
    • Un fichier FBX doit être au format binaire FBX 7.1 ou plus récent.
    • Un fichier GLB ou glTF ne doit pas utiliser la compression Draco.

    Un fichier GLB, OBJ, FBX ou STL conserve son format dans le résultat. Un fichier .gltf ou une Data URI revient au format GLB.

Envoyez exactement un seul des paramètres resize_height, resize_longest_side ou auto_size. N'en envoyer aucun, ou en envoyer plusieurs, renvoie 400.

  • Name
    resize_height
    Type
    number
    Description

    La nouvelle hauteur du modèle en mètres, supérieure à 0. Une valeur négative renvoie 400.

  • Name
    resize_longest_side
    Type
    number
    Description

    La nouvelle longueur du côté le plus long du modèle en mètres, supérieure à 0. Une valeur négative renvoie 400. Meshy conserve le rapport d'aspect du modèle.

  • Name
    auto_size
    Type
    boolean
    Description

    Indique s'il faut estimer la hauteur réelle de l'objet grâce à la vision par IA et redimensionner le modèle en conséquence. Sauf si vous définissez origin_at, Meshy place l'origine en bas.

  • Name
    origin_at
    Type
    string
    défaut bottom
    Description

    Où placer l'origine du modèle après le redimensionnement, bottom ou center.

Retours

Le champ result de la réponse contient l'ID de la nouvelle tâche de redimensionnement.

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 model_url ni input_task_id n'ont été envoyés.
    • Mode de redimensionnement manquant : aucun des paramètres resize_height, resize_longest_side et auto_size n'a été envoyé.
    • Paramètres mutuellement exclusifs : la requête contient plus d'un des paramètres resize_height, resize_longest_side et auto_size. N'en envoyez qu'un seul.
    • Taille négative : resize_height ou resize_longest_side est négatif.
    • Tâche d'entrée invalide : input_task_id n'est pas une tâche API réussie contenant un fichier de modèle.
    • Format de modèle invalide : le fichier model_url a une extension non prise en charge.
    • URL inaccessible : Meshy ne peut pas télécharger le fichier model_url.
    • Fichier de modèle trop volumineux : le fichier model_url dépasse 400 Mo depuis une URL http ou https, ou dépasse 100 Mo en tant que Data URI.
    • Trop de faces : le fichier model_url dépasse 100 Mo et compte plus de 10 000 000 faces. Réduisez le nombre de faces, puis renvoyez le fichier.
    • FBX ASCII de plus de 100 Mo : le fichier model_url est un FBX ASCII dépassant 100 Mo. Envoyez-le au format FBX binaire ou GLB.
    • Fichier de modèle illisible : le fichier model_url dépasse 100 Mo, et Meshy ne peut pas lire son en-tête. Par exemple, il s'agit d'un GLB ou glTF compressé avec Draco, ou d'un FBX binaire antérieur à la version 7.1.
    • En-tête de modèle trop complexe : le fichier model_url dépasse 100 Mo, et son en-tête comporte trop de maillages, de nœuds ou d'enregistrements à vérifier. Réduisez le nombre d'objets dans le fichier, puis renvoyez-le.

    Corrigez la requête, puis renvoyez-la. 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 ne dispose pas de crédits suffisants pour cette tâche, ou le compte a atteint une limite de crédits. Vérifiez votre solde de crédits, puis réessayez.
    • Forfait gratuit : la création d'une tâche nécessite un forfait payant. Mettez à niveau votre forfait dans vos paramètres d'abonnement, puis réessayez.
  • Name
    403 - Forbidden
    Description

    input_task_id correspond à un modèle en bas-relief, que ce point de terminaison ne peut pas redimensionner. Le message est This model type does not support this operation. Envoyez un autre modèle.

  • Name
    404 - Not Found
    Description

    input_task_id ne correspond à aucune de vos tâches. Vérifiez l'ID de la tâche, puis renvoyez 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/resize/:id

Récupérer une tâche de redimensionnement

Renvoie une tâche de redimensionnement (Resize) par son ID.

Request

GET
/openapi/v1/resize/:id
curl https://api.meshy.ai/openapi/v1/resize/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "resize",
  "model_urls": {
      "glb": "https://assets.meshy.ai/.../model.glb?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}

Paramètres

  • Name
    id
    Type
    path
    Description

    L'ID de la tâche issu de la réponse de création.

Retourne

L'objet tâche de redimensionnement.


DELETE/openapi/v1/resize/:id

Supprimer une tâche de Redimensionnement

Supprime définitivement une tâche de Redimensionnement, y compris ses modèles et ses données. Vous ne pouvez pas annuler une suppression.

Request

DELETE
/openapi/v1/resize/:id
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/resize/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -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.

Retourne

200 OK lorsque la tâche est supprimée, ou 409 Conflict lorsque la tâche est IN_PROGRESS.


GET/openapi/v1/resize

Lister les tâches de redimensionnement

Renvoie une liste de vos tâches de Redimensionnement.

Request

GET
/openapi/v1/resize
curl https://api.meshy.ai/openapi/v1/resize?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "resize",
    "model_urls": {
      "glb": "https://assets.meshy.ai/.../model.glb?Expires=..."
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null,
    "consumed_credits": 1
  }
]

Paramètres

  • Name
    page_num
    Type
    integer
    défaut 1
    Description

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

  • Name
    page_size
    Type
    integer
    défaut 10
    Description

    Le nombre de tâches par page, jusqu'à 100.

  • Name
    sort_by
    Type
    string
    Description

    L'ordre de tri.

    Valeurs disponibles :

    • +created_at : 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 de redimensionnement.


GET/openapi/v1/resize/:id/stream

Diffuser les mises à jour d'une tâche Resize

Diffuse les mises à jour d'une tâche Resize sous forme d'événements envoyés par le serveur (SSE).

Request

GET
/openapi/v1/resize/:id/stream
curl -N https://api.meshy.ai/openapi/v1/resize/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Message event examples illustrate task progress.
event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "resize",
  "model_urls": {
    "glb": "https://assets.meshy.ai/.../model.glb?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}

Paramètres

  • Name
    id
    Type
    path
    Description

    L'ID de la tâche provenant de la réponse de création.

Retour

Un flux d'objets de tâche Resize 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.


The Resize task object

Un objet de tâche Resize décrit un redimensionnement d'un modèle 3D. Il contient le statut, la progression et le fichier du modèle lorsque la tâche réussit.

Properties

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

  • Name
    model_urls
    Type
    object
    Description

    URL de téléchargement du fichier du modèle redimensionné. Pour input_task_id, le fichier est toujours au format GLB. Pour model_url, un fichier GLB, OBJ, FBX ou STL conserve son format, et un fichier .gltf ou une Data URI revient au format GLB.

  • Name
    progress
    Type
    integer
    Description

    La part de la tâche réalisée, exprimée en pourcentage. Elle vaut 0 tant que la tâche n'a pas commencé et 100 lorsqu'elle réussit.

  • Name
    status
    Type
    string
    Description

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

  • Name
    preceding_tasks
    Type
    integer
    Description

    Le nombre de tâches devançant celle-ci dans la file d'attente. La valeur n'est pertinente que tant que la tâche est PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

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

  • Name
    started_at
    Type
    timestamp
    Description

    Heure de démarrage de la tâche, en millisecondes Unix. Elle vaut 0 tant que la tâche n'a pas démarré.

  • Name
    finished_at
    Type
    timestamp
    Description

    Heure de fin de la tâche, en millisecondes Unix. Elle vaut 0 tant que la tâche n'est pas terminée.

  • Name
    expires_at
    Type
    timestamp
    Description

    Heure d'expiration des URL de téléchargement de la tâche, en millisecondes Unix. Elle vaut 0 tant que la tâche n'est pas terminée.

  • Name
    texture_urls
    Type
    array
    Description

    URL de téléchargement des textures du modèle, lorsque la tâche réussit : un tableau d'objets, un par jeu de textures. Chaque objet comporte une URL base_color, et peut également avoir des URL metallic, roughness, normal, emission et metallic_roughness. Elle vaut null tant que la tâche n'a pas réussi, et un tableau vide lorsque le modèle n'a pas de textures.

  • 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, qui est 1 pour une tâche Resize. Il vaut 0 pour une tâche FAILED.