URL du serveur
text
https://www.youthumb.ai/api/mcpAjouter YouThumb à ton agent
| Agent | Comment ajouter le serveur |
|---|---|
| Claude | Paramètres → Connecteurs → Ajouter un connecteur personnalisé, colle l’URL du serveur, puis Connecter. |
| ChatGPT | Dans les réglages des connecteurs (mode développeur), crée un connecteur avec l’URL du serveur et l’authentification OAuth. |
| Claude Code | claude mcp add --transport http youthumb https://www.youthumb.ai/api/mcp, puis lance /mcp pour te connecter. |
| Codex | codex mcp add youthumb --url https://www.youthumb.ai/api/mcp, puis codex mcp login youthumb. |
Connexion et autorisation
- Ton agent ouvre une page YouThumb dans ton navigateur.
- Connecte-toi avec ton e-mail et ton mot de passe ou avec Google. Le lien magique n’est pas disponible pour cette connexion.
- YouThumb affiche l’application qui demande l’accès, l’adresse où elle te renverra et les droits demandés.
- Choisis l’Organisation utilisée par cette app : l’app travaillera uniquement dans cette organisation, avec ses crédits. Pour en changer plus tard, reconnecte l’app.
- Choisis Autoriser ou Refuser.
Ce que ton agent peut faire
| Droit | Outils |
|---|---|
mcp:read | get_credits, list_persons, get_person, list_assets, list_templates, list_presets, get_generation |
mcp:generate | create_thumbnail_project, start_generation |
mcp:assets | upload_asset, delete_asset, create_person, add_person_images |
Garder la main sur les crédits
Créer un projet ne consomme pas de crédits ; lancer la génération, si. L’agent utilise les crédits de l’organisation que tu as choisie en l’autorisant. Si tes crédits sont épuisés, qu’une limite de ton plan est atteinte ou que trop de générations tournent en même temps, l’outil renvoie une erreur lisible au lieu de générer. Tu préfères une clé API et le skillyouthumb-ai ? Consulte Agents.
Bibliothèque, favoris et corbeille
Retrouvez les projets existants avant de créer une nouvelle miniature.GET /api/thumbnails et list_thumbnail_projects acceptent search, status, favorite et deleted. Les listes utilisent page (à partir de 1) et limit (1–100, 20 par défaut), avec les filtres appliqués avant pagination. favorite=false sélectionne les non-favoris ; deleted=true sélectionne les projets à la corbeille.
Les favoris sont partagés par l’organisation sélectionnée. Envoyez explicitement {"isFavorite":true} ou {"isFavorite":false} : une répétition ne bascule pas l’état. Renommez avec {"projectName":"Nouveau titre"}. La gestion de bibliothèque ne consomme aucun crédit. En MCP, les lectures demandent mcp:read et le droit Lecture ; les mutations demandent mcp:generate et le droit Génération, ainsi que les permissions habituelles du compte. Seuls les administrateurs peuvent mettre un projet entier à la corbeille.
Les listes normales et le détail masquent les jobs supprimés et les projets parents supprimés. list_generations renvoie les résultats terminés des projets miniatures visibles, avec toutes les images de variations dans le tableau results de chaque job. La corbeille accepte kind=projects ou kind=jobs (jobs supprimés individuellement, y compris sous un parent supprimé). Aucune suppression définitive. Restaurez d’abord le projet, puis les jobs supprimés individuellement. La restauration d’un projet fixe son statut à completed, sans restaurer ses enfants. Le deletedAt du projet est dérivé de updatedAt, pas un historique immuable de suppression. Le job possède son propre deletedAt stocké. Répéter une suppression/restauration déjà effectuée préserve les horodatages.
Un job actif ou un projet avec des jobs actifs ne peut pas être supprimé (409). Restaurer un job sous un parent supprimé renvoie aussi 409. Une requête invalide renvoie 400, un droit insuffisant 403, un identifiant inconnu ou d’une autre organisation 404.
GET /api/thumbnails/:projectId, /detailed-status, /status et get_generation partagent le détail : métadonnées projet, isFavorite, résumé global, dernier résultat, métadonnées des jobs, images groupées et IDs des personnes. jobs[].results et activeJobs restent disponibles. Sans option, tous les jobs visibles sont renvoyés ; page ou limit active la pagination bornée. status seul (valeurs séparées par des virgules) filtre tous les jobs visibles sans les paginer, pour préserver les clients existants. Le résumé et le dernier résultat restent globaux au projet visible.
| REST | MCP | Parameters |
|---|---|---|
GET /api/thumbnails | list_thumbnail_projects | page, limit, search, status, favorite, deleted |
GET /api/thumbnails/:projectId | get_generation | summary?, page?, limit?, status? |
PATCH /api/thumbnails/:projectId | update_thumbnail_project | projectName |
GET /api/thumbnails/results | list_generations | page, limit, favorite, projectId |
PUT /api/thumbnails/:projectId/favorite | set_project_favorite | isFavorite |
PUT /api/thumbnails/jobs/:jobId/favorite | set_generation_favorite | isFavorite |
DELETE /api/thumbnails/:projectId | trash_thumbnail_project | projectId |
POST /api/thumbnails/:projectId/restore | restore_thumbnail_project | projectId |
DELETE /api/thumbnails/jobs/:jobId | trash_generation | jobId |
POST /api/thumbnails/jobs/:jobId/restore | restore_generation | jobId |
GET /api/thumbnails/trash | list_trash | kind=projects / jobs, page, limit |
json
{"favorite":true,"page":1,"limit":20}Essais, itération et relance
POST /api/thumbnails/:projectId/start et start_generation conservent le même projet. Paramètres facultatifs : prompt, personId (null efface), presetKey, templateId, styleReferenceUrl, youtubeUrl, sourceResultId, contentImages ([] efface), title ("" efface) et advancedOptions. Les champs omis reprennent les réglages du projet ; les options fusionnent. Ces changements concernent uniquement cet essai, pas le projet enregistré. Fournir une seule source (preset, template, URL, YouTube ou résultat). Chaque image de contenu contient exactement un userImageId ou url ; les URL explicites doivent appartenir au chemin de stockage configuré de vos imports. Importer les images externes avant utilisation.
Lire jobs[].results[].id dans le détail du projet, puis passer cet identifiant dans sourceResultId pour itérer sur cette image exacte. Elle doit provenir d'un job terminé, visible, du même projet. Une référence sélectionne le mode normal ; un preset, le mode magique. Les projets et résultats supprimés sont refusés.
json
{"projectId":"<project-id>","sourceResultId":"<result-image-id>","prompt":"Garde cette composition et éclaircis le fond","advancedOptions":{"variations":1}}POST /api/thumbnails/jobs/:jobId/retry / retry_generation({jobId}) accepte uniquement un job Default échoué. Il crée un nouvel essai facturé dans le même projet, en conservant prompt, images d'entrée, personnes, titre, preset et options de l'essai échoué. Il ne réinitialise pas l'ancien job et ne reprend pas les réglages actuels du projet. Les métadonnées portent retryOfJobId. Chaque appel consomme de nouveaux crédits : l'opération n'est pas idempotente. Le succès renvoie jobId, projectId, status, creditsConsumed seulement après confirmation du lancement. Un échec synchrone rembourse et marque le job orphelin échoué.
Aide au prompt
POST /api/thumbnails/prompts/improve / improve_prompt : prompt et context facultatif avec axes (composition, hook, readability), language (fr, en, es), personName, title, customInstruction, hasStyleReference, referenceTokens (@image1...), sketchTokens (@sketch1...).
POST /api/thumbnails/prompts/from-reference / prompt_from_reference : une seule source parmi assetId, templateId publié ou privé créé par vous, projectId + sourceResultId, ou imageUrl dont l'appartenance aux imports de l'appelant est prouvée. language facultatif, en par défaut. Les URL arbitraires sont refusées : importer d'abord. Les références sont autorisées dans l'organisation sélectionnée avant facturation.
Les deux renvoient {prompt, creditsConsumed: 0.5}, sans créer de projet ni d'image. Un échec fournisseur rembourse une fois. MCP exige mcp:generate et la génération activée. Le plafond quotidien compte exactement les demi-crédits ; changer d'outil ne permet pas de le contourner. Les plafonds entiers existants gardent leur signification.
Ressources : personnes, imports et catalogue
Toutes les opérations utilisent l'identité connectée. Un asset stocké doit appartenir à l'organisation sélectionnée et être le vôtre ou partagé avec elle. Les imports restent non publiés et sont retrouvables. Un ID absent ou inaccessible renvoie 404 ; un refus de permission 403 ; une entrée invalide 400. Le MCP renvoieisError: true pour les erreurs. Ces opérations de gestion ne consomment aucun crédit.
| REST | MCP | Paramètres / effet |
|---|---|---|
PATCH /api/persons/:id | update_person | name? (1–100), description? (max 500) ; null efface la description ; au moins un champ |
DELETE /api/persons/:id | delete_person | Supprime le profil et ses associations ; conserve les images stockées |
DELETE /api/persons/:id/images/:imageId | remove_person_image | Détache cette association existante, sans supprimer l'asset |
PUT /api/persons/:id/default | set_default_person | Défaut de l'organisation, idempotent ; conserve les permissions de propriété |
GET /api/assets/:id | get_asset | UUID d'un asset stocké autorisé |
GET /api/templates/:id | get_template | Template du catalogue publié ou privé créé par vous |
mcp:assets et le droit Images et personnes actif. Les lectures demandent mcp:read et Lecture actif. Les paramètres MCP sont personId, imageId, assetId ou templateId à la place des segments de chemin. Lecture/modification d'une personne renvoie son profil avec images et imageCount ; suppression renvoie {"deleted":true}. Création et ajout de photos vérifient aussi chaque image avant toute écriture.
Retrouver les imports
GET /api/assets / list_assets accepte type (face, template, bucket), search, isPublished, page (1 par défaut), limit (20, max 100). Sans type, liste les images face/template stockées. Recherche sur nom/description ; visibilité et filtres appliqués avant pagination et comptage. Chaque asset stocké porte isPublished, ownerScope: "organization". Pagination : page, limit, total, totalPages, hasMore.
type=bucket liste le dossier temporaire personnel de l'appelant, commun à ses organisations. Chaque résultat porte ownerScope: "user", id: "", fileKey stable, url et isFavorite. Utiliser contentImages: [{"url": "URL_RENVOYÉE"}] pour générer ; get_asset et userImageId exigent un UUID d'asset persisté, jamais une clé bucket. favorite=true sélectionne les favoris, favorite=false les exclut ; sans filtre, les deux sont inclus. search recherche les noms de fichier. Réservés au bucket, sortBy=name|createdAt et sortOrder=asc|desc valent par défaut createdAt descendant. Les dates absentes ou invalides restent createdAt: null et sont placées en fin dans les deux sens ; les égalités sont départagées par fileKey ascendant. Ces trois filtres bucket sont refusés pour les autres types ; isPublished est invalide pour le bucket.
Le service parcourt tous les fichiers correspondants par lots de 100, déduplique les chemins et exclut les non-images/marqueurs avant filtrage des favoris, tri et pagination publique. total compte les images filtrées, totalPages = ceil(total / limit) et hasMore indique une page suivante. Une liste vide a des totaux de 0 ; une page hors borne est vide. Les favoris orphelins ne créent aucun asset. Chaque requête énumère le dossier correspondant : un gros dossier demande davantage d'appels stockage ; les changements concurrents ne constituent pas un snapshot atomique. Toute erreur d'une page fournisseur fait échouer la requête, sans succès partiel. Pas de suppression temporaire par /api/assets/:id.
Exemple : GET /api/assets?type=bucket&search=logo&favorite=true&sortBy=createdAt&sortOrder=desc&page=1&limit=20 ou MCP list_assets({"type":"bucket","search":"logo","favorite":true,"sortBy":"createdAt","sortOrder":"desc","page":1,"limit":20}).
Trois espaces d'identifiants
GET /api/templates / list_templates recherche titre, description et tags du catalogue via search. scope=public (défaut) liste les templates publiés ; scope=mine seulement vos créations, publiées ou privées. isPublished=false exige scope=mine. category, isFeatured, page, limit restent disponibles. Réponse : templates et pagination (page, limit, total, totalPages).
Un UUID du catalogue va dans templateId. Une référence importée se retrouve avec list_assets(type="template") : son URL va dans styleReferenceUrl, son UUID dans un userImageId de contenu ou un assetId d'aide au prompt. Un fichier temporaire utilise son URL. Ne pas mélanger IDs de catalogue, IDs d'assets et clés de fichiers.
bash
curl "$BASE/api/assets?type=template&search=studio&page=1&limit=20" -H "x-api-key: $YOUTHUMB_API_KEY"
curl "$BASE/api/templates?scope=mine&isPublished=false&search=studio" -H "x-api-key: $YOUTHUMB_API_KEY"
curl -X PATCH "$BASE/api/persons/$PERSON_ID" -H "x-api-key: $YOUTHUMB_API_KEY" -H "Content-Type: application/json" -d '{"description":null}'Exploration compacte et compteurs explicites
Pour explorer ou suivre une génération, préférezget_generation({projectId, summary:true, page:1, limit:5}) ou GET /api/thumbnails/:projectId?summary=true&page=1&limit=5. summary=true applique page 1 et limit 20 par défaut (1–100) ; status accepte toujours plusieurs statuts séparés par des virgules. La réponse contient projectId, projectName, status, isFavorite, le summary global du projet, pagination et des jobs limités à jobId, status, type, isFavorite, userPrompt, generatedFileUrl, createdAt. Métadonnées, images embarquées et personnes sont omises. Les prompts restent complets : aucune taille maximale en octets n’est garantie. Suivez pagination.hasMore. Pour obtenir les IDs des images nécessaires à sourceResultId, demandez une page détaillée bornée avec summary:false.
Sans summary, ou avec false, le contrat détaillé historique est conservé, y compris les lectures non bornées avec status seul. list_generations / GET /api/thumbnails/results expose désormais le userPrompt complet (ou null) par job, sans appel au détail.
get_credits / GET /api/usage ajoute counts.activeGenerationProjects (projets non supprimés, tous types) et counts.completedThumbnailJobs (jobs terminés non supprimés de projets miniatures visibles, même périmètre que list_generations sans filtre). Ces compteurs sont propres à l’organisation : projets et jobs, pas images ni crédits consommés. Les statistiques historiques generations comptent toujours des projets ; generations.total égale counts.activeGenerationProjects. Crédits et anciens compteurs restent inchangés.
Les favoris projet (generation_project), job (generation_job) et fichier bucket personnel sont distincts. list_thumbnail_projects({favorite:true}) peut normalement renvoyer zéro malgré de nombreux jobs favoris : ce filtre ne sélectionne pas les projets contenant simplement un job favori. Si summary, page, limit ou search des assets sont absents des paramètres disponibles, actualisez/reconnectez le client MCP et rechargez sa liste d’outils. La mise à jour du skill seule ne rafraîchit pas les schémas en cache.