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 Redimensionner

Crée une tâche Redimensionner. 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
Requis sauf si vous envoyez model_url. L'ID de la tâche Meshy dont vous souhaitez redimensionner le modèle. La tâche doit avoir le statut SUCCEEDED. Meshy renvoie le modèle redimensionné sous forme de fichier GLB.

Name
model_url
Type
string
Requis
Description
Requis 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 depuis une URL http ou https, ou de 100 Mo en 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 plus 10 000 000 faces. Meshy compte les faces en triangles, donc un quad compte pour 2, et un maillage dessiné plusieurs fois compte une fois par copie.
- Un fichier FBX doit être un FBX binaire 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 est renvoyé au format GLB.

Envoyez exactement un seul des paramètres resize_height, resize_longest_side ou auto_size. N'en envoyer aucun, ou plus d'un, 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 Redimensionner.

Modes d'échec

Name
400 - Bad Request
Description
La requête ne peut pas s'exécuter. Le message d'erreur indique quel problème a été détecté. Par exemple :
- Paramètre manquant : 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 ne correspond pas à une tâche réussie.
- 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 Data URI.
- Trop de faces : le fichier model_url dépasse 100 Mo et comporte 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 de plus de 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 n'a pas suffisamment de crédits pour cette tâche, ou le compte a atteint une limite de crédits. Vérifiez votre solde de crédits, puis réessayez.
- Plan gratuit : la création d'une tâche nécessite un plan payant. Mettez à niveau votre plan dans les 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 modèle différent.
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.

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

L'objet de tâche Resize

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.

Propriétés

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 est renvoyé au format GLB.
Name
progress
Type
integer
Description
La part de la tâche déjà effectuée, en pourcentage. C'est 0 jusqu'à ce que la tâche démarre et 100 lorsqu'elle réussit.
Name
status
Type
string
Description
Le statut de la tâche, l'une des valeurs PENDING, IN_PROGRESS, SUCCEEDED, FAILED ou CANCELED.
Name
preceding_tasks
Type
integer
Description
Le nombre de tâches qui précèdent celle-ci dans la file d'attente. Cette valeur n'a de sens que 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. C'est 0 jusqu'à ce que la tâche démarre.
Name
finished_at
Type
timestamp
Description
Heure de fin de la tâche, en millisecondes Unix. C'est 0 jusqu'à ce que la tâche se termine.
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 utilisés par la tâche, qui est 1 pour une tâche Resize. C'est 0 pour une tâche FAILED.