Creative Lab — API Fidget Pixel

Photo source que Meshy doit pixeliser. Nous prenons actuellement en charge les formats .jpg, .jpeg, .png et .webp.

Le format est détecté en décodant les données de l'image, pas à partir de l'extension de fichier de l'URL — une URL sans extension, ou qui redirige, fonctionne tant que les octets se décodent vers un format pris en charge. Les redirections HTTP sont suivies.

Il existe deux façons de fournir l'image :

• URL accessible publiquement : une URL accessible depuis l'internet public.
• Data URI : une URI de données encodée en base64 de l'image. Exemple de Data URI : data:image/jpeg;base64,<vos données d'image encodées en base64>.

Ce que représente la photo. Sélectionne le style de pixelisation, choisissez donc délibérément — les deux produisent des résultats visiblement différents. Valeurs disponibles :

• person — le sujet est une personne (portrait ou corps entier). Produit un sprite pixel au style chibi du sujet.
• other — tout le reste : animaux de compagnie, objets, mascottes, logos, paysages. Produit une icône pixel au style perles du sujet.

Nom de tâche facultatif à des fins d'affichage. Maximum 100 caractères.

La requête était inacceptable. Causes courantes :

• Paramètre manquant : image_url et type sont tous deux requis.
• Type invalide : type doit être person ou other.
• Format d'image invalide : l'image_url fournie 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 maximal de pixels.
• URL inaccessible : l'image_url n'a pas pu être téléchargée (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 modération NSFW.

L'authentification a échoué. Veuillez vérifier votre clé API.

Crédits insuffisants pour effectuer cette tâche, ou la clé API appartient à un compte au forfait gratuit.

L'image d'entrée a été signalée par la modération de propriété intellectuelle (Content flagged for intellectual property violation). Seuls les comptes Enterprise avec le filtrage de propriété intellectuelle activé sont bloqués ; rien n'est facturé.

Vous avez dépassé votre limite de débit.

La vérification de propriété intellectuelle elle-même n'a pas pu être effectuée (Unable to perform intellectual property check, please try again). Les comptes Enterprise avec le filtrage de propriété intellectuelle activé échouent en mode fermé sur cette vérification ; rien n'est facturé — réessayez la requête.

L'ID de tâche d'une tâche de prototype créée via ce même point de terminaison OpenAPI. Le prototype doit avoir été créé par le même compte Meshy et doit avoir atteint SUCCEEDED.

Les tâches de prototype créées via l'application web ne sont pas acceptées — le point de terminaison de build accepte uniquement les tâches de prototype produites par POST /openapi/creative-lab/fidget-pixel/v1/prototype et refuse toute autre source avec 404.

Nom de tâche optionnel à des fins d'affichage. Maximum 100 caractères.

Empreinte de chaque pièce. Valeurs disponibles :

• square (par défaut) — pièces carrées sur une grille carrée.
• hex — pièces hexagonales sur une grille hexagonale. Les pièces hexagonales sont disponibles uniquement en 6 et 8 mm.

Nombre de pièces le long de chaque côté du plateau. Valeurs disponibles : 16 ou 32. Une grille de 32 conserve plus de détails ; une grille de 16 signifie des pièces moins nombreuses et plus grandes pour le même sujet.

Longueur de côté de chaque pièce, en millimètres. Valeurs disponibles : 6, 8, ou 10. Combinée avec grid_size, cela définit la taille du plateau imprimé — par exemple 32 × 8 mm ≈ 26 cm par côté. 10 n'est pas disponible pour shape: "hex" (la face hexagonale inclinée forme un porte-à-faux sur la plupart des imprimantes FDM grand public).

Nombre maximum de couleurs dans la palette à laquelle l'image est quantifiée. Plage : [1, 8]. Chaque couleur devient un filament dans votre trancheur.

Hauteur de chaque pièce, en millimètres. Plage : [10, 80].

Artefact renvoyé par le build. Valeurs disponibles :

• 3mf (par défaut) — renvoie un seul model.3mf sous model_urls.3mf, avec un objet par pièce et la couleur de la pièce attachée à chaque objet.

La requête était inacceptable. Causes courantes :

• Paramètre manquant : input_task_id est requis.
• UUID invalide : input_task_id n'est pas un UUID valide.
• Parent non réussi : La tâche de prototype référencée n'a pas encore atteint SUCCEEDED.
• Aucun candidat : La tâche de prototype a réussi mais n'a produit aucune image pixel-art ; créez un nouveau prototype.
• Options hors limites : Un des champs options est en dehors de son ensemble ou de sa plage autorisée — par exemple options.grid_size must be 16 or 32, ou options.piece_size_mm=10 is not supported for shape=hex; hex pieces are available in 6 and 8 mm.
• Format non pris en charge : output.format doit être 3mf.

L'authentification a échoué. Veuillez vérifier votre clé API.

Crédits insuffisants pour effectuer cette tâche, ou la clé API appartient à un compte de plan gratuit.

L'image du prototype référencé a été signalée par la moderation de propriété intellectuelle. Seuls les comptes Enterprise avec le filtrage de propriété intellectuelle activé sont bloqués ; aucun montant n'est débité.

La tâche de prototype référencée n'existe pas, appartient à un autre utilisateur, ou a été créée via l'application web (seules les tâches de prototype en mode API s'enchaînent vers le build).

Vous avez dépassé votre limite de débit.

Le verdict de propriété intellectuelle du prototype référencé n'a pas pu être établi (Unable to perform intellectual property check, please try again). Les comptes Enterprise avec le filtrage de propriété intellectuelle activé échouent de manière fermée sur cette vérification ; aucun montant n'est débité — réessayez la requête.

Identifiant unique de la tâche fidget pixel à récupérer.

id n'est pas un UUID valide (Invalid ID).

L'image de la tâche a été signalée par la modération de propriété intellectuelle. Seuls les comptes Enterprise ayant activé le filtrage de propriété intellectuelle sont bloqués.

La tâche n'existe pas, appartient à un autre utilisateur, ou son étape ne correspond pas au chemin de l'URL.

La vérification de propriété intellectuelle n'a pas pu être effectuée (Unable to perform intellectual property check, please try again) ; les comptes Enterprise ayant activé le filtrage de propriété intellectuelle échouent par défaut de manière restrictive. Réessayez la requête.

Identifiant unique de la tâche fidget pixel à annuler.

La requête était inacceptable. Causes courantes :

• ID invalide : id n'est pas un UUID valide.
• État terminal : La tâche est déjà SUCCEEDED, FAILED ou CANCELED et ne peut pas être annulée.

La tâche n'existe pas, appartient à un autre utilisateur, ou son étape ne correspond pas au chemin de l'URL.

Identifiant unique de la tâche fidget pixel à diffuser.

Soit prototype soit build. La collection ne renvoie que les tâches dont l'étape correspond à l'URL — récupérer /prototype ne renvoie jamais de tâches de build, et vice versa.

Numéro de page pour la pagination.

Limite de taille de page. Le maximum autorisé est de 100 éléments.

Champ selon lequel trier. Valeurs disponibles :

• +created_at : Trier par date de création par ordre croissant.
• -created_at : Trier par date de création par ordre décroissant.

Identifiant unique de la tâche. Bien que nous utilisions un UUID k-sortable 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.

Type de la tâche. La valeur est creative-lab-fidget-pixel-prototype.

Le nom de la tâche fourni lors de sa création. Chaîne vide si aucun nom n'a été fourni.

Statut de la tâche. Les valeurs possibles sont PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Progression de la tâche. Si la tâche n'a pas encore commencé, cette propriété vaudra 0. Une fois la tâche réussie, elle deviendra 100.

Horodatage de la création de la tâche, en millisecondes.

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.

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.

Horodatage d'expiration du résultat de la tâche, en millisecondes — 3 jours après la fin de la tâche. Les comptes Enterprise conservent les résultats de l'API indéfiniment (voir Conservation des ressources) ; pour eux, cet horodatage est fixé à environ 100 ans.

Le nombre de tâches précédentes.

Détails de l'erreur pour les tâches échouées. Voir Erreurs pour la référence complète de l'objet task_error.

Le nombre de crédits consommés par cette tâche. Une tâche qui atteint SUCCEEDED est facturée au montant total de son étape. Une tâche qui n'est jamais créée (une erreur 4xx au moment de la requête, y compris un rejet de moderation) n'est pas facturée du tout. Une tâche qui atteint FAILED renvoie 0 — les crédits sont remboursés. L'annulation via DELETE ne rembourse que si la tâche est encore PENDING ; une tâche déjà IN_PROGRESS reste facturée, car le travail a déjà été effectué.

URLs téléchargeables pour l'image en pixel art générée par cette tâche de prototype. Actuellement, l'API renvoie toujours exactement une image ; le champ est un tableau afin que de futures révisions puissent proposer plusieurs candidats sans rupture de compatibilité. Vide tant que la tâche n'a pas atteint SUCCEEDED.

Ce sont des URLs signées : récupérez-les sans en-tête Authorization. Elles restent valides jusqu'à expires_at, soit 3 jours après finished_at, et relire la tâche dans cette fenêtre renvoie l'URL identique plutôt qu'une nouvelle URL signée. Téléchargez et stockez les fichiers vous-même avant cette échéance — il n'existe aucun moyen de rafraîchir un lien expiré.

Identifiant unique de la tâche.

Type de la tâche. La valeur est creative-lab-fidget-pixel-build.

Le nom de la tâche fourni lors de sa création. Chaîne vide si aucun nom n'a été fourni.

Statut de la tâche. Les valeurs possibles sont l'une des suivantes : PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Progression de la tâche. Si la tâche n'a pas encore démarré, cette propriété vaudra 0. Une fois la tâche réussie, elle deviendra 100.

Horodatage de la création de la tâche, en millisecondes.

Horodatage du démarrage de la tâche, en millisecondes. null tant que la tâche n'a pas démarré.

Horodatage de la fin de la tâche, en millisecondes. null tant que la tâche n'est pas terminée.

Horodatage de l'expiration du résultat de la tâche, en millisecondes — 3 jours après la fin de la tâche. Les comptes Enterprise conservent les résultats de l'API indéfiniment (voir Conservation des ressources) ; pour eux, cet horodatage est fixé à environ 100 ans.

Le nombre de tâches précédentes. Pertinent uniquement lorsque le statut est PENDING.

Détails d'erreur pour les tâches échouées. Voir Erreurs pour la référence complète de l'objet task_error.

Le nombre de crédits consommés par cette tâche. Une tâche qui atteint SUCCEEDED est facturée au montant complet correspondant à son étape. Une tâche qui n'est jamais créée (une erreur 4xx au moment de la requête, y compris un rejet par la moderation) n'est pas facturée du tout. Une tâche qui atteint FAILED renvoie 0 — le montant est remboursé. L'annulation via DELETE ne rembourse que tant que la tâche est encore PENDING ; une tâche déjà IN_PROGRESS reste facturée, car le travail a déjà été effectué.

URLs téléchargeables pour la ressource générée, classées par format. Contient exactement une entrée — le format demandé via le champ output.format de la requête de build. Vide tant que la tâche n'a pas atteint SUCCEEDED.

Ce sont des URLs signées : récupérez-les sans en-tête Authorization. Elles restent valides jusqu'à expires_at, soit 3 jours après finished_at, et relire la tâche pendant cette période renvoie l'URL identique plutôt qu'une nouvelle URL signée. Téléchargez et stockez les fichiers vous-même avant cette échéance — il n'existe aucun moyen de renouveler un lien expiré.