API Creative Lab Fidget Pixel

Transformez une photo en un plateau fidget en pixel art multicolore, imprimable en 3D, en deux étapes. Une tâche de prototype transforme la photo en une image en pixel art. Une tâche de build transforme cette image en pièces imbriquées dans un seul fichier 3MF, et prend l'ID de la tâche de prototype en tant que input_task_id.

POST /openapi/creative-lab/fidget-pixel/v1/prototype
POST /openapi/creative-lab/fidget-pixel/v1/build

Les deux endpoints POST nécessitent un abonnement payant. Une requête provenant d'un compte en plan gratuit renvoie 402.

POST/openapi/creative-lab/fidget-pixel/v1/prototype

Créer une tâche de prototype Fidget Pixel

Génère une image en pixel art à partir d'une photo. Pour construire les pièces, transmettez l'ID de cette tâche au point de terminaison de construction en tant que input_task_id. Pour les champs de la tâche, consultez L'objet de tâche de prototype Fidget Pixel.

Si l'image ne vous convient pas, créez une autre tâche de prototype. Chaque tâche est facturée séparément.

Request

POST

/openapi/creative-lab/fidget-pixel/v1/prototype

# Stage 1: pixelize the source photo
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/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>",
    "type": "person"
  }'

Response

{
  "result": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7"
}

Paramètres

Name
image_url
Type
string
Requis
Description
La photo à transformer en pixel art, sous forme d'URL publique ou de Data URI (data:image/jpeg;base64,<vos données d'image encodées en base64>).
L'image doit être un fichier JPG, JPEG, PNG ou WebP de 20 Mo maximum. Meshy détecte le format à partir des données de l'image, et non à partir de l'extension du fichier dans l'URL. Une URL sans extension fonctionne, et Meshy suit les redirections.
Name
type
Type
string
Requis
Description
Ce que montre la photo, ce qui détermine le style du pixel art. Les deux styles sont clairement différents. Toute autre valeur renvoie 400.
Valeurs disponibles :
- person : une personne, en portrait ou en photo plein corps. Meshy dessine un sprite pixel de style chibi.
- other : tout autre sujet, par exemple un animal de compagnie, un objet, une mascotte, un logo ou un paysage. Meshy dessine une icône pixel de style perles à repasser.
Name
name
Type
string
Description
Un nom pour la tâche, jusqu'à 100 caractères. Il est renvoyé dans le champ name de la tâche. Un nom plus long renvoie 400.

Retours

Le champ result contient l'ID de la nouvelle tâche de prototype. Récupérez la tâche ou diffusez-la en continu jusqu'à ce que status soit SUCCEEDED. Transmettez ensuite l'ID au point de terminaison de construction en tant que input_task_id.

Modes d'échec

Name
400 - Bad Request
Description
La requête ne peut pas s'exécuter. Par exemple :
- image_url ou type est manquant.
- type n'est ni person ni other.
- L'image n'est pas un fichier JPG, JPEG, PNG ou WebP.
- L'image est trop petite, dépasse 20 Mo, ou dépasse le nombre maximal de pixels.
- Meshy ne peut pas télécharger l'image, par exemple parce que l'URL renvoie 404 ou expire.
- Le Data URI n'est pas un base64 valide.
- L'image a été signalée comme NSFW.
Le message d'erreur indique le problème détecté. Corrigez la requête, puis renvoyez-la.
Name
401 - Unauthorized
Description
La clé API est manquante ou invalide. Vérifiez l'en-tête Authorization.
Name
402 - Payment Required
Description
L'un des cas suivants s'applique :
- Le compte n'a pas assez de crédits.
- La clé API, l'espace de travail ou le membre a atteint sa limite de crédits.
- Le compte est sur le plan gratuit.
Vérifiez vos crédits et votre plan, puis réessayez.
Name
403 - Forbidden
Description
Votre équipe a activé le filtrage IP, et Meshy a signalé l'image pour propriété intellectuelle tierce. Envoyez une image que vous avez le droit d'utiliser.
Name
429 - Too Many Requests
Description
L'une de ces limites a été atteinte :
- Vous avez envoyé plus de requêtes que ne le permet votre limite de débit. Attendez quelques secondes, puis réessayez. Consultez Limites de débit.
- Trop de vos tâches sont en file d'attente ou en cours d'exécution. Attendez que certaines se terminent, puis réessayez.
- Sur un plan illimité sans crédits restants, vous avez atteint le nombre de tâches pouvant s'exécuter sans crédits. Attendez qu'une tâche se termine, ou ajoutez des crédits.
Name
500 - Internal Server Error
Description
Meshy a rencontré une erreur serveur, par exemple parce qu'il n'a pas pu exécuter la vérification de propriété intellectuelle sur l'image. Meshy ne crée pas la tâche, et rembourse les crédits éventuellement facturés. Réessayez la requête.

