Transformez une photo source en une figurine 3D vinyle à grosse tête, à collectionner, en deux
étapes : prototype génère une image conceptuelle stylisée à partir de votre
photo d'entrée, puis build transforme cette image conceptuelle en un modèle 3D texturé.
Les deux étapes sont liées via input_task_id.
POST /openapi/creative-lab/vinyl-figure/v1/prototype
Génère une seule image de concept de type figurine vinyle à partir de la
photo source. L'ID de tâche renvoyé est celui que vous transmettez en tant
que input_task_id au point de terminaison de build. Consultez
The Vinyl Figure Prototype Task Object
pour connaître la forme de la réponse.
Paramètres
Name
image_url
Type
string
Requis
Description
Photo source que Meshy doit styliser en figurine vinyle à grosse tête. Nous prenons actuellement en charge les formats .jpg, .jpeg, .png et .webp.
Il existe deux façons de fournir l'image :
URL accessible publiquement : une URL accessible depuis internet public.
Data URI : une URI de données encodée en base64 de l'image. Exemple de Data URI : data:image/jpeg;base64,<vos données d'image encodées en base64>.
Name
name
Type
string
Description
Nom de tâche optionnel à des fins d'affichage. Maximum 100 caractères.
Name
remove_background
Type
boolean
défaut false
Description
Lorsque défini sur true, l'image du prototype est renvoyée sous forme de PNG RGBA transparent avec l'arrière-plan supprimé, afin que vous puissiez incruster le sujet sur n'importe quel arrière-plan.
Retours
La propriété result de la réponse contient l'id de la tâche de la tâche de prototype de figurine vinyle nouvellement créée. Interrogez le point de terminaison Get a Task ou abonnez-vous au stream jusqu'à ce que la tâche atteigne SUCCEEDED, puis transmettez cet ID au point de terminaison de build en tant que input_task_id.
Modes d'échec
Name
400 - Bad Request
Description
La requête était inacceptable. Causes courantes :
Paramètre manquant : image_url est requis.
Format d'image invalide : l'image_url fournie n'est pas dans un format pris en charge (.jpg, .jpeg, .png, .webp).
Dimensions d'image hors limites : l'image est trop petite, dépasse la taille de fichier maximale ou dépasse le nombre de pixels maximal.
URL inaccessible : l'image_url n'a pas pu être téléchargée (404 ou timeout).
Data URI invalide : la chaîne base64 est malformée.
Contenu signalé : l'image d'entrée a été signalée par la moderation 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
429 - Too Many Requests
Description
Vous avez dépassé votre limite de débit.
Request
POST
/openapi/creative-lab/vinyl-figure/v1/prototype
# Stage 1: generate a vinyl-figure-style concept imagecurlhttps://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/prototype \-XPOST \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "image_url": "<your publicly accessible image url or base64-encoded data URI>" }'
Response
{"result":"019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de"}
Prototype example
Start with a source photo, then generate the prototype image used by the build stage.
Génère la figurine vinyle 3D finale texturée à partir d'une tâche de prototype réussie. Le build exécute le même pipeline image-vers-3D que
Image en 3D, donc le format de l'objet de réponse et la
liste des URLs de sortie correspondent exactement. Reportez-vous à
L'objet de tâche de build de figurine vinyle
pour la forme de la réponse.
Paramètres
Name
input_task_id
Type
string
Requis
Description
L'ID de tâche d'une tâche de 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 de prototype créées via l'application web ne sont pas acceptées — le point de terminaison de build accepte uniquement les tâches de prototype produites par POST /openapi/creative-lab/vinyl-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 tâche de la tâche de build de figurine vinyle nouvellement créée. Interrogez 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 en 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 de prototype référencée n'a pas encore atteint SUCCEEDED.
Aucun candidat : La tâche de 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 de prototype référencée n'existe pas, appartient à un autre utilisateur, ou a été créée via l'application web (seules les tâches de prototype en mode API s'enchaînent vers le build).
Name
429 - Too Many Requests
Description
Vous avez dépassé votre limite de débit.
Request
POST
/openapi/creative-lab/vinyl-figure/v1/build
# Stage 2: chain build off a succeeded prototype taskcurlhttps://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/build \-XPOST \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "input_task_id": "019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de" }'
Récupère une tâche de prototype ou de build à partir d'un id de tâche valide. Le chemin de l'URL
doit correspondre à l'étape de la tâche — une tâche de build récupérée via
/prototype/:id renvoie 404, et inversement.
Annule une tâche de figurine en vinyle. Si la tâche est encore en état PENDING, les
crédits consommés au moment de la création sont remboursés. Les tâches déjà
en état IN_PROGRESS sont annulées sans remboursement (le worker est peut-être déjà
en train de consommer des ressources). Les tâches ayant déjà atteint un état
terminal (SUCCEEDED, FAILED, CANCELED) ne peuvent pas être annulées.
Le chemin de l'URL doit correspondre à l'étape de la tâche — un DELETE sur
/prototype/:buildId renvoie 404.
Paramètres de chemin
Name
id
Type
path
Description
Identifiant unique de la tâche de figurine en vinyle à annuler.
Retours
Renvoie 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 terminal 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 de l'URL.
Diffuse en flux les mises à jour en temps réel d'une tâche de figurine vinyle via Server-Sent Events
(SSE). Le chemin de l'URL doit correspondre à l'étape de la tâche — ouvrir un flux sur
/prototype/:buildId/stream émet une seule charge utile event: error avec
status_code: 404 puis ferme le flux.
Paramètres
Name
id
Type
path
Description
Identifiant unique de la tâche de figurine vinyle à diffuser en flux.
Retours
Renvoie un flux d'objets de tâche Vinyl Figure Prototype
ou Vinyl Figure Build
sous forme de Server-Sent Events. Chaque frame transporte l'objet de tâche complet pour l'étape en cours — la même forme que celle renvoyée par le
point de terminaison Get — donc tant que la tâche est PENDING ou IN_PROGRESS, les
champs de sortie ne sont simplement pas encore renseignés (null, [] ou {}) et
finished_at vaut null.
Récupère une liste paginée de vos tâches de figurine vinyle pour une seule étape.
Le chemin de l'URL sélectionne l'étape — /prototype renvoie les tâches de prototype ;
/build renvoie les tâches de build. Les tâches de l'autre étape ne sont incluses
dans aucune des deux réponses.
Paramètres de chemin
Name
stage
Type
path
Requis
Description
Soit prototype, soit build. La collection ne renvoie que les tâches
dont l'étape correspond à l'URL — récupérer /prototype ne renvoie jamais
de tâches de build, et inversement.
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 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.
L'objet Vinyl Figure Prototype Task est une unité de travail que Meshy suit
pour générer une image de concept de figurine en vinyle à partir d'une photo source.
Le résultat de cette étape est enchaîné vers
l'étape de construction via input_task_id.
Propriétés
Name
id
Type
string
Description
Identifiant unique de la tâche. Bien que nous utilisions un UUID k-sortable pour les identifiants de tâche comme 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-vinyl-figure-prototype.
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 l'une des suivantes : PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
progress de la tâche. Si la tâche n'a pas encore démarré, cette propriété sera 0. Une fois la tâche réussie, elle deviendra 100.
Name
created_at
Type
timestamp
Description
horodatage de la création de la tâche, en millisecondes.
Un horodatage représente le nombre de millisecondes écoulées depuis le 1er janvier 1970 UTC, conformément
à la norme RFC 3339.
Par exemple, le vendredi 1 septembre 2023 à 12h00:00 GMT est représenté par 1693569600000. Cela s'applique
à tous les horodatages dans Meshy API.
Name
started_at
Type
timestamp
Description
horodatage du démarrage de la tâche, en millisecondes. Si la tâche n'a pas encore démarré, cette propriété sera 0.
Name
finished_at
Type
timestamp
Description
horodatage de la fin de la tâche, en millisecondes. Si la tâche n'est pas encore terminée, cette propriété sera 0.
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.
La valeur de ce champ n'est pertinente que si le statut de la tâche est PENDING.
Name
task_error
Type
object
Description
Détails de l'erreur pour les tâches ayant échoué. 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 d'image de concept générés par cette tâche de prototype. Actuellement, l'API renvoie toujours exactement un candidat ; le champ est un tableau afin que les futures révisions puissent proposer plusieurs candidats sans provoquer de rupture de compatibilité.
L'objet Vinyl Figure Build Task est une unité de travail que Meshy suit
pour générer une figurine vinyle 3D texturée à partir d'une tâche de prototype réussie.
Il exécute le même pipeline image-en-3D que celui utilisé par Image en 3D,
de sorte que les champs de sortie reflètent l'objet de tâche de ce point de terminaison.
Propriétés
Name
id
Type
string
Description
Identifiant unique de la tâche.
Name
type
Type
string
Description
Type de la tâche. La valeur est creative-lab-vinyl-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
Progrès de la tâche. Si la tâche n'a pas encore démarré, cette propriété sera 0. Une fois la tâche réussie, elle 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émarrage 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 d'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. Renvoie 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 vinyle. Présent pour la compatibilité inter-points de terminaison avec la structure partagée V2ImageTo3DTaskResponse utilisée par Image en 3D.
Name
negative_prompt
Type
string
Description
Toujours vide pour la construction de figurine vinyle. Présent pour la compatibilité inter-points de terminaison.
Name
texture_prompt
Type
string
Description
Toujours vide pour la construction de figurine vinyle. Présent pour la compatibilité inter-points de terminaison.
Name
texture_image_url
Type
string
Description
Toujours vide pour la construction de figurine vinyle. Présent pour la compatibilité inter-points de terminaison.
Name
model_urls
Type
object
Description
URLs téléchargeables pour le modèle 3D généré. La construction de figurine vinyle produit un GLB texturé ainsi que la paire OBJ + MTL pour les pipelines qui préfèrent le format Wavefront OBJ. La forme du champ correspond à l'objet model_urls d'Image en 3D, de sorte que les futurs ajouts de format s'intègrent 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ériau MTL compagnon 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 d'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.