API Creative Lab Collapsible Fidget

Transformez une photo en un jouet fidget pliable imprimable en une seule pièce, en une seule tâche. La silhouette du sujet devient des anneaux concentriques imbriqués qui se replient à plat et s'étirent à nouveau. Le jouet s'imprime en une seule pièce, sans assemblage.

POST /openapi/creative-lab/fidget-collapsible/v1

Contrairement aux autres endpoints de Creative Lab, celui-ci n'a pas d'étapes distinctes de prototype et de construction. Il n'y a pas d'images candidates entre lesquelles choisir, donc une seule tâche transforme la photo en modèle 3D.

La requête n'a pas non plus de paramètres de géométrie. L'application web vous permet de définir la taille, le nombre de couches, la largeur de l'espace, l'épaisseur de paroi, la profondeur d'extrusion et le renflement. Chaque tâche API utilise les mêmes valeurs par défaut pour ces paramètres.

POST/openapi/creative-lab/fidget-collapsible/v1

Créer une tâche Fidget pliable

Génère un modèle de fidget pliable à partir d'une photo. Pour les champs de la tâche, voir L'objet tâche Fidget pliable.

Chaque tâche coûte 6 crédits et nécessite un plan payant.

Request

POST

/openapi/creative-lab/fidget-collapsible/v1

curl https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1 \
  -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"
}

Paramètres

Name
image_url
Type
string
Requis
Description
La photo à transformer en fidget pliable, 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.
La silhouette du sujet devient les anneaux, un sujet avec un contour net et fermé fonctionne donc le mieux. Un arrière-plan chargé, plusieurs sujets distincts ou des formes très fines peuvent laisser trop peu d'espace pour les parois imbriquées. Dans ce cas, la tâche échoue.
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, et Meshy ne le grave pas sur le modèle. Un nom plus long renvoie 400.

Retours

Le champ result contient l'ID de la nouvelle tâche. Récupérez la tâche ou diffusez-la en flux jusqu'à ce que status soit SUCCEEDED. Téléchargez ensuite le fichier STL imprimable depuis model_urls.stl. Pour prévisualiser le modèle au préalable, téléchargez le fichier GLB depuis model_urls.glb lorsqu'il est présent.

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 le problème rencontré. 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. 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 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 débités. Réessayez la requête.

GET/openapi/creative-lab/fidget-collapsible/v1/:id

Récupérer une tâche Collapsible Fidget

Renvoie une tâche Collapsible Fidget. Seules les tâches créées avec ce point de terminaison sont renvoyées. Une tâche provenant d'un autre point de terminaison Creative Lab, ou une tâche créée dans l'application web, renvoie 404.

Pour les champs, voir L'objet tâche Collapsible Fidget.

Request

GET

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

Paramètres

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

Retour

L'objet tâche Collapsible Fidget.

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 comme relevant d'une propriété intellectuelle tierce. Les équipes sur le plan Entreprise ne reçoivent pas cette erreur. Créez une tâche à partir d'une image dont vous détenez les droits d'utilisation.
Name
404 - Not Found
Description
Aucune tâche Collapsible Fidget avec cet ID n'appartient à votre compte, ou la tâche n'a pas été créée avec ce point de terminaison. Vérifiez l'ID.
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-collapsible/v1/:id

Supprimer une tâche Collapsible Fidget

Annule une tâche Collapsible Fidget. 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.

Request

DELETE

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -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 Collapsible Fidget avec cet ID n'appartient à votre compte, ou la tâche n'a pas été créée avec ce point de terminaison. Vérifiez l'ID.

GET/openapi/creative-lab/fidget-collapsible/v1/:id/stream

Diffuser les mises à jour d'une tâche Collapsible Fidget en continu

Diffuse les mises à jour d'une tâche Collapsible Fidget sous forme d'événements envoyés par le serveur (SSE). Si la tâche n'existe pas ou n'a pas été créée avec ce point de terminaison, le flux envoie un événement error avec status_code: 404 puis se ferme.

Request

GET

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (task not found, or not created through this endpoint)
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": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?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 Collapsible Fidget. Chaque événement contient l'objet de tâche complet, tel que renvoyé par Récupérer une tâche Collapsible Fidget. 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, avec le status_code qu'une requête get aurait renvoyé.

GET/openapi/creative-lab/fidget-collapsible/v1

Lister les tâches Collapsible Fidget

Renvoie vos tâches Collapsible Fidget, une page à la fois. Seules les tâches créées avec ce point de terminaison sont incluses.

Request

GET

/openapi/creative-lab/fidget-collapsible/v1

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-fidget-collapsible",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123512000,
    "expires_at": 1729382712000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
    }
  }
]

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 tâche Collapsible Fidget.

L'objet de tâche Collapsible Fidget

Une tâche Collapsible Fidget transforme une photo en un modèle de fidget pliable imprimable en une seule pièce. C'est une tâche en une seule étape, il n'y a donc pas de tâche de prototype à partir de laquelle enchaîner. La réponse n'inclut pas la silhouette que Meshy crée en cours de route.

Propriétés

Example Collapsible Fidget Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?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-collapsible.
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 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 éventuel. 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 parvient 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
model_urls
Type
object
Description
URL de téléchargement pour le modèle 3D, vide jusqu'à ce que la tâche réussisse. Une tâche réussie dispose toujours de stl, et n'a glb que si Meshy a rendu l'aperçu.
- Name
  stl
  Type
  string
  Description
  URL de téléchargement pour le fichier STL, qui est le fichier à imprimer. Vous pouvez l'ouvrir directement dans un trancheur.
- Name
  glb
  Type
  string
  Description
  URL de téléchargement pour un fichier GLB permettant de prévisualiser le modèle dans une visionneuse 3D. Ses couleurs ne servent qu'à l'aperçu. Le fichier STL n'a pas de couleur, donc le fidget imprimé prend sa couleur à partir du filament.
  Si Meshy ne peut pas rendre l'aperçu, model_urls n'a pas de clé glb, donc vérifiez la présence de la clé avant de la lire. Une tâche SUCCEEDED dispose toujours de stl.