POST/openapi/creative-lab/fidget-pixel/v1/build

Créer une tâche de build Fidget Pixel

Génère les pièces imprimables en 3D à partir d'une tâche de prototype réussie. Meshy échantillonne l'image pixel-art sur la grille et la réduit à au plus color_count couleurs. Chaque cellule du sujet devient une pièce entrelacée, et l'arrière-plan n'est pas imprimé.

Le résultat est un unique fichier 3MF multicolore, prêt à être imprimé en couleur. Chaque pièce a un corps gris et un dessus de la couleur de son pixel. Pour ses champs, consultez L'objet de la tâche de build Fidget Pixel.

Request

POST

/openapi/creative-lab/fidget-pixel/v1/build

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
    "options": {
      "shape": "square",
      "grid_size": 32,
      "piece_size_mm": 8,
      "color_count": 8,
      "piece_height_mm": 15
    },
    "output": {
      "format": "3mf"
    }
  }'

Response

{
  "result": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98"
}

Paramètres

Name
input_task_id
Type
string
Requis
Description
L'ID de la tâche de prototype à construire. Il doit s'agir d'une tâche créée par votre compte avec POST /openapi/creative-lab/fidget-pixel/v1/prototype, avec le statut SUCCEEDED.
Un ID qui ne correspond pas à l'une de vos tâches de prototype Fidget Pixel issues de l'API renvoie 404, y compris un prototype créé dans l'application web.
Name
name
Type
string
Description
Un nom pour la tâche, jusqu'à 100 caractères. Il est renvoyé dans le champ name de la tâche. Un nom plus long renvoie 400.

`options`

Paramètres pour la forme et la taille des pièces. Chaque champ a une valeur par défaut, donc n'envoyez que les champs que vous souhaitez modifier. Un 0 utilise la valeur par défaut du champ. Ce sont les mêmes paramètres que dans l'application web Creative Lab. Les autres paramètres de forme sont fixes, et Meshy les définit à partir de shape et piece_size_mm.

Name
shape
Type
string
défaut square
Description
L'empreinte de chaque pièce. Toute autre valeur renvoie 400.
Valeurs disponibles :
- square : pièces carrées sur une grille carrée
- hex : pièces hexagonales sur une grille hexagonale, avec piece_size_mm défini sur 6 ou 8
Name
grid_size
Type
integer
défaut 32
Description
Le nombre de cellules de la grille le long de chaque côté du plateau, 16 ou 32. Toute autre valeur renvoie 400. Une grille 32 conserve plus de détails. Une grille 16 donne moins de pièces de la même taille, donc le plateau est environ deux fois moins large.
Name
piece_size_mm
Type
integer
défaut 8
Description
La longueur de l'arête de chaque pièce en millimètres, 6, 8, ou 10. Toute autre valeur renvoie 400. Avec grid_size, il définit la taille du plateau imprimé. Par exemple, une grille 32 de pièces de 8 mm fait environ 26,5 cm de côté.
10 ne fonctionne pas avec hex et renvoie 400, car la face hexagonale inclinée est en porte-à-faux sur la plupart des imprimantes FDM grand public.
Name
color_count
Type
integer
défaut 8
Description
Le nombre maximal de couleurs dans la palette pixel-art, de 1 à 8. Une valeur en dehors de cette plage renvoie 400. Pour imprimer, vous avez besoin d'au plus color_count plus un filament, un par couleur et un pour les corps gris.
Name
piece_height_mm
Type
integer
défaut 15
Description
La hauteur de chaque pièce en millimètres, de 10 à 80. Une valeur en dehors de cette plage renvoie 400.

