Creative Lab — API Collapsible Fidget

Transformez une photo source en un jouet fidget télescopique 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 d'un seul tenant sans assemblage.

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

Contrairement aux autres endpoints Creative Lab, celui-ci ne comporte aucune paire d'étapes prototype/build — il n'y a pas de candidats intermédiaires parmi lesquels choisir, donc une seule tâche fait passer l'image directement jusqu'au modèle 3D. Les contrôles de géométrie exposés par l'application web (taille, nombre de couches, largeur d'espacement, épaisseur de paroi, profondeur d'extrusion, bombement) 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 Repliable

Génère un modèle de fidget repliable à partir d'une photo source. Consultez L'objet de tâche du Fidget Repliable pour la structure 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 va transformer en fidget repliable. Nous prenons actuellement en charge les formats .jpg, .jpeg, .png, et .webp.
Il existe deux façons de fournir l'image :
- URL publiquement accessible : Une URL accessible depuis internet public.
- Data URI : Une data URI de l'image encodée en base64. Exemple de data URI : data:image/jpeg;base64,<vos données d'image encodées en base64>.
Un sujet avec un contour net et fermé fonctionne le mieux — la silhouette est ce qui devient les anneaux. Des arrière-plans chargés, plusieurs sujets distincts, ou des formes très fines peuvent laisser trop peu de surface 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 optionnel à des fins d'affichage. Maximum 100 caractères. 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 tâche du fidget repliable nouvellement créé. Interrogez le point de terminaison Obtenir une tâche ou abonnez-vous au flux jusqu'à ce que la tâche atteigne SUCCEEDED, puis téléchargez le 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 d'entrée 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âche 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 d'entrée 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 rétractable

Récupérez une tâche de fidget rétractable à partir d'un id de tâche valide. Seules les tâches créées via ce point de terminaison peuvent être adressées ici — une tâche provenant d'un autre point de terminaison de Creative Lab, ou créée dans l'application web, renvoie 404.

Consultez L'objet tâche de fidget rétractable pour connaître la forme de la réponse.

Paramètres

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

Retours

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

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 à 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 flux les mises à jour d'une tâche Fidget Collapsible

Diffuse en flux les mises à jour en temps réel d'une tâche fidget collapsible via 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 et ferme le flux.

Paramètres

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

Retours

Retourne un flux d'objets de tâche Collapsible Fidget sous forme de Server-Sent Events. Chaque trame contient l'objet de tâche complet pour l'étape en cours — la même forme que celle retournée par le point de terminaison Get — ainsi, tant que la tâche est PENDING ou IN_PROGRESS, les champs de sortie ne sont simplement pas encore renseignés (null, [] ou {}) et finished_at vaut null.

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 PENDING frame below is abbreviated 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=***"
  }
}

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

Lister les tâches de fidget dépliable

Récupérez une liste paginée de vos tâches de fidget dé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 la taille de la page. Le maximum autorisé est de 100 éléments.
Name
sort_by
Type
string
défaut -created_at
Description
Champ selon lequel trier. Valeurs disponibles :
- +created_at : Trier par heure de création dans l'ordre croissant.
- -created_at : Trier par heure de création dans l'ordre décroissant.

Retours

Retourne une liste paginée de l'objet tâche de fidget dé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 Tâche de fidget pliable

L'objet Tâche de fidget pliable est une unité de travail que Meshy suit pour 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 k-triable pour les identifiants de tâche comme détail d'implémentation, 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 la création de la tâche. Chaîne vide si aucun nom n'a été fourni.
Name
status
Type
string
Description
Statut de la tâche. Les valeurs possibles sont PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progression de la tâche. Si la tâche n'a pas encore commencé, cette propriété sera 0. Une fois que la tâche a réussi, 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, conformément à la norme RFC 3339. Par exemple, le vendredi 1er septembre 2023 à 12h00 GMT est représenté par 1693569600000. Cela s'applique à tous les horodatages de Meshy API.
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. Retourne 0 pour les tâches FAILED (les crédits sont remboursés en cas d'échec).
Name
model_urls
Type
object
Description
URL téléchargeables pour le modèle 3D généré. Renseigné une fois que la tâche a 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. C'est le 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 un visualiseur 3D. Ses couleurs ne sont qu'à titre d'aperçu : le STL ne porte 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, il faut donc 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=***"
  }
}