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.
Créer une tâche de Conversion
Crée une tâche de Conversion. 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
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
Requis 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, Redimensionner ou Retexturisation. La tâche doit provenir de l'API et avoir le statutSUCCEEDED.
- Name
- model_url
- Type
- string
- Requis
- Description
Requis 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 utiliseinput_task_id.Le modèle doit être un fichier GLB, glTF, OBJ, FBX ou STL d'au plus 400 Mo provenant d'une URL
httpouhttps, ou de 100 Mo au maximum en tant que Data URI. Pour un Data URI, utilisez le MIME typeapplication/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.
- Name
- target_formats
- Type
- string[]
- Requis
- Description
Les formats de fichier à générer. Indiquez-en au moins un. Une liste manquante ou vide renvoie
400.Valeurs disponibles :
glbfbxobjusdzblendstl3mf
Retours
Le champ result de la réponse contient l'ID de la nouvelle tâche de Conversion.
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_urlniinput_task_idn'ont été envoyés. target_formatsmanquant :target_formatsest manquant ou ne contient aucun format.- Tâche d'entrée invalide :
input_task_idn'est pas une tâche API réussie contenant un fichier modèle. - Format de modèle invalide : le fichier
model_urla une extension non prise en charge. - URL inaccessible : Meshy ne peut pas télécharger le fichier
model_url. - Fichier modèle trop volumineux : le fichier
model_urldépasse 400 Mo depuis une URLhttpouhttps, ou dépasse 100 Mo en tant que Data URI. - Trop de faces : le fichier
model_urldé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_urlest un FBX ASCII de plus de 100 Mo. Envoyez-le au format FBX binaire ou GLB. - Fichier modèle illisible : le fichier
model_urldé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_urldé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.
- Paramètre manquant : ni
- 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 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 vos paramètres d'abonnement, puis réessayez.
- Name
403 - Forbidden- Description
input_task_idcorrespond à un modèle en bas-relief, que ce point de terminaison ne peut pas convertir. Le message estThis model type does not support this operation. Envoyez un modèle différent.
- Name
404 - Not Found- Description
input_task_idne 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. Attendez, puis réessayez. Consultez Limites de débit.
Récupérer une tâche Convert
Renvoie une tâche Convert à partir de son ID.
Request
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
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
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.
Lister les tâches de conversion
Renvoie une liste de vos tâches de conversion.
Request
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, jusqu'à
255. Une valeur plus élevée renvoie400.
- 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 conversion.
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
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 Convert
Un objet de tâche Convert 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_formatsont 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 déjà effectuée, en pourcentage. Elle vaut
0jusqu'à ce que la tâche démarre et100lorsqu'elle réussit.
- Name
- status
- Type
- string
- Description
Le statut de la tâche, l'un de
PENDING,IN_PROGRESS,SUCCEEDED,FAILED, ouCANCELED.
- 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 significative que tant que la tâche est
PENDING.
- Name
- created_at
- Type
- timestamp
- Description
L'heure de création de la tâche, en millisecondes Unix.
- Name
- started_at
- Type
- timestamp
- Description
L'heure de démarrage de la tâche, en millisecondes Unix. Elle vaut
0jusqu'à ce que la tâche démarre.
- Name
- finished_at
- Type
- timestamp
- Description
L'heure de fin de la tâche, en millisecondes Unix. Elle vaut
0jusqu'à ce que la tâche se termine.
- Name
- expires_at
- Type
- timestamp
- Description
L'heure d'expiration des URLs de téléchargement de la tâche, en millisecondes Unix. Elle vaut
0jusqu'à ce que la tâche se termine.
- Name
- texture_urls
- Type
- array
- Description
Les URLs de téléchargement pour les cartes de texture du modèle, lorsque la tâche réussit : un tableau d'objets, un par ensemble de textures. Chaque objet a une URL
base_color, et peut également avoir des URLsmetallic,roughness,normal,emission, etmetallic_roughness. Elle vautnulljusqu'à ce que la tâche réussisse, et un tableau vide lorsque le modèle n'a pas de cartes de texture.
- 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
1pour une tâche Convert. Il vaut0pour une tâcheFAILED.