`output`

Paramètres pour le fichier de résultat.

Name
format
Type
string
défaut 3mf
Description
Le format de fichier du résultat. Toute autre valeur renvoie 400.
Valeurs disponibles :
- 3mf : un seul fichier model.3mf multicolore, renvoyé dans model_urls.3mf

Retours

Le champ result contient l'ID de la nouvelle tâche de build. Récupérez la tâche ou diffusez-la jusqu'à ce que status soit SUCCEEDED. Téléchargez ensuite le fichier 3MF depuis model_urls.3mf.

Modes d'échec

Name
400 - Bad Request
Description
La requête ne peut pas s'exécuter. Par exemple :
- input_task_id est manquant ou n'est pas un ID de tâche valide.
- Le statut de la tâche de prototype n'est pas SUCCEEDED. Si elle est encore en cours, attendez puis réessayez. Si elle a échoué ou a été annulée, créez une nouvelle tâche de prototype.
- La tâche de prototype a réussi mais n'a pas d'image. Créez une nouvelle tâche de prototype.
- Un champ options est en dehors de ses valeurs autorisées, par exemple un grid_size autre que 16 ou 32.
- piece_size_mm vaut 10 et shape vaut hex. Les pièces hexagonales n'existent qu'en 6 et 8 mm.
- output.format n'est pas 3mf.
Le message d'erreur indique quel problème a été trouvé.
Name
401 - Unauthorized
Description
La clé API est manquante ou invalide. Vérifiez l'en-tête Authorization.
Name
402 - Payment Required
Description
L'un des cas suivants s'applique :
- Le compte n'a pas assez de crédits.
- La clé API, l'espace de travail ou le membre a atteint sa limite de crédits.
- Le compte est sur le plan gratuit.
Vérifiez vos crédits et votre plan, puis réessayez.
Name
403 - Forbidden
Description
Votre équipe a activé le filtrage IP, et Meshy a signalé l'image de la tâche de prototype pour propriété intellectuelle tierce. Créez une tâche de prototype à partir d'une image que vous avez le droit d'utiliser.
Name
404 - Not Found
Description
input_task_id ne correspond à aucune tâche de prototype Fidget Pixel créée par votre compte avec l'API. Un prototype créé dans l'application web renvoie aussi 404. Envoyez l'ID result d'une réponse de création de prototype.
Name
429 - Too Many Requests
Description
L'une de ces limites a été atteinte :
- Vous avez envoyé plus de requêtes que votre limite de débit ne le permet. Attendez quelques secondes, puis réessayez. Consultez Limites de débit.
- Trop de vos tâches sont en file d'attente ou en cours d'exécution. Attendez que certaines se terminent, puis réessayez.
- Sur un plan illimité sans crédits restants, vous avez atteint le nombre de tâches pouvant s'exécuter sans crédits. Attendez qu'une tâche se termine, ou ajoutez des crédits.
Name
500 - Internal Server Error
Description
Meshy a rencontré une erreur serveur, par exemple parce qu'elle n'a pas pu exécuter la vérification de propriété intellectuelle sur l'image de la tâche de prototype. Meshy ne crée pas la tâche, et rembourse tous les crédits qu'elle a facturés. Réessayez la requête.

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

Récupérer une tâche Fidget Pixel

