API Creative Lab Keycap

Transformez une photo en un keycap personnalisé entièrement coloré pour un clavier mécanique en deux étapes. Une tâche de prototype génère une image du keycap fini à partir de la photo. Une tâche de build transforme cette image en un modèle de keycap 3D texturé. Elle prend l'ID de la tâche de prototype comme input_task_id et l'ID du candidat de l'image comme candidate_id.

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

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

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

Créer une tâche de prototype Keycap

Génère une image du keycap terminé à partir d'une photo. Le champ image_urls de la tâche contient l'image, et candidate_ids contient son ID, avec une seule entrée dans chacun. Si le design ne vous plaît pas, créez une autre tâche de prototype. Meshy facture chaque tâche de prototype séparément.

Pour construire le keycap 3D, transmettez l'ID de cette tâche au point de terminaison de construction en tant que input_task_id, avec l'entrée candidate_ids en tant que candidate_id. Pour les champs de la tâche, consultez L'objet tâche de prototype Keycap.

Request

POST

/openapi/creative-lab/keycap/v1/prototype

# Stage 1: generate a finished-keycap design render
curl https://api.meshy.ai/openapi/creative-lab/keycap/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": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef"
}

Paramètres

Name
image_url
Type
string
Requis
Description
La photo à transformer en design de keycap, 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 d'au plus 20 Mo (20 000 000 octets). Chaque côté doit faire au moins 32 pixels, et l'image peut avoir au plus 178 956 970 pixels au total. Une image en dehors de ces limites renvoie 400.
Meshy détecte le format à partir des données de l'image, et non à partir de l'extension de fichier dans l'URL. Une URL sans extension fonctionne, et Meshy suit les redirections HTTP. Meshy applique l'orientation EXIF, de sorte qu'une photo de téléphone pivotée apparaît comme elle devrait.
Un Data URI doit être encodé en base64 avec un type d'image, comme data:image/png;base64,..., et l'image décodée doit être au format JPEG, PNG ou WebP. La limite de 20 Mo s'applique à l'image décodée, donc le texte base64 peut être environ un tiers plus volumineux.
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.
Name
remove_background
Type
boolean
défaut false
Description
Indique s'il faut supprimer l'arrière-plan de l'image du prototype. true renvoie un PNG RGBA transparent, afin que vous puissiez placer le keycap sur n'importe quel arrière-plan. Si Meshy ne peut pas supprimer l'arrière-plan, il renvoie l'image avec son arrière-plan, et la tâche réussit quand même.
Le design de la tête que la construction transforme en 3D conserve son arrière-plan dans tous les cas. La construction peint la base du keycap à partir de l'image dans image_urls, sans son arrière-plan si vous avez envoyé true. La construction renvoie cette image sous process_image_urls.composite.

Résultats retournés

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, avec l'entrée de candidate_ids en tant que candidate_id.

Modes d'échec

Name
400 - Bad Request
Description
La requête ne peut pas s'exécuter. Par exemple :
- image_url est manquant.
- 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 quel problème a été détecté. Corrigez la requête, puis envoyez-la à nouveau.
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 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 que la modération de contenu ou la vérification de propriété intellectuelle n'a pas pu s'exécuter, ou que Meshy n'a pas pu stocker l'image. Meshy ne crée pas la tâche, et rembourse tous les crédits facturés. Réessayez la requête.

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

Créer une tâche de build Keycap

Génère le keycap 3D texturé à partir d'une tâche de prototype réussie et de l'un de ses candidats. Pour ses champs, voir L'objet tâche de build Keycap.

Une tâche de build exécute chaque étape. Elle génère un modèle 3D à partir du design et le colorie. Ensuite, elle positionne et découpe le modèle sur la base du keycap dans une pose par défaut calibrée, afin que vous n'ayez pas besoin de l'ajuster manuellement. Enfin, elle assemble le keycap et exporte les fichiers. Un build prend généralement de 3 à 7 minutes.

