Creative Lab — API de figurine

Transformez une photo source en figurine 3D de collection de style chibi 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 modèle 3D texturé. Les deux étapes sont liées via input_task_id.

POST /openapi/creative-lab/figure/v1/prototype
POST /openapi/creative-lab/figure/v1/build

POST/openapi/creative-lab/figure/v1/prototype

Créer une tâche de prototype de figurine

Générez une image conceptuelle unique de style chibi à partir de la photo source. L’ID de tâche renvoyé est celui que vous transmettez comme input_task_id au point de terminaison de build. Consultez L’objet de tâche de prototype de figurine pour connaître la structure de la réponse.

Paramètres

Name
image_url
Type
string
Requis
Description
Photo source que Meshy doit styliser sous forme de figurine chibi. 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 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 tâche facultatif à des fins d’affichage. 100 caractères maximum.

Retours

La propriété result de la réponse contient l’id de tâche de la nouvelle tâche de prototype de figurine 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 transmettez cet ID au point de terminaison de build comme 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 non valide : l’image_url fourni n’est pas dans un format pris en charge (.jpg, .jpeg, .png, .webp).
- Dimensions de l’image hors limites : l’image est trop petite, dépasse la taille de fichier maximale ou dépasse le nombre maximal de pixels.
- URL inaccessible : l’image_url n’a pas pu être téléchargée (404 ou timeout).
- Data URI non valide : la chaîne base64 est mal formé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/figure/v1/prototype

# Stage 1: generate a chibi-style concept image
curl https://api.meshy.ai/openapi/creative-lab/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>"
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Prototype example

Start with a source portrait, then generate the prototype image used by the build stage.

Portrait source utilisé comme entrée Creative Lab Figure — Prototype input

Image de prototype de figurine de style chibi générée à partir de la photo source — Prototype output

POST/openapi/creative-lab/figure/v1/build

Créer une tâche de build de figurine

Générez la figurine 3D texturée finale à partir d’une tâche de prototype réussie. Le build exécute le même pipeline Image en 3D que Image en 3D, donc le format de l’objet de réponse et la liste des URL de sortie correspondent exactement. Consultez L’objet de tâche de build de figurine pour la structure 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/figure/v1/prototype et refuse toute autre source avec 404.
Name
name
Type
string
Description
Nom de tâche facultatif à des fins d’affichage. 100 caractères maximum.

Retourne

La propriété result de la réponse contient l’id de tâche de la nouvelle tâche de build de figurine 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 fréquentes :
- Paramètre manquant : input_task_id est requis.
- UUID invalide : 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 peuvent être enchaînées vers le build).
Name
429 - Too Many Requests
Description
Vous avez dépassé votre limite de débit.

Request

POST

/openapi/creative-lab/figure/v1/build

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/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"
  }'

Response

{
  "result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}

Build example

The build task turns the selected prototype image into a downloadable textured 3D model.

Creative Lab Figure build model preview — Build model preview

GET/openapi/creative-lab/figure/v1/(prototype|build)/:id

Récupérer une tâche de figurine

Récupérez une tâche de prototype ou de build avec un id de tâche valide. Le chemin d’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.

Consultez L’objet de tâche de prototype de figurine et L’objet de tâche de build de figurine pour les structures de réponse.

Paramètres

Name
id
Type
path
Description
Identifiant unique de la tâche de figurine à récupérer.

Retours

La réponse contient l’objet de tâche de figurine. La structure dépend de l’étape demandée.

Request

GET

/openapi/creative-lab/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

# Prototype
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-figure-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Build Response

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-figure-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 20,
  "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=***"
    }
  ]
}

DELETE/openapi/creative-lab/figure/v1/(prototype|build)/:id

Supprimer une tâche de figurine

Annule une tâche de figurine. Si la tâche est encore PENDING, les crédits consommés au moment de la création sont remboursés. Les tâches déjà IN_PROGRESS sont annulées sans remboursement (le worker peut déjà être en train de consommer des Ressources). Les tâches qui ont déjà atteint un état terminal (SUCCEEDED, FAILED, CANCELED) ne peuvent pas être annulées.

Le chemin d’URL doit correspondre à l’étape de la tâche — DELETE sur /prototype/:buildId renvoie 404.

Paramètres de chemin

Name
id
Type
path
Description
Identifiant unique de la tâche de figurine à 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 d’URL.

Request

DELETE

/openapi/creative-lab/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 204 No Content on success (empty body).

GET/openapi/creative-lab/figure/v1/(prototype|build)/:id/stream