Renvoie une tâche de prototype ou de build. Le chemin doit correspondre à l'étape de la tâche. Une tâche de build demandée via /prototype/:id renvoie 404, et il en va de même pour une tâche de prototype demandée via /build/:id.

Pour les champs, voir L'objet tâche de prototype Fidget Pixel et L'objet tâche de build Fidget Pixel.

Request

GET

/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7

# Prototype
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
  "type": "creative-lab-fidget-pixel-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001000000,
  "started_at": 1757001005000,
  "finished_at": 1757001178000,
  "expires_at": 1757260378000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/pixel-art.jpg?Expires=***"
  ]
}

Build Response

{
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001300000,
  "started_at": 1757001304000,
  "finished_at": 1757001309000,
  "expires_at": 1757260509000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/output/model.3mf?Expires=***"
  }
}

Paramètres

Name
id
Type
path
Description
L'ID de la tâche issu de la réponse de création.

Retours

L'objet tâche de prototype ou l'objet tâche de build, correspondant à l'étape indiquée dans le chemin.

Modes d'échec

Name
400 - Bad Request
Description
id n'est pas un ID de tâche valide. Envoyez l'ID result issu de la réponse de création.
Name
403 - Forbidden
Description
Votre équipe a activé le filtrage IP, et Meshy a signalé l'image de la tâche de prototype pour propriété intellectuelle de tiers. Les tâches de build et les équipes sur le plan Enterprise ne reçoivent pas cette erreur. Créez une tâche de prototype à partir d'une image dont vous détenez les droits d'utilisation.
Name
404 - Not Found
Description
Aucune tâche Fidget Pixel avec cet ID n'appartient à votre compte, ou l'étape de la tâche ne correspond pas au chemin. Vérifiez l'ID, et utilisez /prototype ou /build pour correspondre à la tâche.
Name
500 - Internal Server Error
Description
Meshy n'a pas pu exécuter la vérification de propriété intellectuelle. Réessayez la requête.

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

Supprimer une tâche Fidget Pixel

Annule une tâche Fidget Pixel. Annuler une tâche PENDING rembourse ses crédits. Une tâche IN_PROGRESS est annulée sans remboursement, car un worker l'a déjà prise en charge. Une tâche ayant un statut final (SUCCEEDED, FAILED ou CANCELED) ne peut pas être annulée.

Le chemin doit correspondre à l'étape de la tâche. Par exemple, un DELETE sur /prototype/:id avec l'ID d'une tâche de build renvoie 404.

Request

DELETE

/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

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

Paramètres de chemin

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

Retours

204 No Content avec un corps vide.

Modes d'échec

Name
400 - Bad Request
Description
L'un des cas suivants s'applique :
- id n'est pas un ID de tâche valide. Envoyez l'ID result de la réponse de création.
- La tâche a déjà un statut final (SUCCEEDED, FAILED ou CANCELED), elle ne peut donc pas être annulée.
Name
404 - Not Found
Description
Aucune tâche Fidget Pixel avec cet ID n'appartient à votre compte, ou l'étape de la tâche ne correspond pas au chemin. Vérifiez l'ID, et utilisez /prototype ou /build pour faire correspondre la tâche.

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

Diffuser les mises à jour d'une tâche Fidget Pixel

Diffuse les mises à jour d'une tâche Fidget Pixel sous forme d'événements envoyés par le serveur (SSE). Le chemin doit correspondre à l'étape de la tâche. Si ce n'est pas le cas, par exemple l'ID d'une tâche de build sur /prototype/:id/stream, le flux envoie un événement error unique avec status_code: 404 puis se ferme. Un id qui n'est pas un identifiant de tâche valide produit le même résultat avec status_code: 400.

Request

GET

/openapi/creative-lab/fidget-pixel/v1/build/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/stream