Request

POST

/openapi/creative-lab/keycap/v1/build

# Stage 2: build the chosen candidate into a 3D keycap
curl https://api.meshy.ai/openapi/creative-lab/keycap/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef",
    "candidate_id": "0198c1b2-33f5-7d21-a4b7-8e9d0c1f2a3b",
    "options": {
      "base_model": "cherry-mx-1x1-r1",
      "head_size_mm": 23,
      "vertical_offset_mm": 0
    }
  }'

Response

{
  "result": "019c9a52-7d18-7e2b-9f01-6e3b98c4d2af"
}

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/keycap/v1/prototype, avec le statut SUCCEEDED.
Un ID qui ne correspond pas à l'une de vos tâches de prototype Keycap provenant de l'API renvoie 404, y compris un prototype créé dans l'application web.
Name
candidate_id
Type
string
Requis
Description
Le candidat à construire, provenant du tableau candidate_ids de la tâche de prototype. Une valeur qui n'est pas présente dans ce tableau renvoie 400.
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 de géométrie optionnels. Chaque champ a une valeur par défaut calibrée, n'envoyez donc que les champs que vous souhaitez modifier.

Name
base_model
Type
string
défaut cherry-mx-1x1-r1
Description
La base de keycap sur laquelle construire. La seule valeur possible est cherry-mx-1x1-r1, un keycap standard au profil Cherry MX 1u. Les tailles personnalisées ne sont pas prises en charge, et toute autre valeur renvoie 400.
Name
head_size_mm
Type
number
défaut 23
Description
La taille de la tête selon sa plus grande dimension, en millimètres, de 10 à 40. Meshy met à l'échelle la tête de sorte que sa plus grande dimension corresponde à cette valeur. Une valeur hors de cette plage renvoie 400.
Pour une valeur supérieure à environ 32.9, Meshy peut réduire la taille afin que la tête respecte la limite d'empreinte de protection de la base. La tête peut alors ressortir plus petite que demandé. L'objet tâche ne renvoie pas la taille appliquée par Meshy. Pour la vérifier, mesurez la boîte englobante du maillage keycap-head dans le modèle.
Name
vertical_offset_mm
Type
number
défaut 0
Description
Le décalage vertical à appliquer à la tête avant que Meshy ne la positionne sur la base, en millimètres, de -5 à 5. Une valeur hors de cette plage renvoie 400.

Retours

Le champ result contient l'ID de la nouvelle tâche de build. Récupérez la tâche ou diffusez-la en flux jusqu'à ce que status soit SUCCEEDED. Ensuite, téléchargez le fichier GLB depuis model_urls.glb et le paquet OBJ depuis model_urls.obj_zip.

Meshy exporte le fichier GLB et le paquet OBJ à l'échelle réelle en millimètres. Les deux utilisent un système de coordonnées avec axe Y vers le haut, l'avant du keycap étant orienté vers +Z.

Modes d'échec

Name
400 - Bad Request
Description
La requête ne peut pas être exécutée. 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 d'exécution, 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 aucun candidat. Créez une nouvelle tâche de prototype.
- candidate_id est manquant, ou n'est pas présent dans le candidate_ids de la tâche de prototype. Envoyez une valeur issue de ce tableau.
- Un champ dans options est hors de la plage autorisée, ou base_model n'est pas une valeur disponible.
Le message d'erreur indique le problème 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
404 - Not Found
Description
input_task_id ne correspond à aucune tâche de prototype Keycap créée par votre compte via l'API. Un prototype créé dans l'application web renvoie également 404. Envoyez l'ID result provenant 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 ce que votre limite de débit autorise. Attendez quelques secondes, puis réessayez. Voir 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 n'a pas pu créer la tâche en raison d'une erreur serveur. Meshy rembourse tous les crédits facturés. Réessayez la requête.

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

Récupérer une tâche Keycap

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 Keycap et L'objet tâche de build Keycap.

