API Convertir

L'API Convertir vous permet de convertir des modèles 3D existants dans différents formats de fichiers.

POST/openapi/v1/convert

Créer une tâche de conversion

Ce point de terminaison crée une nouvelle tâche de conversion de format.

La tâche s'exécute en arrière-plan. Pour connaître la durée habituelle, consultez Temps de traitement.

Paramètres

Seul l'un des paramètres input_task_id ou model_url est requis. Si les deux sont fournis, input_task_id a la priorité.

Name
input_task_id
Type
string
Requis
Description
L'ID d'une tâche Meshy terminée dont vous souhaitez convertir le modèle. La tâche doit avoir le statut SUCCEEDED.

Name
model_url
Type
string
Requis
Description
Une URL publiquement accessible ou une Data URI pointant vers un fichier de modèle 3D. Formats pris en charge : .glb, .gltf, .obj, .fbx, .stl. Pour les Data URI, utilisez le MIME type : application/octet-stream.
Taille de fichier maximale : 100 Mo.

Name
target_formats
Type
string[]
Requis
Description
Une liste de formats de sortie pour le modèle converti. Valeurs disponibles : glb, fbx, obj, usdz, blend, stl, 3mf.

Retours

La propriété result de la réponse contient l'id de la tâche de conversion nouvellement créée.

Modes d'échec

400 - Bad Request

La requête était inacceptable. Causes courantes :

Paramètre manquant : model_url ou input_task_id doit être fourni.
target_formats manquant : au moins un format cible doit être spécifié.
Tâche d'entrée invalide : input_task_id doit faire référence à une tâche réussie.
Format de modèle invalide : model_url pointe vers un fichier avec une extension non prise en charge.
URL inaccessible : model_url n'a pas pu être téléchargé.
Fichier de modèle trop volumineux : le fichier model_url dépasse 100 Mo.

401 - Unauthorized

L'authentification a échoué. Veuillez vérifier votre clé API.

402 - Payment Required

Crédits insuffisants pour effectuer cette tâche.

429 - Too Many Requests

Vous avez dépassé votre limite de débit.

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"
}

GET/openapi/v1/convert/:id

Récupérer une tâche de conversion

Ce point de terminaison récupère une tâche de conversion à partir de son ID.

Paramètres

Name
id
Type
path
Description
L'ID de la tâche de conversion à récupérer.

Retour

L'objet Tâche de conversion.

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": {
      "glb": "",
      "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
      "obj": "",
      "usdz": "",
      "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
}

DELETE/openapi/v1/convert/:id

Supprimer une tâche de conversion

Ce point de terminaison supprime définitivement une tâche de conversion, y compris tous les modèles et données associés. Cette action est irréversible.

Paramètres de chemin

Name
id
Type
path
Description
L'ID de la tâche de conversion à supprimer.

Statut de la tâche

Une tâche encore PENDING est supprimée et les crédits consommés au moment de la création sont remboursés.

Une tâche déjà IN_PROGRESS ne peut pas être supprimée : la requête est rejetée avec 409 Conflict et la tâche continue de s'exécuter. Les crédits d'une tâche que le worker a déjà commencée ne sont pas remboursables, donc la supprimer en cours d'exécution vous ferait perdre à la fois les crédits et le résultat. Attendez qu'elle atteigne SUCCEEDED, FAILED ou CANCELED, puis supprimez-la.

Une tâche dans un état final (SUCCEEDED, FAILED ou CANCELED) est supprimée sans remboursement.

Retourne

Retourne 200 OK en cas de succès, ou 409 Conflict lorsque la tâche est IN_PROGRESS.

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 is left 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."
}

GET/openapi/v1/convert

Liste des tâches de conversion

Ce point de terminaison vous permet de récupérer une liste de tâches de conversion.

Paramètres

Name
page_num
Type
integer
défaut 1
Description
Numéro de page pour la pagination.

Name
page_size
Type
integer
défaut 10
Description
Limite de taille de page. Le maximum autorisé est de 100 éléments.

Name
sort_by
Type
string
Description
Champ à utiliser pour le tri. Valeurs disponibles :
- +created_at : Trier par heure de création par ordre croissant.
- -created_at : Trier par heure de création par ordre décroissant.

Retours

Retourne une liste paginée d'Objets de tâche de conversion.

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
  }
]

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

Diffuser en continu une tâche de conversion

Ce point de terminaison diffuse en continu les mises à jour en temps réel d'une tâche de conversion à l'aide des Server-Sent Events (SSE).

Paramètres

Name
id
Type
path
Description
Identifiant unique de la tâche de conversion à diffuser.

Retours

Renvoie un flux d'Objets de tâche de conversion sous forme de Server-Sent Events.

Pour les tâches PENDING ou IN_PROGRESS, le flux de réponse n'inclura que les champs progress et status nécessaires.

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
}

L'objet Tâche de conversion

L'objet Tâche de conversion représente un travail de conversion de format.

Propriétés

id · string

Identifiant unique de la tâche.

type · string

Type de la tâche. La valeur est convert.

model_urls · object

URLs de téléchargement pour les fichiers du modèle converti. Seuls les formats spécifiés dans target_formats auront des URLs. Les autres propriétés de format seront des chaînes vides.

progress · integer

progress de la tâche (0-100).

status · string

Statut de la tâche. Valeurs possibles : PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

preceding_tasks · integer

Le nombre de tâches précédentes. Pertinent uniquement lorsque le statut est PENDING.

created_at · timestamp

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

started_at · timestamp

horodatage du démarrage de la tâche, en millisecondes. 0 si non démarrée.

finished_at · timestamp

horodatage de la fin de la tâche, en millisecondes. 0 si non terminée.

task_error · object

Objet d'erreur si la tâche a échoué. Voir Erreurs pour plus de détails.

consumed_credits · integer

Le nombre de crédits consommés par cette tâche (1 crédit par tâche de conversion). Renvoie 0 pour les tâches FAILED.