curl -N https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/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.
// Every frame is the full task object for the stage; fields not yet populated are null / empty.
event: message
data: {
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "name": "",
  "status": "PENDING",
  "progress": 0,
  "created_at": 1757001300000,
  "started_at": null,
  "finished_at": null,
  "expires_at": 1757260500000,
  "preceding_tasks": 2,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {}
}

event: message
data: {
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001300000,
  "started_at": 1757001304000,
  "finished_at": 1757001309000,
  "expires_at": 1757260509000,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/output/model.3mf?Expires=***"
  }
}

Paramètres

Name
id
Type
path
Description
L'ID de la tâche provenant de la réponse de création.

Retours

Un flux d'objets de tâche prototype ou build. Chaque événement contient l'objet de tâche complet, tel que renvoyé par Récupérer une tâche Fidget Pixel. Tant que la tâche est PENDING ou IN_PROGRESS, ses champs de sortie restent vides (null, [] ou {}), et finished_at vaut null.

Si le filtrage IP bloque le résultat de la tâche, le flux envoie à la place un événement error unique, avec le status_code qu'une requête GET renverrait.

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

Lister les tâches Fidget Pixel

Renvoie vos tâches Fidget Pixel d'une étape, une page à la fois. Le chemin sélectionne l'étape. /prototype renvoie uniquement les tâches de prototype, et /build renvoie uniquement les tâches de build.

Request

GET

/openapi/creative-lab/fidget-pixel/v1/prototype

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

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

Response (List Prototype Tasks)

[
  {
    "id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
    "type": "creative-lab-fidget-pixel-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1757001000000,
    "started_at": 1757001005000,
    "finished_at": 1757001178000,
    "expires_at": 1757260378000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/pixel-art.jpg?Expires=***"
    ]
  }
]

Paramètres de chemin

Name
stage
Type
path
Requis
Description
L'étape à lister, prototype ou build.

Paramètres de requête

Name
page_num
Type
integer
défaut 1
Description
La page à renvoyer, de 1 à 255. 0 renvoie la première page. Une valeur en dehors de 0 à 255 renvoie 400.
Name
page_size
Type
integer
défaut 10
Description
Nombre de tâches par page, jusqu'à 100. Une valeur de 101 à 255 renvoie 100 tâches, et 0 utilise la valeur par défaut. Une valeur en dehors de 0 à 255 renvoie 400.
Name
sort_by
Type
string
défaut -created_at
Description
L'ordre de tri.
Valeurs disponibles :
- -created_at : du plus récent au plus ancien
- +created_at : du plus ancien au plus récent

Retour

Un tableau d'objets tâche de prototype ou d'objets tâche de build, correspondant à l'étape indiquée dans le chemin.

L'objet de tâche de prototype Fidget Pixel

Une tâche de prototype transforme une photo en image pixel art. Pour transformer l'image en pièces imprimables en 3D, transmettez l'ID de la tâche au point de terminaison de build en tant que input_task_id.

Propriétés

Example Fidget Pixel Prototype Task Object

{
  "id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
  "type": "creative-lab-fidget-pixel-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001000000,
  "started_at": 1757001005000,
  "finished_at": 1757001178000,
  "expires_at": 1757260378000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/pixel-art.jpg?Expires=***"
  ]
}