Request

GET

/openapi/creative-lab/keycap/v1/prototype/019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef

# Prototype
curl https://api.meshy.ai/openapi/creative-lab/keycap/v1/prototype/019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/keycap/v1/build/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef",
  "type": "creative-lab-keycap-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1753142456000,
  "started_at": 1753142460000,
  "finished_at": 1753142516000,
  "expires_at": 1753401716000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 12,
  "image_urls": [
    "https://assets.meshy.ai/***/design-1.png?Expires=***"
  ],
  "candidate_ids": [
    "0198c1b2-33f5-7d21-a4b7-8e9d0c1f2a3b"
  ]
}

Build Response

{
  "id": "019c9a52-7d18-7e2b-9f01-6e3b98c4d2af",
  "type": "creative-lab-keycap-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1753142600000,
  "started_at": 1753142610000,
  "finished_at": 1753143050000,
  "expires_at": 1753402250000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 50,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model.glb?Expires=***",
    "obj_zip": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model-obj.zip?Expires=***"
  },
  "process_image_urls": {
    "head_design": "https://assets.meshy.ai/***/head-design.png?Expires=***",
    "composite": "https://assets.meshy.ai/***/composite.png?Expires=***",
    "base_canvas": "https://assets.meshy.ai/***/base-canvas.png?Expires=***"
  }
}

Paramètres

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

Retours

L'objet tâche de prototype ou l'objet tâche de build, selon 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 provenant 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 tierce. Les tâches de build et les équipes du plan Enterprise ne reçoivent pas cette erreur. Créez une tâche de prototype à partir d'une image que vous avez le droit d'utiliser.
Name
404 - Not Found
Description
Aucune tâche Keycap 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/keycap/v1/(prototype|build)/:id

Supprimer une tâche Keycap

Annule une tâche Keycap. 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/keycap/v1/prototype/019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/keycap/v1/prototype/019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef \
  -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 Keycap 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 a rencontré une erreur serveur en annulant la tâche, celle-ci est donc peut-être annulée ou non. Récupérez la tâche pour vérifier son status avant de réessayer.

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

Diffuser les mises à jour d'une tâche Keycap

