Creative Lab — API Fidget Collapsible

Transformez une photo source en un jouet fidget pliable imprimable en une seule pièce : la silhouette du sujet devient un ensemble d'anneaux concentriques imbriqués qui se replient à plat et s'étirent à nouveau, imprimés en une seule pièce sans assemblage.

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

Contrairement aux autres endpoints de Creative Lab, celui-ci ne comporte aucune paire d'étapes prototype/build — il n'y a pas de candidats intermédiaires parmi lesquels choisir, si bien qu'une seule tâche mène l'image jusqu'au modèle 3D. Les contrôles de géométrie exposés par l'application web (taille, nombre de couches, largeur de l'espacement, épaisseur de paroi, profondeur d'extrusion, renflement) ne font pas non plus partie de la requête : chaque tâche est construite avec les mêmes valeurs par défaut côté serveur.

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

Créer une tâche de fidget pliable

Génère un modèle de fidget pliable à partir d'une photo source. Reportez-vous à The Collapsible Fidget Task Object pour connaître la forme de la réponse.

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

Paramètres

Name
image_url
Type
string
Requis
Description
Photo source que Meshy transformera en fidget pliable. 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 : une Data URI encodée en base64 de l'image. Exemple de Data URI : data:image/jpeg;base64,<your base64-encoded image data>.
Un sujet avec un contour net et fermé fonctionne le mieux — c'est la silhouette qui devient les anneaux. Des arrière-plans chargés, plusieurs sujets distincts, ou des formes très fines peuvent laisser trop peu d'espace pour les parois imbriquées, et la tâche échoue avec une erreur de tâche.
Name
name
Type
string
Description
Nom de tâche facultatif à des fins d'affichage. 100 caractères maximum. Il s'agit uniquement d'une étiquette de tâche ; rien n'est gravé sur le modèle.

Retours

La propriété result de la réponse contient l'id de la tâche de fidget pliable nouvellement créée. Interrogez le point de terminaison Get a Task ou abonnez-vous au stream jusqu'à ce que la tâche atteigne SUCCEEDED, puis téléchargez le fichier STL imprimable depuis model_urls.stl (et, lorsqu'il est présent, le GLB depuis model_urls.glb pour le prévisualiser d'abord).

Modes d'échec

Name
400 - Bad Request
Description
La requête était inacceptable. Causes courantes :
- Paramètre manquant : image_url est requis.
- Format d'image invalide : le image_url fourni n'est pas dans un format pris en charge (.jpg, .jpeg, .png, .webp).
- Dimensions d'image hors limites : l'image est trop petite, dépasse la taille de fichier maximale, ou dépasse le nombre de pixels maximal.
- URL inaccessible : le image_url n'a pas pu être téléchargé (404 ou timeout).
- Data URI invalide : la chaîne base64 est mal formée.
- Contenu signalé : l'image fournie a été signalée par la moderation NSFW.
Name
401 - Unauthorized
Description
L'authentification a échoué. Veuillez vérifier votre clé API.
Name
402 - Payment Required
Description
Soit votre compte est sur le plan gratuit — la création de tâches sur ce point de terminaison nécessite un plan payant — soit vous n'avez pas assez de crédits.
Name
403 - Forbidden
Description
L'image fournie a été signalée pour violation de propriété intellectuelle.
Name
429 - Too Many Requests
Description
Vous avez dépassé votre limite de débit.

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"
}

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

Récupérer une tâche de fidget escamotable

Récupère une tâche de fidget escamotable à partir d'un id de tâche valide. Seules les tâches créées via ce point de terminaison sont accessibles ici — une tâche provenant d'un autre point de terminaison Creative Lab, ou créée dans l'application web, renvoie 404.

Consultez L'objet Tâche de fidget escamotable pour connaître la structure de la réponse.

Paramètres

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

Retour

La réponse contient l'objet de la tâche de fidget escamotable.

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=***"
  }
}

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

Supprimer une tâche de fidget pliable

Annule une tâche de fidget pliable. 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 est peut-être déjà en train de consommer des ressources). Les tâches ayant déjà atteint un état terminal (SUCCEEDED, FAILED, CANCELED) ne peuvent pas être annulées.

Paramètres de chemin

Name
id
Type
path
Description
Identifiant unique de la tâche de fidget pliable à annuler.