Name
id
Type
string
Description
L'ID de la tâche. Ne vous fiez pas à son format.
Name
type
Type
string
Description
Le type de tâche, toujours creative-lab-fidget-pixel-prototype.
Name
name
Type
string
Description
Le name que vous avez envoyé lors de la création de la tâche, ou "" si vous n'en avez pas envoyé.
Name
status
Type
string
Description
Le statut de la tâche.
Valeurs disponibles :
- PENDING : en attente dans la file
- IN_PROGRESS : génération du résultat en cours
- SUCCEEDED : final, avec le résultat
- FAILED : final, avec la raison dans task_error
- CANCELED : final, sans résultat
Name
progress
Type
integer
Description
Pourcentage du travail effectué, de 0 à 100. Il est à 0 tant que la tâche n'a pas démarré et à 100 quand elle réussit.
Name
created_at
Type
timestamp
Description
Heure de création de la tâche, en millisecondes Unix.
Name
started_at
Type
timestamp
Description
Heure à laquelle un worker a démarré la tâche, en millisecondes Unix. null jusqu'à ce moment-là.
Name
finished_at
Type
timestamp
Description
Heure à laquelle la tâche a atteint un statut final, en millisecondes Unix. null jusqu'à ce moment-là.
Name
expires_at
Type
timestamp
Description
Heure à laquelle le résultat de la tâche expire, en millisecondes Unix. C'est 3 jours après finished_at, ou 3 jours après created_at tant que la tâche n'est pas terminée. Pour les comptes Enterprise, qui conservent les résultats de l'API indéfiniment, c'est environ 100 ans plus tard. Voir Conservation des ressources.
Name
preceding_tasks
Type
integer
Description
La position de la tâche dans la file tant qu'elle est PENDING. 1 signifie qu'elle démarre ensuite. 0 une fois la tâche sortie de la file, et toujours 0 dans les résultats de liste.
Name
task_error
Type
object
Description
La raison de l'échec de la tâche. null sauf si status est FAILED. Voir Erreurs.
Name
consumed_credits
Type
integer
Description
Nombre de crédits facturés pour la tâche, après tout remboursement éventuel. Une requête qui renvoie une erreur n'est pas facturée. Une tâche échouée vaut 0, car Meshy la rembourse. L'annulation ne rembourse une tâche que pendant qu'elle est PENDING. Si Meshy ne peut pas lire la charge, une réponse de récupération ou de flux omet le champ, et une requête de liste renvoie 500. Dans ce cas, réessayez la requête.
Name
image_urls
Type
array of strings
Description
URL de téléchargement de l'image pixel art. Le tableau contient une URL une fois la tâche réussie, et est vide jusque-là.
Les URL sont signées, il faut donc les récupérer sans en-tête Authorization. Elles restent valides jusqu'à expires_at. Récupérer à nouveau la tâche avant cette échéance renvoie les mêmes URL, pas de nouvelles URL signées. Une URL expirée ne peut pas être renouvelée, il faut donc télécharger et stocker les fichiers avant cette échéance.

L'objet de tâche de construction Fidget Pixel

Une tâche de construction génère les pièces imprimables en 3D à partir d'une tâche de prototype réussie. Meshy échantillonne l'image pixel art sur la grille et renvoie les pièces dans un seul fichier 3MF multicolore.

Propriétés

Example Fidget Pixel Build Task Object

{
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001300000,
  "started_at": 1757001304000,
  "finished_at": 1757001309000,
  "expires_at": 1757260509000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/output/model.3mf?Expires=***"
  }
}