Diffuse les mises à jour d'une tâche Keycap sous forme d'événements envoyés par le serveur (Server-Sent Events, 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 build sur /prototype/:id/stream, le flux envoie un seul événement error avec status_code: 404 puis se ferme.

Request

GET

/openapi/creative-lab/keycap/v1/build/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/stream

curl -N https://api.meshy.ai/openapi/creative-lab/keycap/v1/build/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/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; fields not yet populated are null / empty.
// The following PENDING frame is shortened to the fields that change.
event: message
data: {
  "id": "019c9a52-7d18-7e2b-9f01-6e3b98c4d2af",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "019c9a52-7d18-7e2b-9f01-6e3b98c4d2af",
  "type": "creative-lab-keycap-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1753142600000,
  "started_at": 1753142610000,
  "finished_at": 1753143050000,
  "expires_at": 1753402250000,
  "task_error": null,
  "consumed_credits": 50,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model.glb?Expires=***",
    "obj_zip": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model-obj.zip?Expires=***"
  },
  "process_image_urls": {
    "head_design": "https://assets.meshy.ai/***/head-design.png?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 Keycap. 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 seul événement error, avec le status_code qu'une requête get aurait renvoyé.

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

List Keycap tasks

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

Request

GET

/openapi/creative-lab/keycap/v1/prototype

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

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

Response (List Prototype Tasks)

[
  {
    "id": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef",
    "type": "creative-lab-keycap-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1753142456000,
    "started_at": 1753142460000,
    "finished_at": 1753142516000,
    "expires_at": 1753401716000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 12,
    "image_urls": [
      "https://assets.meshy.ai/***/design-1.png?Expires=***"
    ],
    "candidate_ids": [
      "0198c1b2-33f5-7d21-a4b7-8e9d0c1f2a3b"
    ]
  }
]

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

Retours

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

L'objet de tâche de prototype Keycap

Une tâche de prototype génère une image du keycap fini à partir d'une photo. Pour transformer le design en keycap 3D, transmettez l'ID de la tâche au point de terminaison de build en tant que input_task_id, avec son entrée candidate_ids en tant que candidate_id.

Propriétés

Example Keycap Prototype Task Object

{
  "id": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef",
  "type": "creative-lab-keycap-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1753142456000,
  "started_at": 1753142460000,
  "finished_at": 1753142516000,
  "expires_at": 1753401716000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 12,
  "image_urls": [
    "https://assets.meshy.ai/***/design-1.png?Expires=***"
  ],
  "candidate_ids": [
    "0198c1b2-33f5-7d21-a4b7-8e9d0c1f2a3b"
  ]
}

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-keycap-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 jusqu'à ce que la tâche démarre 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 à 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 jusqu'à ce que la tâche se termine. 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 pendant qu'elle est PENDING. 1 signifie qu'elle démarre ensuite. 0 une fois que la tâche quitte 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 est à 0, car Meshy la rembourse. L'annulation ne rembourse une tâche que pendant qu'elle est PENDING. Si Meshy ne peut pas lire le montant facturé, une réponse get ou stream omet ce 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
URLs de téléchargement pour l'image du keycap fini. Le tableau contient une URL une fois la tâche réussie, et est vide jusque-là. image_urls[i] montre le candidat dans candidate_ids[i].
Ces URLs sont destinées à l'affichage. Le point de terminaison de build prend une entrée de candidate_ids, pas une URL. Ce sont des URLs signées, donc récupérez-les sans en-tête Authorization. Elles restent valides jusqu'à expires_at, et récupérer à nouveau la tâche renvoie les mêmes URLs.
Name
candidate_ids
Type
array of strings
Description
IDs des candidats, dans le même ordre que image_urls. Pour construire un candidat, envoyez son ID en tant que candidate_id dans la requête de build. Ne vous fiez pas au format de ces IDs.

L'objet de tâche de construction de keycap

Une tâche de construction génère le keycap 3D texturé à partir d'une tâche de prototype réussie et de l'un de ses candidats. Elle génère le modèle 3D, le colore, l'ajuste et le découpe sur la base du keycap, puis assemble et exporte le keycap.

Propriétés

Example Keycap Build Task Object

{
  "id": "019c9a52-7d18-7e2b-9f01-6e3b98c4d2af",
  "type": "creative-lab-keycap-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1753142600000,
  "started_at": 1753142610000,
  "finished_at": 1753143050000,
  "expires_at": 1753402250000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 50,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model.glb?Expires=***",
    "obj_zip": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model-obj.zip?Expires=***"
  },
  "process_image_urls": {
    "head_design": "https://assets.meshy.ai/***/head-design.png?Expires=***",
    "composite": "https://assets.meshy.ai/***/composite.png?Expires=***",
    "base_canvas": "https://assets.meshy.ai/***/base-canvas.png?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-keycap-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 : 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. C'est 0 jusqu'à ce que la tâche démarre 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 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 à 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 que la tâche quitte 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 est à 0, car Meshy la rembourse. L'annulation ne rembourse une tâche que tant qu'elle est PENDING. Si Meshy ne peut pas lire la charge, une réponse get ou stream omet le 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 pour le modèle 3D. Meshy exporte le fichier GLB et le bundle OBJ à l'échelle réelle en millimètres, axe Y vers le haut, avec l'avant du keycap orienté vers +Z.
Le modèle comporte des maillages nommés keycap-head et keycap-base. Lorsque Meshy se rabat sur un remplissage à motif pour la base, le modèle comporte également un maillage keycap-base-interior pour la cavité de la tige. Ne supposez pas que le modèle comporte exactement deux maillages.
Ce sont des URLs signées, donc récupérez-les sans en-tête Authorization. Elles restent valides jusqu'à expires_at, et récupérer à nouveau la tâche avant cette échéance renvoie les mêmes URLs. Une URL expirée ne peut pas être renouvelée, donc téléchargez et stockez les fichiers avant cette échéance.
- Name
  glb
  Type
  string
  Description
  URL de téléchargement pour le fichier GLB texturé, model.glb.
- Name
  obj_zip
  Type
  string
  Description
  URL de téléchargement pour le bundle OBJ, un fichier ZIP contenant model.obj, model.mtl, et les textures PNG utilisées par model.mtl. Avec une base de couleur unie, la seule texture est keycap-head.png. Avec une base à motif, le fichier ZIP contient également keycap-base.png.
Name
process_image_urls
Type
object
Description
URLs de téléchargement pour les images des étapes de la construction, indexées par type. Comme model_urls, ce sont des URLs signées, donc récupérez-les sans en-tête Authorization. Elles restent valides jusqu'à expires_at, et récupérer à nouveau la tâche renvoie les mêmes URLs.
Elle peut contenir ces clés :
- head_design : l'image de design du candidat choisi, que la construction a transformée en 3D. Toujours présente.
- composite : l'image du keycap terminé pour le candidat choisi, à partir de laquelle la construction a peint la base. Peut être absente.
- base_canvas : la base de keycap peinte. Peut être absente.
Meshy peut ajouter des clés, ignorez donc une clé que vous ne reconnaissez pas.

End-to-end example

Cet exemple exécute le flux complet :

Créer une tâche de prototype à partir d'une photo.
Récupérer la tâche jusqu'à ce que son status soit SUCCEEDED.
Choisir un candidat parmi candidate_ids.
Créer une tâche de build avec ce candidat.
Récupérer la tâche de build jusqu'à ce que son status soit SUCCEEDED.
Télécharger le fichier GLB et le bundle OBJ depuis model_urls.

L'exemple choisit le premier candidat. Dans votre application, affichez les entrées de image_urls à vos utilisateurs et laissez-les choisir. L'index d'une image choisie dans image_urls correspond à l'index de son ID dans candidate_ids.

Complete flow

POST

/openapi/creative-lab/keycap/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://...
: "${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

BASE="https://api.meshy.ai/openapi/creative-lab/keycap/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 '{"image_url":"data:%s;base64,' "$MIME"
    base64 <"$IMAGE_PATH" | tr -d '\n'
    printf '"}'
  } >"$BODY"
else
  printf '{"image_url":"%s"}' "$IMAGE_URL" >"$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 design render
poll prototype "$PROTO_ID"

# 3. Pick a candidate (first one here; show image_urls to a user in production)
CANDIDATE_ID=$(api GET "$BASE/prototype/$PROTO_ID" | jq -r '.candidate_ids[0]')

# 4. Create the build task
jq -n --arg p "$PROTO_ID" --arg c "$CANDIDATE_ID" \
  '{input_task_id: $p, candidate_id: $c}' >"$BODY"
BUILD_ID=$(api POST "$BASE/build" \
  -H 'Content-Type: application/json' --data-binary @"$BODY" | jq -r '.result')

# 5. Wait for the model (a build usually takes 3-7 minutes)
poll build "$BUILD_ID"

# 6. Download the artifacts. These are signed URLs: no Authorization header,
#    and they stay valid for 3 days after the task finishes.
TASK=$(api GET "$BASE/build/$BUILD_ID")
curl --silent --show-error --fail --max-time 900 \
  -o keycap.glb "$(jq -r '.model_urls.glb' <<<"$TASK")"
curl --silent --show-error --fail --max-time 900 \
  -o keycap-obj.zip "$(jq -r '.model_urls.obj_zip' <<<"$TASK")"
echo "Done: keycap.glb + keycap-obj.zip"