API de conversion

Convertir un modèle 3D vers d'autres formats de fichier, à partir d'une tâche Meshy ou d'un fichier de modèle.

POST/openapi/v1/convert

Créer une tâche de conversion

Crée une tâche de Convert. 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/convert

curl https://api.meshy.ai/openapi/v1/convert \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["fbx", "stl"]
  }'

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 de la tâche Meshy dont vous voulez convertir le modèle. La tâche doit avoir le statut SUCCEEDED.

Name
model_url
Type
string
Requis
Description
Obligatoire sauf si vous envoyez input_task_id. Le modèle à convertir, 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 pour un Data URI. Pour un Data URI, utilisez le MIME type application/octet-stream.
Un fichier de plus de 100 Mo doit également respecter les règles suivantes :
- Un fichier GLB, glTF, FBX ou OBJ peut avoir au maximum 10 000 000 faces. Meshy compte les faces en triangles : un quadrilatère compte donc 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.

Name
target_formats
Type
string[]
Requis
Description
Les formats de fichiers à générer. Indiquez-en au moins un. Une liste manquante ou vide renvoie 400.
Valeurs disponibles :
- glb
- fbx
- obj
- usdz
- blend
- stl
- 3mf

Valeurs renvoyées

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

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.
- target_formats manquant : target_formats est absent ou ne liste aucun format.
- Tâche d'entrée invalide : input_task_id n'est 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 tant que 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 contient 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 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 offre 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 convertir. 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/convert/:id

Récupérer une tâche Convert

Renvoie une tâche Convert à partir de son ID.

Request

GET

/openapi/v1/convert/:id

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "convert",
  "model_urls": {
      "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
      "stl": "https://assets.meshy.ai/.../model.stl?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.

Retours

L'objet tâche Convert.

DELETE/openapi/v1/convert/:id

Supprimer une tâche Convert

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

Request

DELETE

/openapi/v1/convert/:id

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/convert/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 déjà démarrée, 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.

GET/openapi/v1/convert

List Convert tasks

Renvoie une liste de vos tâches Convert.

Request

GET

/openapi/v1/convert

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "convert",
    "model_urls": {
      "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
      "stl": "https://assets.meshy.ai/.../model.stl?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 de tâche Convert.

GET/openapi/v1/convert/:id/stream

Diffuser un task Convertir sous forme de flux

Diffuse les mises à jour d'un task Convertir sous forme d'événements envoyés par le serveur (SSE).

Request

GET

/openapi/v1/convert/:id/stream

curl -N https://api.meshy.ai/openapi/v1/convert/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": "convert",
  "model_urls": {
    "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
    "stl": "https://assets.meshy.ai/.../model.stl?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 du task provenant de la réponse de création.

Retours

Un flux d'objets task Convertir sous forme d'événements envoyés par le serveur.

Chaque événement contient l'objet task complet, dans le même format que celui renvoyé par le point de terminaison Get. Tant que le task est PENDING ou IN_PROGRESS, ses champs de résultat n'ont pas encore de valeurs.

L'objet de tâche Convertir

Un objet de tâche Convertir décrit une conversion de format d'un modèle 3D. Il contient le statut, la progression, et les fichiers 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 convert.
Name
model_urls
Type
object
Description
Les URLs de téléchargement pour le modèle converti, une par format de fichier. Seuls les formats présents dans target_formats ont des URLs. Un format que vous n'avez pas demandé n'a pas de clé, plutôt qu'une chaîne vide.
Name
progress
Type
integer
Description
La part de la tâche réalisée, en pourcentage. C'est 0 jusqu'à ce que la tâche démarre et 100 quand 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 qui précèdent celle-ci dans la file d'attente. Cette valeur n'est pertinente que lorsque 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 lorsque la tâche échoue. 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 Convertir. C'est 0 pour une tâche FAILED.