Name
id
Type
string
Description
L'ID de la tâche. Ne vous fiez pas à son format.
Name
type
Type
string
Description
Le type de la tâche, toujours creative-lab-fidget-pixel-build.
Name
name
Type
string
Description
Le name que vous avez envoyé lors de la création de la tâche, ou "" si vous n'en avez pas envoyé.
Name
status
Type
string
Description
Le statut de la tâche.
Valeurs disponibles :
- PENDING : en attente dans la file
- IN_PROGRESS : génération du résultat en cours
- SUCCEEDED : terminée, avec le résultat
- FAILED : terminée, avec la raison dans task_error
- CANCELED : terminée, sans résultat
Name
progress
Type
integer
Description
Pourcentage du travail effectué, de 0 à 100. Il vaut 0 tant que la tâche n'a pas commencé et 100 lorsqu'elle réussit.
Name
created_at
Type
timestamp
Description
Heure de création de la tâche, en millisecondes Unix.
Name
started_at
Type
timestamp
Description
Heure à laquelle un worker a démarré la tâche, en millisecondes Unix. null jusque-là.
Name
finished_at
Type
timestamp
Description
Heure à laquelle la tâche a atteint un statut final, en millisecondes Unix. null jusque-là.
Name
expires_at
Type
timestamp
Description
Heure d'expiration du résultat de la tâche, en millisecondes Unix. C'est 3 jours après finished_at, ou 3 jours après created_at tant que la tâche n'est pas terminée. Pour les comptes Enterprise, qui conservent les résultats de l'API indéfiniment, c'est environ 100 ans plus tard. Voir Conservation des ressources.
Name
preceding_tasks
Type
integer
Description
La position de la tâche dans la file d'attente tant qu'elle est PENDING. 1 signifie qu'elle démarre ensuite. 0 une fois que la tâche a quitté la file, et toujours 0 dans les résultats de liste.
Name
task_error
Type
object
Description
La raison de l'échec de la tâche. null sauf si status est FAILED. Voir Erreurs.
Name
consumed_credits
Type
integer
Description
Nombre de crédits facturés pour la tâche, après tout remboursement. Une requête qui renvoie une erreur n'est pas facturée. Une tâche échouée vaut 0, car Meshy la rembourse. L'annulation ne rembourse une tâche que tant qu'elle est PENDING. Si Meshy ne parvient pas à lire la charge, une réponse de récupération ou de flux omet ce champ, et une requête de liste renvoie 500. Dans ce cas, réessayez la requête.
Name
model_urls
Type
object
Description
URLs de téléchargement du résultat, indexées par format de fichier. L'objet contient une seule entrée, pour le output.format que vous avez envoyé, et est vide jusqu'à ce que la tâche réussisse.
Les URLs sont signées, donc récupérez-les sans en-tête Authorization. Elles restent valides jusqu'à expires_at. Récupérer la tâche à nouveau avant cette échéance renvoie les mêmes URLs, pas des URLs nouvellement signées. Une URL expirée ne peut pas être rafraîchie, donc téléchargez et stockez les fichiers avant cette échéance.
- Name
  3mf
  Type
  string
  Description
  URL de téléchargement du fichier 3MF multicolore. Chaque pièce a un corps gris et un dessus de la couleur de son pixel. Présent lorsque output.format est 3mf, qui est la valeur par défaut.

Exemple de bout en bout

Les scripts cURL et Python suivants exécutent l'intégralité du flux. Chaque script crée une tâche de prototype à partir d'une photo et attend qu'elle réussisse. Ensuite, il crée une tâche de build, attend que cette tâche se termine, puis télécharge le fichier 3MF depuis model_urls.3mf.

Le script cURL nécessite curl et jq, et le script Python nécessite le package requests. Pour exécuter un script, suivez ces étapes :

Définissez MESHY_API_KEY sur votre clé API.
Définissez IMAGE_PATH sur le chemin d'une photo locale, ou IMAGE_URL sur une URL d'image publique.
Facultatif : pour pixéliser un sujet autre qu'une personne, définissez PIXEL_TYPE sur other.
Exécutez le script.

Une tâche de prototype se termine généralement en quelques minutes. Une tâche de build se termine généralement en bien moins d'une minute.

Dans votre application, affichez l'image provenant de image_urls à votre utilisateur avant de créer la tâche de build. Si elle ne lui convient pas, créez plutôt une autre tâche de prototype. Ainsi, vous ne dépensez des crédits de build que pour une image qu'il a approuvée.

Complete flow

POST

/openapi/creative-lab/fidget-pixel/v1

#!/usr/bin/env bash
set -euo pipefail

# Requires curl and jq. Point IMAGE_PATH at a local photo, or IMAGE_URL at a public one:
#   export MESHY_API_KEY=msy_...
#   export IMAGE_PATH=./portrait.jpg          # or: export IMAGE_URL=https://...
#   export PIXEL_TYPE=person                  # or: other
: "${MESHY_API_KEY:?export MESHY_API_KEY first}"
if [[ -z "${IMAGE_PATH:-}" && -z "${IMAGE_URL:-}" ]]; then
  echo "export IMAGE_PATH (local file) or IMAGE_URL (public url) first" >&2
  exit 1