Diffuser une tâche de figurine

Diffusez des mises à jour en temps réel pour une tâche de figurine via Server-Sent Events (SSE). Le chemin de l’URL doit correspondre à l’étape de la tâche — l’ouverture d’un flux sur /prototype/:buildId/stream émet une seule charge utile event: error avec status_code: 404 et ferme le flux.

Paramètres

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

Retours

Retourne un flux d’objets de tâche Prototype de figurine ou Build de figurine 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/creative-lab/figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream

curl -N https://api.meshy.ai/openapi/creative-lab/figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (wrong stage or task not found)
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-figure-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "task_error": null,
  "consumed_credits": 20,
  "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=***"
    }
  ]
}

GET/openapi/creative-lab/figure/v1/(prototype|build)

Lister les tâches de figurine

Récupérez une liste paginée de vos tâches de figurine 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 réponse.

Paramètres de chemin

Name
stage
Type
path
Requis
Description
Soit prototype, soit build. La collection renvoie uniquement 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 50 é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 par ordre croissant.
- -created_at: Trier par heure de création par ordre décroissant.

Retours

Renvoie une liste paginée de l’objet de tâche par étape — soit l’objet de tâche de prototype de figurine lors du listing de /prototype, soit l’objet de tâche de build de figurine lors du listing de /build.

Request

GET

/openapi/creative-lab/figure/v1/prototype

# List prototype tasks
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/prototype?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# List build tasks
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/build?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response (List Prototype Tasks)

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-figure-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123486000,
    "expires_at": 1729382686000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/concept.png?Expires=***"
    ]
  }
]

L’objet tâche de prototype de figurine

L’objet tâche de prototype de figurine est une unité de travail que Meshy suit pour générer une image conceptuelle de style chibi à partir d’une photo source. La sortie de cette étape est enchaînée à 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 triable en k pour les identifiants de tâche comme détail d’implémentation, vous ne devez faire aucune supposition sur le format de l’identifiant.
Name
type
Type
string
Description
Type de la tâche. La valeur est creative-lab-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 l’une de PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progression 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 indiquant quand 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, conformément à la norme RFC 3339. Par exemple, le vendredi 1er 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 indiquant quand la tâche a démarré, en millisecondes. Si la tâche n’a pas encore démarré, cette propriété sera 0.
Name
finished_at
Type
timestamp
Description
Horodatage indiquant quand la tâche s’est terminée, en millisecondes. Si la tâche n’est pas encore terminée, cette propriété sera 0.
Name
expires_at
Type
timestamp
Description
Horodatage indiquant quand 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 n’est significative 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é. Consultez 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. Renvoie 0 pour les tâches FAILED (les crédits sont remboursés en cas d’échec).
Name
image_urls
Type
array of strings
Description
URL téléchargeables pour les images conceptuelles candidates générées par cette tâche de prototype. Actuellement, l’API renvoie toujours exactement une candidate ; le champ est un tableau afin que de futures révisions puissent exposer plusieurs candidates sans changement incompatible.

Example Figure Prototype Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-figure-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

L’objet de tâche de construction de figurine

L’objet de tâche de construction de figurine est une unité de travail que Meshy suit afin de générer une figurine 3D texturée à partir d’une tâche de prototype réussie. Il exécute le même pipeline d’image en 3D utilisé par Image en 3D, de sorte que les champs de sortie reflètent l’objet de tâche de ce point de terminaison.

Properties

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-figure-build.
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 l’une de 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.
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. Significatif uniquement lorsque le statut est PENDING.
Name
task_error
Type
object
Description
Détails d’erreur pour les tâches échouées. Consultez 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. Présent pour la compatibilité entre points 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. Présent pour la compatibilité entre points de terminaison.
Name
texture_prompt
Type
string
Description
Toujours vide pour la construction de figurine. Présent pour la compatibilité entre points de terminaison.
Name
texture_image_url
Type
string
Description
Toujours vide pour la construction de figurine. Présent pour la compatibilité entre points de terminaison.
Name
model_urls
Type
object
Description
URL téléchargeables pour le modèle 3D généré. La construction de figurine émet un GLB texturé ainsi que la paire OBJ + MTL pour les pipelines qui préfèrent Wavefront OBJ. La forme du champ correspond à l’objet Image en 3D model_urls, afin que les futurs ajouts de formats s’intègrent sans changement cassant.
- 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 de 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 carte de couleur de base.

Example Figure Build Task Object

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-figure-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 20,
  "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=***"
    }
  ]
}