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 Convertir

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

Paramètres

Un seul des deux, input_task_id ou model_url, est requis. Si les deux sont fournis, input_task_id prend 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 accessible publiquement ou une Data URI pointant vers un fichier de modèle 3D. Formats pris en charge : .glb, .gltf, .obj, .fbx, .stl. Pour les Data URIs, utilisez le MIME type : application/octet-stream.

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 : Le input_task_id doit faire référence à une tâche réussie.
Format de modèle invalide : Le model_url pointe vers un fichier avec une extension non prise en charge.
URL inaccessible : Le model_url n’a pas pu être téléchargé.

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 Convertir

Ce point de terminaison récupère une tâche Convertir par son ID.

Paramètres

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

Retours

L’objet Tâche Convertir.

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 Convertir

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

Paramètres de chemin

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

Retours

Retourne 200 OK en cas de succès.

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

// Returns 200 Ok on success.

GET/openapi/v1/convert

Lister les tâches Convertir

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

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 50 éléments.

Name
sort_by
Type
string
Description
Champ selon lequel trier. Valeurs disponibles :
- +created_at: Trier par heure de création dans l’ordre croissant.
- -created_at: Trier par heure de création dans l’ordre décroissant.

Retours

Renvoie une liste paginée des objets de tâche Convertir.

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 une tâche Convertir

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

Paramètres

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

Retours

Renvoie un flux des objets de tâche Convertir sous forme de Server-Sent Events.

Pour les tâches PENDING ou IN_PROGRESS, le flux de réponse inclura uniquement 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 de tâche Convertir

L’objet de tâche Convertir représente une tâche 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

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

progress · integer

Progression 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. Significatif uniquement lorsque le statut est PENDING.

created_at · horodatage

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

started_at · horodatage

Horodatage du démarrage de la tâche, en millisecondes. 0 si elle n’a pas démarré.

finished_at · horodatage

Horodatage de la fin de la tâche, en millisecondes. 0 si elle n’est pas 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.