Creative Lab — Keycap API

Photo source que Meshy transforme en images de design de keycap. 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, et non à partir de l'extension de fichier de l'URL — une URL sans extension, ou une URL qui redirige, fonctionne tant que les octets se décodent vers un format pris en charge. Les redirections HTTP sont suivies. L'orientation EXIF est normalisée, de sorte qu'une photo de téléphone tournée est utilisée telle qu'elle apparaît visuellement.

Limites : au moins 32 pixels sur chaque côté, au plus 178 956 970 pixels au total, et au plus 20 000 000 octets une fois téléchargée. Pour un Data URI, la limite s'applique aux octets décodés, donc le fichier source lui-même peut atteindre cette taille — c'est le texte base64 qui est environ un tiers plus volumineux, ce qui compte pour le corps de votre requête, pas pour cette limite. Un Data URI doit déclarer un type de contenu image/* et ;base64.

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

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

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

Lorsqu'il est défini sur true, le rendu d'affichage renvoyé dans image_urls est un PNG RGBA transparent avec l'arrière-plan supprimé, ce qui vous permet de le composer sur n'importe quel arrière-plan.

Cela s'applique uniquement au rendu d'affichage. Le candidat consommé par le point de terminaison de build n'est pas affecté, le résultat 3D est donc identique dans les deux cas.

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 de l'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 : 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.

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

Le compte est sur le plan gratuit (un plan payant est requis pour créer des tâches) ou dispose de crédits insuffisants.

L'image d'entrée a été signalée par la moderation de propriété intellectuelle.

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

Une erreur serveur inattendue s'est produite — par exemple, le service de moderation de contenu était indisponible, la mise en préparation de l'image d'entrée a échoué, ou la tâche n'a pas pu être créée. Aucune tâche n'est créée dans ce cas, il est donc sûr de réessayer.

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, doit avoir atteint SUCCEEDED, et doit avoir produit au moins un candidat.

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/keycap/v1/prototype et refuse toute autre source avec 404.

Le candidat à construire, pris dans le tableau candidate_ids de la tâche de prototype réussie. Doit appartenir à cette tâche ; toute autre valeur est rejetée avec 400.

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

La base de keycap sur laquelle construire. Actuellement, la seule valeur disponible est cherry-mx-1x1-r1 — un keycap 1u de profil Cherry MX standard. 3 à 5 tailles standard grand public supplémentaires sont prévues ; les tailles personnalisées ne sont pas prises en charge.

Taille cible de la tête sculptée, en millimètres : sa dimension la plus longue est mise à l'échelle sur cette valeur. Plage : [10, 40]. Les valeurs supérieures à environ 32.9 peuvent être réduites afin que la tête respecte toujours la limite d'emprise de protection de la base, de sorte que la dimension la plus longue livrée peut être inférieure à celle demandée. La valeur appliquée n'est pas encore renvoyée sur l'objet tâche — si vous devez confirmer la taille réellement obtenue, mesurez la boîte englobante du maillage keycap-head dans le modèle téléchargé.

Décalage vertical appliqué à la tête avant qu'elle ne soit positionnée sur la base, en millimètres. Plage : [-5, 5].

La requête était inacceptable. Causes courantes :

• Paramètre manquant : input_task_id et candidate_id sont 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 aucun candidat.
• Candidat inconnu : candidate_id ne fait pas partie des candidats de la tâche d'entrée.
• Options hors limites : l'un des champs options se situait en dehors de sa plage autorisée ou de son ensemble d'énumération.

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

Le compte est sur le plan gratuit (un plan payant est requis pour créer des tâches) ou dispose de crédits insuffisants.

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 peuvent enchaîner vers un build).

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

Une erreur serveur inattendue s'est produite — par exemple, le service de moderation de contenu était indisponible, la mise en préparation de l'image d'entrée a échoué, ou la tâche n'a pas pu être créée. Aucune tâche n'est créée dans ce cas, il est donc sûr de réessayer.

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

Identifiant unique de la tâche keycap à annuler.

La tâche est déjà dans un état final 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.

Une erreur serveur inattendue s'est produite lors de l'annulation. La tâche a pu être annulée ou non — relisez-la pour le confirmer avant de réessayer.

Identifiant unique de la tâche keycap à diffuser en flux continu.

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 heure de création dans l'ordre croissant.
• -created_at : Trier par heure de création dans l'ordre décroissant.

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

Type de la tâche. La valeur est creative-lab-keycap-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 démarré, cette propriété sera 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 0.

Horodatage de la fin de la tâche, en millisecondes. Si la tâche n'est pas encore terminée, cette propriété sera 0.

Horodatage de l'expiration du résultat de la tâche, en millisecondes.

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

Détails d'erreur pour les tâches échouées. Consultez 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 du 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 par la modération) n'est pas facturée du tout. Une tâche qui atteint FAILED renvoie 0 — les frais sont remboursés, y compris en cas de blocage par la modération asynchrone. 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é.

URL téléchargeable du rendu de la conception de touche finalisée — l'apparence du candidat en tant que touche finie. Contient une seule entrée ; image_urls[i] correspond à candidate_ids[i]. Vide jusqu'à ce que la tâche atteigne SUCCEEDED. L'URL est uniquement destinée à l'affichage ; le point de terminaison de build consomme les candidate_ids, pas ces URL. Même cycle de vie d'URL que model_urls : signée, sans en-tête Authorization, valide jusqu'à expires_at, et stable lors d'une nouvelle lecture de la tâche.

Identifiants de candidats opaques, en parallèle de image_urls. Transmettez l'entrée correspondant à la conception choisie en tant que candidate_id de la requête de build. Ne faites pas d'hypothèses sur le format de ces identifiants.

Identifiant unique de la tâche.

Type de la tâche. La valeur est creative-lab-keycap-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 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.

Horodatage de la fin de la tâche, en millisecondes.

Horodatage de l'expiration du résultat de la tâche, en millisecondes.

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 pour son étape. Une tâche qui n'est jamais créée (un 4xx au moment de la requête, y compris un rejet de modération) n'est pas facturée du tout. Une tâche qui atteint FAILED renvoie 0 — le montant est remboursé, y compris en cas de blocage de modération asynchrone. 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é.

URL téléchargeables pour les fichiers du modèle généré. Le GLB et le bundle OBJ sont tous deux exportés à l'échelle réelle en millimètres, avec Y vers le haut, l'avant du keycap étant orienté vers +Z. Les maillages sont nommés keycap-head et keycap-base ; lorsque la base se rabat sur un remplissage à motif, un troisième maillage keycap-base-interior est également présent pour la cavité de la tige. Ne pas supposer qu'il y a exactement deux maillages.

Ce sont des URL 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 vous-même les fichiers avant cela — il n'existe aucun moyen de rafraîchir un lien expiré.

URL téléchargeables pour les images de processus intermédiaires, indexées par type. Même cycle de vie d'URL que model_urls : signées, sans en-tête Authorization, valides jusqu'à expires_at, et stables lorsque la tâche est relue. Types actuellement émis :

• head_design — l'image de design du candidat choisi consommée par la génération (toujours présente).
• composite — le rendu d'affichage du keycap terminé pour le candidat choisi (présent si disponible).
• base_canvas — le canevas peint de la base du keycap (présent si disponible).

Considérez cet ensemble de clés comme ouvert ; de nouveaux types peuvent être ajoutés sans rupture de compatibilité.