fi
PIXEL_TYPE=${PIXEL_TYPE:-person}

BASE="https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1"
AUTH="Authorization: Bearer $MESHY_API_KEY"

# api METHOD URL [curl args...] -> prints the response body, non-zero on failure.
# Note we do not use -f/--fail: it discards the body, and the body is the only
# place the reason appears.
api() {
  local method=$1 url=$2 out http_code body
  shift 2
  out=$(curl --silent --show-error --max-time 60 --write-out $'\n%{http_code}' \
    -X "$method" "$url" -H "$AUTH" "$@") || return 1
  http_code=${out##*$'\n'}
  body=${out%$'\n'*}
  if ((http_code >= 400)); then
    echo "HTTP $http_code for $url: $body" >&2
    return 1
  fi
  printf '%s' "$body"
}

# Each task gets its own 40-minute budget.
poll() {
  local kind=$1 id=$2 delay=5 task_status deadline
  deadline=$(($(date +%s) + 2400))
  while :; do
    if (($(date +%s) >= deadline)); then
      echo "gave up waiting for $kind $id" >&2
      return 1
    fi
    task_status=$(api GET "$BASE/$kind/$id" | jq -r '.status')
    echo "$kind: $task_status"
    case "$task_status" in
    SUCCEEDED) return 0 ;;
    FAILED | CANCELED) return 1 ;;
    esac
    sleep "$delay"
    delay=$((delay * 2 > 30 ? 30 : delay * 2))
  done
}

# Build the request body in a file. A base64 data URI must never go on the
# command line or into an exported variable - a photo of any real size will
# exceed the OS argument limit.
BODY=$(mktemp)
trap 'rm -f "$BODY"' EXIT
if [[ -n "${IMAGE_PATH:-}" ]]; then
  # Declare the real type: the API accepts JPEG, PNG and WebP.
  case "$(printf '%s' "${IMAGE_PATH##*.}" | tr 'A-Z' 'a-z')" in
    png) MIME=image/png ;;
    webp) MIME=image/webp ;;
    *) MIME=image/jpeg ;;
  esac
  {
    printf '{"type":"%s","image_url":"data:%s;base64,' "$PIXEL_TYPE" "$MIME"
    base64 <"$IMAGE_PATH" | tr -d '\n'
    printf '"}'
  } >"$BODY"
else
  jq -n --arg t "$PIXEL_TYPE" --arg u "$IMAGE_URL" \
    '{type: $t, image_url: $u}' >"$BODY"
fi

# 1. Create the prototype task
PROTO_ID=$(api POST "$BASE/prototype" \
  -H 'Content-Type: application/json' --data-binary @"$BODY" | jq -r '.result')

# 2. Wait for the pixel-art image (show image_urls[0] to a user in production)
poll prototype "$PROTO_ID"

# 3. Create the build task (defaults: square pieces, 32x32 grid, 8 mm, 8 colors, 15 mm tall)
jq -n --arg p "$PROTO_ID" \
  '{input_task_id: $p, options: {shape: "square", grid_size: 32, piece_size_mm: 8, color_count: 8, piece_height_mm: 15}, output: {format: "3mf"}}' >"$BODY"
BUILD_ID=$(api POST "$BASE/build" \
  -H 'Content-Type: application/json' --data-binary @"$BODY" | jq -r '.result')

# 4. Wait for the pieces
poll build "$BUILD_ID"

# 5. Download the 3MF. This is a signed URL: no Authorization header,
#    and it stays valid for 3 days after the task finishes.
TASK=$(api GET "$BASE/build/$BUILD_ID")
curl --silent --show-error --fail --max-time 900 \
  -o fidget-pixel.3mf "$(jq -r '.model_urls["3mf"]' <<<"$TASK")"
echo "Done: fidget-pixel.3mf"