Retours

Retourne 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 n'a pas été créée via ce point de terminaison.

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).

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

Diffuser en continu une tâche de fidget pliable

Diffusez en continu les mises à jour en temps réel d'une tâche de fidget pliable via des Server-Sent Events (SSE). Une tâche qui n'existe pas, ou qui n'a pas été créée via ce point de terminaison, émet une seule charge utile event: error avec status_code: 404 puis ferme le flux.

Paramètres

Name
id
Type
path
Description
Identifiant unique de la tâche de fidget pliable à diffuser en continu.

Retours

Retourne un flux d'objets de tâche Fidget pliable sous forme de Server-Sent Events. Pour les tâches PENDING ou IN_PROGRESS, le flux de réponse n'inclura que les champs progress et status nécessaires.

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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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=***"
  }
}

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

Lister les tâches de fidget pliable

Récupère une liste paginée de vos tâches de fidget pliable. Seules les tâches créées via ce point de terminaison sont incluses.

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 100 éléments.
Name
sort_by
Type
string
défaut -created_at
Description
Champ de tri. Valeurs disponibles :
- +created_at : Trier par heure de création dans l'ordre croissant.
- -created_at : Trier par heure de création dans l'ordre décroissant.

Retours

Renvoie une liste paginée de l'objet tâche de fidget pliable.

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=***"
    }
  }
]

L'objet Collapsible Fidget Task

L'objet Collapsible Fidget Task est une unité de travail que Meshy suit afin de transformer une photo source en un modèle de fidget pliable imprimable en une seule pièce. Il s'agit d'une tâche à une seule étape : il n'y a pas de prototype dont dériver, et la silhouette intermédiaire ne fait pas partie de la réponse.

Propriétés

Name
id
Type
string
Description
Identifiant unique de la tâche. Bien que nous utilisions un UUID triable par k (k-sortable) comme détail d'implémentation pour les identifiants de tâche, vous ne devez pas faire d'hypothèses sur le format de l'id.
Name
type
Type
string
Description
Type de la tâche. La valeur est creative-lab-fidget-collapsible.
Name
name
Type
string
Description
Le nom de la tâche fourni lors de sa création. Chaîne vide si aucun nom n'a été fourni.
Name
status
Type
string
Description
Statut de la tâche. Les valeurs possibles sont l'une 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 de la création de la tâche, en millisecondes.
Un horodatage représente le nombre de millisecondes écoulées depuis le 1er janvier 1970 UTC, en suivant la norme RFC 3339. Par exemple, le vendredi 1er septembre 2023 à 12:00:00 GMT est représenté comme 1693569600000. Cela s'applique à tous les horodatages de l'API Meshy.
Name
started_at
Type
timestamp
Description
Horodatage du démarrage de la tâche, en millisecondes. Si la tâche n'a pas encore démarré, cette propriété sera null.
Name
finished_at
Type
timestamp
Description
Horodatage de la fin de la tâche, en millisecondes. Si la tâche n'est pas encore terminée, cette propriété sera null.
Name
expires_at
Type
timestamp
Description
Horodatage de l'expiration du résultat de la tâche, en millisecondes.
Name
preceding_tasks
Type
integer
Description
Le nombre de tâches précédentes.
La valeur de ce champ n'est 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 é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. 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
model_urls
Type
object
Description
URLs téléchargeables pour le modèle 3D généré. Renseigné une fois que la tâche a atteint le statut SUCCEEDED : stl est toujours présent, glb uniquement lorsque le rendu d'aperçu a réussi.
- Name
  stl
  Type
  string
  Description
  URL téléchargeable vers le fichier STL. Il s'agit du livrable imprimable — envoyez-le directement à un trancheur.
- Name
  glb
  Type
  string
  Description
  URL téléchargeable vers le fichier GLB, pour prévisualiser le modèle dans une visionneuse 3D. Ses couleurs sont uniquement à des fins d'aperçu : le STL ne comporte aucune couleur, et un fidget imprimé tire sa couleur du filament. Le GLB est fourni au mieux : lorsque le rendu d'aperçu n'est pas disponible, la clé est entièrement omise de model_urls, aussi convient-il de la lire de manière défensive — stl est le livrable et est toujours présent sur une tâche SUCCEEDED.

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=***"
  }
}