Transformez une photo source en une minifigurine 3D de style brique en deux étapes :
prototype génère une image conceptuelle stylée à partir de votre photo d'entrée, puis
construct transforme cette image conceptuelle en un modèle 3D avec texture. Les deux étapes
sont liées via input_task_id.
POST /openapi/creative-lab/brick-figure/v1/prototype
Générer une image conceptuelle unique de style brique à partir de la photo source. L'ID de tâche retourné est celui que vous passez comme input_task_id au point de terminaison de construction. Référez-vous à L'objet de la tâche de prototype de figurine en briques pour la forme de la réponse.
Paramètres
Name
image_url
Type
string
Requis
Description
Photo source pour que Meshy la stylise en tant que figurine en brique. Nous supportons actuellement les formats .jpg, .jpeg, .png, et .webp.
Il y a deux façons de fournir l'image :
URL accessible publiquement : Une URL accessible depuis l'internet public.
Data URI : Un Data URI encodé en base64 de l'image. Exemple de Data URI: data:image/jpeg;base64,<your base64-encoded image data>.
Name
name
Type
string
Description
Nom de la tâche facultatif à des fins d'affichage. Maximum 100 caractères.
Retours
La propriété result de la réponse contient l'ID de la tâche id de la nouvelle tâche de prototype de figurine en briques. Interrogez le Récupérer une tâche point de terminaison ou abonnez-vous au flux jusqu'à ce que la tâche atteigne SUCCEEDED, puis passez cet ID au point de terminaison de construction comme input_task_id.
Modes d'échec
Name
400 - Bad Request
Description
La demande était inacceptable. Causes courantes :
Paramètre manquant : image_url est requis.
Format d'image invalide : Le image_url fourni n'est pas un format supporté (.jpg, .jpeg, .png, .webp).
Dimensions de l'image hors plage : L'image est trop petite, dépasse la taille de fichier maximale, ou dépasse le nombre maximal de pixels.
URL inaccessible : Le image_url n'a pas pu être téléchargé (404 ou timeout).
Data URI invalide : La chaîne en base64 est mal formée.
Contenu signalé : L'image d'entrée a été signalée par la modération NSFW ou de propriété intellectuelle.
Name
401 - Unauthorized
Description
L'authentification a échoué. Veuillez vérifier votre clé API.
Name
402 - Payment Required
Description
Crédits insuffisants pour effectuer cette tâche.
Name
403 - Forbidden
Description
L'image d'entrée a été signalée pour violation de propriété intellectuelle.
Name
429 - Too Many Requests
Description
Vous avez dépassé votre limite de débit.
Request
POST
/openapi/creative-lab/brick-figure/v1/prototype
# Étape 1 : générer une image conceptuelle de style briquecurl https://api.meshy.ai/openapi/creative-lab/brick-figure/v1/prototype \ -X POST \ -H "Authorization: Bearer ${YOUR_API_KEY}" \ -H 'Content-Type: application/json' \ -d '{ "image_url": "<your publicly accessible image url or base64-encoded data URI>" }'
Générer la figurine finale en 3D texturée à partir d'une tâche prototype réussie.
La construction utilise le même pipeline image-en-3D que
Image en 3D, donc le format de l'objet de réponse et la
liste des URLs de sortie correspondent exactement. Consultez
L'Objet de la Tâche de Construction de Figurine en Briques pour connaître la forme de la réponse.
Paramètres
Name
input_task_id
Type
string
Requis
Description
L'ID de la tâche prototype créée via ce même point de terminaison OpenAPI. Le prototype doit avoir été créé avec la même clé API, doit avoir atteint SUCCEEDED, et doit avoir produit exactement une image candidate.
Les tâches prototypes créées via l'application web ne sont pas acceptées — le point de terminaison de construction n'accepte que les tâches prototypes produites par POST /openapi/creative-lab/brick-figure/v1/prototype et refuse toute autre source avec 404.
Name
name
Type
string
Description
Nom de tâche optionnel à des fins d'affichage. Maximum 100 caractères.
Retours
La propriété result de la réponse contient l'id de la nouvelle tâche de construction de figurine en briques créée. Sondez le point de terminaison Obtenir une Tâche ou abonnez-vous au flux jusqu'à ce que la tâche atteigne SUCCEEDED, puis téléchargez le GLB texturé depuis model_urls.glb (ou la paire OBJ + MTL depuis model_urls.obj et model_urls.mtl si votre pipeline aval préfère OBJ).
Modes d'échec
Name
400 - Bad Request
Description
La requête était inacceptable. Causes courantes:
Paramètre manquant : input_task_id est requis.
UUID invalide : Le input_task_id n'est pas un UUID valide.
Parent non réussi : La tâche prototype référencée n'a pas encore atteint SUCCEEDED.
Aucun candidat : La tâche prototype a réussi mais n'a produit aucune image candidate.
Name
401 - Unauthorized
Description
L'authentification a échoué. Veuillez vérifier votre clé API.
Name
402 - Payment Required
Description
Crédits insuffisants pour effectuer cette tâche.
Name
404 - Not Found
Description
La tâche prototype référencée n'existe pas, appartient à un utilisateur différent, ou a été créée via l'application web (seules les tâches prototypes en mode API se connectent à la construction).
Name
429 - Too Many Requests
Description
Vous avez dépassé votre limite de débit.
Requête
POST
/openapi/creative-lab/brick-figure/v1/build
# Étape 2: enchaînez la construction à partir d'une tâche prototype réussiecurl https://api.meshy.ai/openapi/creative-lab/brick-figure/v1/build \ -X POST \ -H "Authorization: Bearer ${YOUR_API_KEY}" \ -H 'Content-Type: application/json' \ -d '{ "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578" }'
Récupérer une tâche de prototype ou de construction donnée avec un id de tâche valide. Le chemin d'URL
doit correspondre à l'étape de la tâche — une tâche de construction récupérée via
/prototype/:id retourne 404, et inversement.
Annuler une tâche de figurine en briques. Si la tâche est toujours PENDING, les crédits
consommés lors de la création sont remboursés. Les tâches qui sont déjà
IN_PROGRESS sont annulées sans remboursement (le travailleur peut déjà être
en train de consommer des ressources). Les tâches qui ont déjà atteint un état final
(SUCCEEDED, FAILED, CANCELED) ne peuvent pas être annulées.
Le chemin URL doit correspondre à l'étape de la tâche — DELETE sur
/prototype/:buildId renvoie 404.
Paramètres du chemin
Name
id
Type
path
Description
Identifiant unique pour la tâche de figurine en briques à annuler.
Retours
Retourne 204 No Content en cas de succès avec un corps vide.
Modes d'échec
Name
400 - Bad Request
Description
La tâche est déjà dans un état final et ne peut pas être annulée.
Name
404 - Not Found
Description
La tâche n'existe pas, appartient à un autre utilisateur, ou son étape ne correspond pas au chemin URL.
Diffusez des mises à jour en temps réel pour une tâche de figurine en briques via Server-Sent Events (SSE).
Le chemin de l'URL doit correspondre à l'étape de la tâche — ouvrir un flux à
/prototype/:buildId/stream émet une seule event: error charge utile avec
status_code: 404 et ferme le flux.
Paramètres
Name
id
Type
path
Description
Identifiant unique pour la tâche de figurine en briques à diffuser.
// Exemple d'événement d'erreur (mauvaise étape ou tâche non trouvée)event: errordata: {"status_code": 404,"message": "Task not found"}// Les exemples d'événements de message illustrent la progression de la tâche.// Pour les tâches PENDING ou IN_PROGRESS, le flux de réponse n'inclura pas tous les champs.event: messagedata: {"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb","progress": 0,"status": "PENDING"}event: messagedata: {"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb","type": "creative-lab-brick-figure-build","status": "SUCCEEDED","progress": 100,"created_at": 1729123500000,"started_at": 1729123510000,"finished_at": 1729123535000,"expires_at": 1729382735000,"task_error": null,"consumed_credits": 30,"prompt": "","negative_prompt": "","texture_prompt": "","texture_image_url": "","model_urls": {"glb":"https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***","obj":"https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.obj?Expires=***","mtl":"https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.mtl?Expires=***" },"thumbnail_url": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/preview.png?Expires=***","texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/texture_0.png?Expires=***" } ]}
Récupérez une liste paginée de vos tâches de figurines brick pour un seul stade. Le chemin URL
sélectionne le stade — /prototype retourne les tâches de prototype ; /build
retourne les tâches de construction. Les tâches de l'autre stade ne sont pas incluses dans l'une ou l'autre
réponse.
Paramètres de Chemin
Name
stage
Type
path
Requis
Description
Soit prototype soit build. La collection retourne uniquement les tâches
dont le stade correspond à l'URL — récupérer /prototype ne retourne jamais
des tâches de construction et vice versa.
Paramètres de Requête
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
défaut -created_at
Description
Champ pour trier. Valeurs disponibles :
+created_at: Trier par date de création en ordre croissant.
-created_at: Trier par date de création en ordre décroissant.
L'objet de tâche Prototype de la Figurine en Brique est une unité de travail que Meshy suit pour générer une image concept de style brique à partir d'une photo source. La sortie de cette étape est enchaînée dans l'étape de construction via input_task_id.
Propriétés
Name
id
Type
string
Description
Identifiant unique pour la tâche. Bien que nous utilisions un UUID triable par k pour les identifiants des tâches en tant que détail d'implémentation, vous ne devriez pas faire d'hypothèses sur le format de l'identifiant.
Name
type
Type
string
Description
Type de la tâche. La valeur est creative-lab-brick-figure-prototype.
Name
name
Type
string
Description
Le nom de la tâche fourni lors de la création de la tâche. Chaîne vide si aucun nom n'a été fourni.
Name
status
Type
string
Description
Statut de la tâche. Les valeurs possibles sont PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progression de la tâche. Si la tâche n'est pas encore commencée, cette propriété sera 0. Une fois la tâche réussie, cela deviendra 100.
Name
created_at
Type
timestamp
Description
Horodatage du moment où la tâche a été créée, en millisecondes.
Un horodatage représente le nombre de millisecondes écoulées depuis le 1er janvier 1970 UTC, suivant
la norme RFC 3339. Par exemple, le vendredi 1 septembre 2023 à 12:00:00 PM GMT est représenté par 1693569600000. Cela s'applique
à tous les horodatages dans Meshy API.
Name
started_at
Type
timestamp
Description
Horodatage du moment où la tâche a été démarrée, en millisecondes. Si la tâche n'est pas encore commencée, cette propriété sera null.
Name
finished_at
Type
timestamp
Description
Horodatage du moment où la tâche a été terminée, en millisecondes. Si la tâche n'est pas encore terminée, cette propriété sera null.
Name
expires_at
Type
timestamp
Description
Horodatage du moment où le résultat de la tâche expire, en millisecondes.
Name
preceding_tasks
Type
integer
Description
Le nombre de tâches précédentes.
La valeur de ce champ est pertinente uniquement si le statut de la tâche est PENDING.
Name
task_error
Type
object
Description
Détails des erreurs pour les tâches échouées. Voir Erreurs pour la référence complète de l'objet task_error.
Name
consumed_credits
Type
integer
Description
Le nombre de crédits consommés par cette tâche. Présent lorsque le statut de la tâche est PENDING, IN_PROGRESS, ou SUCCEEDED. Retourne 0 pour les tâches FAILED (les crédits sont remboursés en cas d'échec).
Name
image_urls
Type
array of strings
Description
URLs téléchargeables pour les candidats image concept générés par cette tâche prototype. Actuellement, l'API retourne toujours exactement un candidat ; le champ est un tableau pour permettre à de futures révisions d'afficher plusieurs candidats sans changement perturbateur.
L'objet Tâche de Construction de la Figurine en Brique est une unité de travail que Meshy suit pour générer une figurine en brique 3D avec texture à partir d'une tâche prototype SUCCEEDED. Il utilise le même pipeline image-en-3D que celui utilisé par Image en 3D, donc les champs de sortie reflètent les objet de la tâche de ce point de terminaison.
Propriétés
Name
id
Type
string
Description
Identifiant unique pour la tâche.
Name
type
Type
string
Description
Type de la tâche. La valeur est creative-lab-brick-figure-build.
Name
name
Type
string
Description
Le nom de la tâche fourni lors de sa création. Chaîne vide si aucun nom n'a été fourni.
Name
status
Type
string
Description
Statut de la tâche. Les valeurs possibles sont PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progression de la tâche. Si la tâche n'a pas encore commencé, cette propriété sera 0. Une fois la tâche terminée avec succès, cela deviendra 100.
Name
created_at
Type
timestamp
Description
Horodatage de la création de la tâche, en millisecondes.
Name
started_at
Type
timestamp
Description
Horodatage du début de la tâche, en millisecondes.
Name
finished_at
Type
timestamp
Description
Horodatage de la fin de la tâche, en millisecondes.
Name
expires_at
Type
timestamp
Description
Horodatage de l'expiration du résultat de la tâche, en millisecondes.
Name
preceding_tasks
Type
integer
Description
Le nombre de tâches précédentes. Pertinent uniquement lorsque le statut est PENDING.
Name
task_error
Type
object
Description
Détails de l'erreur pour les tâches échouées. Voir Erreurs pour la référence complète de l'objet task_error.
Name
consumed_credits
Type
integer
Description
Le nombre de crédits consommés par cette tâche. Retourne 0 pour les tâches FAILED (les crédits sont remboursés en cas d'échec).
Name
prompt
Type
string
Description
Toujours vide pour la construction de figurine en briques. Présent pour la compatibilité inter-point de terminaison avec la forme partagée V2ImageTo3DTaskResponse utilisée par Image en 3D.
Name
negative_prompt
Type
string
Description
Toujours vide pour la construction de figurine en briques. Présent pour la compatibilité inter-point de terminaison.
Name
texture_prompt
Type
string
Description
Toujours vide pour la construction de figurine en briques. Présent pour la compatibilité inter-point de terminaison.
Name
texture_image_url
Type
string
Description
Toujours vide pour la construction de figurine en briques. Présent pour la compatibilité inter-point de terminaison.
Name
model_urls
Type
object
Description
URL téléchargeables pour le modèle 3D généré. La construction de figurine en briques génère un GLB texturé plus la paire OBJ + MTL pour les pipelines qui préfèrent le Wavefront OBJ. La forme du champ correspond à celle de l'objet Image en 3D model_urls afin que les ajouts de formats futurs puissent s'intégrer sans changement majeur.
Name
glb
Type
string
Description
URL téléchargeable vers le fichier GLB texturé.
Name
obj
Type
string
Description
URL téléchargeable vers le fichier Wavefront OBJ (géométrie + UV).
Name
mtl
Type
string
Description
URL téléchargeable vers le fichier matériel compagnon MTL de l'OBJ. À associer avec obj et l'entrée de texture_urls[0].base_color.
Name
thumbnail_url
Type
string
Description
URL téléchargeable vers l'image miniature du fichier modèle.
Name
texture_urls
Type
array
Description
Un tableau d'objets URL de texture générés par cette tâche. Contient actuellement un seul objet avec la carte de couleur de base.
Name
base_color
Type
string
Description
URL téléchargeable vers l'image de la carte de couleur de base.