funi-ai/youtube-thumbnail

Miniature YouTube

Miniatures et couvertures jugées à la taille où les gens les voient réellement : environ 160 px de large dans un fil d'actualité. Un titre, trois concepts différents, l'utilisateur choisit, un final, des révisions étroites, des fichiers à la taille de livraison exacte. Le savoir-faire (cadres conceptuels, plan de prompt, règles de texte, le filtre de la petite taille) se trouve ici ; les mécanismes se trouvent dans references/cli-contract.md et references/platform.md.

Étape 0 — Pré-vol

Une fois par session :

command -v genmedia
python3 "${CLAUDE_SKILL_DIR}/scripts/gm.py" preflight
python3 "${CLAUDE_SKILL_DIR}/scripts/thumbcheck.py" tools

• blockers non vide, CLI manquant ou plus ancien que 0.7.0 → /genmedia-skills:setup. Clé manquante → l'utilisateur exécute genmedia setup ou exporte FAL_KEY lui-même ; attendre. Ne jamais lire, imprimer, demander ou taper une clé.
• Garder config.announce_above_usd et config.confirm_above_usd (par défaut 0.50 et 2) : ce sont les seuils de la porte de coût.
• thumbcheck.py tools indique lesquels de preview, sheet, fit, frame peuvent s'exécuter ici (nécessite un ffmpeg local ou macOS sips), et si lockup le peut (nécessite un navigateur de la famille Chromium). Ni l'un ni l'autre présent → la porte dégradée à l'étape 6 du flux de travail. Ne jamais compter sur drawtext, Pillow ou ImageMagick : le texte est rendu par le modèle.
• Reprendre d'abord : un .genmedia/projects/<slug>/thumbnail.md qui correspond à cette requête → le lire, continuer à sa première étape ouverte. Ne jamais redémarrer un projet qui a des entrées de registre.

Règles UX

1. Répondre dans la langue de l'utilisateur (turc entrant → turc sortant). Rédiger les prompts du modèle en anglais ; le texte sur l'image reste dans la langue et l'orthographe exacte avec lesquelles il sera publié. Les ID de point de terminaison, les noms de champs et les chemins restent tels quels.
2. Pas de JSON, ID de requête, prompts ou narration d'outil dans le chat. Attendre en silence ; au plus une ligne de statut par lot.
3. Budget de questions : 2, une à la fois, sous forme d'options étiquetées, seulement lorsque la réponse manque :
   • Q1 les mots d'accroche : pas de titre et pas de sujet → demander le titre. Titre connu → ne pas demander ; écrire les 2 à 4 mots d'accroche vous-même (trois différents selon les concepts).
   • Q2 visage ou pas : demander seulement si rien ne le décide. Une photo, un @handle ou "mon / mon visage / ben" → visage. "Sans visage", un produit, un enregistrement d'écran, un paysage → pas de visage. L'utilisateur demande une seule miniature ou nomme le concept → une ébauche au lieu de trois ; le choix devient un oui ou non. Tout le reste est une valeur par défaut que vous indiquez dans la ligne de livraison : format 16:9 ; langue du texte = la langue du titre ; palette = les couleurs de la marque données, sinon choisies par concept ; aspect photo-réaliste d'affiche ; 3 concepts ; master final 2560x1440 livré en 1920x1080 et 1280x720. Non comptés : la confirmation de consentement, le choix, une confirmation de coût.
4. Le choix est un arrêt brutal. Afficher la feuille de comparaison et attendre. Le silence, un travail réussi ou votre propre préférence n'est jamais un choix. Recommander l'un d'eux est autorisé ; choisir ne l'est pas.
5. Véracité. Une miniature peut dramatiser, jamais déformer. Tout ce qui est montré ou écrit doit être dans la vidéo ou en découler honnêtement : pas de chiffres, résultats, réactions, produits ou invités inventés ; pas de fausse UI d'une plateforme réelle ; pas de logos ou personnages que l'utilisateur ne possède pas. Impossible de dire ce que la vidéo apporte → demander avant de le promettre (cela remplace Q1 ou Q2, n'ajoute pas une question).
6. Visages. Une photo d'une personne réelle (l'utilisateur inclus) → une confirmation qu'il a le consentement de cette personne, et une ligne indiquant que les téléchargements reposent sur des URL publiques. Jamais une célébrité ou une personnalité publique que l'utilisateur n'est pas ; "ressemble à <personne célèbre>" est refusé, proposer un visage inventé ou un concept sans visage. Un visage inventé est un substitut : ne jamais le présenter comme une personne réelle nommée, un client, un expert ou un invité, et dire dans la livraison que le visage est généré par IA.
7. Coût : estimer l'ensemble de la requête avant le premier appel payant (étape 4 du flux de travail) et appliquer la porte avec les seuils du pré-vol : en dessous de announce_above_usd → exécuter ; jusqu'à confirm_above_usd → une ligne avec l'estimation, puis exécuter ; à ou au-dessus → montrer l'estimation et attendre un oui explicite (references/platform.md section 8). Une approbation couvre le plan présenté ; un plan plus large nécessite un nouveau. Ne jamais citer un prix de mémoire ; ne jamais échanger un modèle nommé par l'utilisateur pour économiser de l'argent.
8. Limité : au plus 3 tours d'ébauche et 3 tours de révision ; chaque tentative change quelque chose ; un rejet de politique de contenu n'est jamais renvoyé inchangé ; un travail avec un ID de requête est repris, jamais soumis à nouveau.

Garde-fou de découverte

Le routage ci-dessous est un cache daté (references/routing-image.md, vérifié le 2026-09-19). Avant le premier appel payant à un point de terminaison dans une session :

genmedia models --endpoint_id <endpoint_id> --json
python3 "${CLAUDE_SKILL_DIR}/scripts/gm.py" schema <endpoint_id>

• status doit être active. Pas actif ou 404 → niveau suivant de la même tâche dans references/routing-image.md, sinon genmedia models "<name>" --no-classify --limit 10 --json, correspondance active la plus récente, et dire quel modèle a exécuté.
• Les noms de champs, énumérations et limites proviennent du schéma, jamais de la mémoire. L'utilisateur nomme un modèle → rechercher avant de douter ; les nouvelles versions se trouvent sous les espaces de noms des fournisseurs (openai/, bytedance/, google/, alibaba/), pas fal-ai/.
• Ne jamais genmedia run sans un ID de point de terminaison (le routage intelligent résout les paramètres par défaut obsolètes).

Routage

Étape	Point de terminaison	Pourquoi
Ébauches, rien à référencer	openai/gpt-image-2.5/flare/text-to-image, quality: "medium"	leader en typographie ; seule la famille cible peut prévisualiser le texte, un modèle d'ébauche bon marché ne le peut pas
Ébauches avec une photo de visage, références @handle, photo de produit ou image vidéo	openai/gpt-image-2.5/flare/edit, quality: "medium"	les références vont dans image_urls (max 16) ; même famille que le final
Final	openai/gpt-image-2.5/sunburst/edit, quality: "high"	niveau de précision ; l'ébauche choisie est l'image 1, donc le final est cette composition, pas un nouveau tirage
Révision (texte, expression, arrière-plan, couleur)	openai/gpt-image-2.5/sunburst/edit, quality: "high"	le final actuel est l'image 1 ; une portée par tour
Plaque sans texte, photo-réaliste (voie alternative)	bytedance/seedream/v5/pro/text-to-image	arène #1 photo-réaliste ; le texte est ajouté ensuite avec une édition GPT Image 2.5
Plaque d'identité lorsque le visage dérive	fal-ai/nano-banana-2/edit	routage par défaut pour les images cohérentes en identité ; texte ajouté ensuite
Agrandir une image réelle ou une photo	fal-ai/seedvr/upscale/image ; visages ou texte d'abord : topaz/upscale/image/precision	fidèle ; Topaz a des modèles Faces et Text Refine
Image de la vidéo de l'utilisateur	thumbcheck.py frame (ffmpeg local)	horodatage exact ; pas de ffmpeg → demander une capture d'écran à l'utilisateur
Logo propre de l'utilisateur sur une plaque sans texte	thumbcheck.py lockup (navigateur local)	la marque est placée à partir du fichier de l'utilisateur ; un modèle la redessinerait

Critères de départage :

1. Texte sur l'image → GPT Image 2.5, même pour un concept photo-réaliste. Pas de texte du tout (l'utilisateur l'a dit) → les ébauches peuvent s'exécuter sur bytedance/seedream/v5/pro/text-to-image ou son /edit ; le reste du flux est inchangé. Seedream rejette 1280x720 (sa surface minimale est 1024x1024) et n'a pas de champ quality : envoyer image_size 1920x1080 (9:16 → 1080x1920, 1:1 → 1536x1536) et le tarifer par image à partir de sa ligne de routage (environ USD 0.07 chacune au 2026-09-19 : trois ébauches coûtent environ USD 0.20, recalculer le total).
2. La stratégie de texte par défaut est intégrée en un seul passage. Utiliser la voie de la plaque (plaque sans texte, puis une édition "ajouter seulement ce texte") lorsque : la même plaque a besoin de plusieurs langues ou formulations A/B ; un signe diacritique a échoué deux fois ; la plaque est une image réelle ou une photo. Détails : references/text-and-readability.md.
3. @handle → lire .genmedia/characters/<handle>/character.json (ancre description ; refs[] avec role: "face" et active: true), réutiliser l'cdn_url d'une référence lorsqu'elle en a une, sinon télécharger son fichier ; utiliser l'ancre textuellement. real_person: true → règle UX 6 s'applique ; un consent_confirmed_at enregistré est la confirmation. Handle inconnu → le dire, proposer /genmedia-skills:character ; ne jamais substituer.
4. L'utilisateur a nommé un modèle → l'utiliser après la vérification en direct ; proposer le défaut en une ligne.
5. Le design est une plaque plus le logo propre de l'utilisateur (une chaîne de marque, une vidéo de prévisualisation d'une application) → voie de la plaque, puis thumbcheck.py lockup place le fichier logo centré à une part de la largeur (references/text-and-readability.md section 2b). La plaque existe déjà (une plaque launch-graphics, la photo de l'utilisateur) → pas d'appel payant : lockup, porte, étape 10. Pas de fichier logo → le demander ; ne jamais laisser le modèle dessiner la marque.

Pièges :

• Piège de la taille automatique. Les points de terminaison d'édition définissent image_size par défaut sur auto, qui suit l'image d'entrée : une photo de visage en portrait donne une miniature en portrait. Toujours envoyer {width,height}.
• Piège de la qualité par défaut. quality par défaut sur high et la famille facture par tokens. Le définir sur chaque appel : medium pour les ébauches, high pour les finals ; xhigh ou max seulement après que l'utilisateur a accepté le prix.
• Piège des multiples de 16. 1920x1080 n'est pas une taille légale pour GPT Image. Rendre 1280x720, 2560x1440 ou 3840x2160 et laisser thumbcheck.py fit produire 1920x1080.
• Piège de l'image jointe. Un point de terminaison texte-à-image n'a pas de champ image ; il ignore la photo et facture quand même. Toute référence → le point de terminaison /edit.
• Piège du nouveau tirage. Ré-exécuter le prompt à haute qualité donne une image différente (pas de seed dans cette famille). Le final est une édition de l'ébauche choisie.
• Piège de la casse. Ne jamais laisser le modèle mettre en majuscule le turc : écrire la chaîne finale vous-même (thumbcheck.py text), entre guillemets, et la vérifier lettre par lettre.

Flux de travail

1. Prise en charge. Titre ou sujet, format (par défaut 16:9), visage ou pas, couleurs de marque, références. HEIC, AVIF, TIFF ou très grandes photos d'abord : thumbcheck.py fit <file> --max-side 2048 --out .genmedia/tmp/<name>.jpg ; Lire et télécharger cette copie. Ouvrir chaque image locale avec l'outil Lire avant de planifier (qui et quoi s'y trouve réellement décide les concepts). Une image de la vidéo de l'utilisateur : python3 "${CLAUDE_SKILL_DIR}/scripts/thumbcheck.py" frame <video> --at <secondes ou m:ss>, puis la Lire. Dépenser le budget de questions seulement comme la règle UX 3 le permet.
2. Fiche d'état. Choisir un <slug> ASCII court (eksi-maya) : c'est le label du lot, le filtre du registre, le dossier de sortie et le dossier du projet. Un libellé en langage naturel fonctionne aussi ; l'assistant plie "Ekşi maya" en Eksi-maya, et cette forme pliée devient alors le nom du dossier. Écrire .genmedia/projects/<slug>/thumbnail.md avec l'outil Écrire et le mettre à jour après chaque étape :

   # <titre> — miniature
   promesse : <une ligne : ce que la vidéo apporte réellement>
   format : 16:9 | langue du texte : <code> | visage : <aucun | chemin photo | @handle> (consentement : <oui, date | n/d>) | palette : <couleurs>
   [ ] concepts  [ ] ébauches-1  [ ] porte  [ ] choix : -  [ ] final  [ ] révisions 0/3  [ ] livré
   journal :
   - <date> ébauches-1 : 1 <cadre> "<TEXTE>", 2 <cadre> "<TEXTE>", 3 <cadre> "<TEXTE>"
   

3. Trois concepts différents. Lire references/frameworks.md. Réfléchir à au moins cinq en privé, garder les trois plus forts qui utilisent des cadres différents (pas trois variantes de couleur d'une même idée), chacun avec ses propres 2 à 4 mots d'accroche. Passer chaque accroche à travers la vérification de texte et utiliser sa chaîne upper textuellement :

   python3 "${CLAUDE_SKILL_DIR}/scripts/thumbcheck.py" text "şimdi izle" --lang tr
   

   Les mots d'accroche et les images peuvent utiliser seulement les nombres, résultats, citations, produits et invités que l'utilisateur a indiqués (titre, brief, leurs fichiers) ; le titre seul ne vous en donne pas un → utiliser une question, une accroche sans contrainte ou un concept sans texte, ou demander (règle UX 5). Rejeter tout concept qui échoue à la règle de véracité. Visage choisi → au moins deux des trois concepts le montrent. Le titre porte déjà l'accroche → un concept peut être sans texte.
4. Vérifier et tarifer. Garde-fou de découverte pour chaque point de terminaison, puis :

   python3 "${CLAUDE_SKILL_DIR}/scripts/gm.py" price openai/gpt-image-2.5/flare/edit,openai/gpt-image-2.5/sunburst/edit
   

   GPT Image 2.5 répond 1 units, ce qui n'est pas un prix. Dollars pour cette compétence : jobs x la ligne par taille, par qualité (une taille non listée → la ligne de taille supérieure suivante) du tableau GPT Image 2.5 dans references/routing-image.md (notes t2i-typography ; les lignes d'édition incluent déjà une image d'entrée) + l'allocation de référence dans references/platform.md §7 pour chaque image de référence supplémentaire. Indices datés (2026-09-19) : ébauche 1280x720 medium environ USD 0.01 ; final ou révision 2560x1440 high environ USD 0.055 ; 3840x2160 high environ USD 0.10. Travail typique complet (3 ébauches + final + 3 révisions) : environ USD 0.25 sans références, environ USD 0.45 avec une référence de visage → en dessous du seuil d'annonce par défaut, exécuter et indiquer l'estimation dans la ligne de livraison. Un deuxième tour d'ébauche, plus de références, xhigh, max, 4K, ou plusieurs vidéos dans une seule requête (un slug et une fiche d'état par vidéo ; l'estimation est la somme) → recalculer et appliquer la porte d'abord.
5. Ébauches en un lot. Télécharger les références une fois et garder les urls (ordre des arguments) ; les téléchargements sont des URL publiques, le dire une fois pour les documents privés :

   python3 "${CLAUDE_SKILL_DIR}/scripts/gm.py" upload ./me.jpg
   

   Construire chaque prompt à partir de references/prompt-blueprint.md. Écrire le plan avec l'outil Écrire dans .genmedia/projects/<slug>/drafts-1.json :

   {"label": "<slug>", "max_parallel": 3, "jobs": [
     {"id": "draft-a", "endpoint_id": "openai/gpt-image-2.5/flare/edit", "est_cost_usd": 0.02,
      "input": {"prompt": "<concept A>", "image_urls": ["<url visage>"], "image_size": {"width": 1280, "height": 720}, "quality": "medium", "num_images": 1, "output_format": "png"}},
     {"id": "draft-b", "endpoint_id": "openai/gpt-image-2.5/flare/edit", "est_cost_usd": 0.02, "input": {"prompt": "<concept B>", "image_urls": ["<url visage>"], "image_size": {"width": 1280, "height": 720}, "quality": "medium", "num_images": 1, "output_format": "png"}},
     {"id": "draft-c", "endpoint_id": "openai/gpt-image-2.5/flare/edit", "est_cost_usd": 0.02, "input": {"prompt": "<concept C>", "image_urls": ["<url visage>"], "image_size": {"width": 1280, "height": 720}, "quality": "medium", "num_images": 1, "output_format": "png"}}
   ]}
   

   Exécuter le plan :

   genmedia run .genmedia/projects/<slug>/drafts-1.json
   

   Vérifier que chaque travail a rendu une image. Les échecs partiels sont retentés en une seule nouvelle ébauche (limitée aux concepts qui ont échoué) ; un échec complet de la famille au moment de l'exécution → passer à bytedance/seedream/v5/pro/text-to-image et réessayer tout le lot (pas de texte sur l'image de tout le lot).
6. Feuille de comparaison. Copier les images de sortie dans un dossier de prévisualisation :

   python3 "${CLAUDE_SKILL_DIR}/scripts/thumbcheck.py" sheet .genmedia/projects/<slug>/drafts-1 --pixels 320 --border 1 --out .genmedia/projects/<slug>/preview.png
   

   Pas de sheet (dégradé) → montrer les URL brutes. L'utilisateur choisit un concept ; mettre à jour la fiche d'état (pick: A).
7. Rafiner le concept choisi. Si le concept choisi a un problème de composition (cadrage, expression, arrière-plan, accessoires) → une édition de réglage ponctuelle sunburst/edit. Sinon, passer à l'étape 9. Le nom du concept est une accroche : si l'utilisateur veut un thème différent, c'est un nouveau concept, pas une révision.
8. Texte sur le concept choisi. Si le concept a été choisi sans texte (concept sans texte ou plaque sans texte), ajouter le texte maintenant : voie de la plaque, sous forme d'édition sunburst/edit avec prompt "Add only this text…" dans la langue cible. Utiliser la chaîne vérifiée.
9. Final. Une édition sunburst/edit à haute qualité avec l'ébauche choisie (étape 6) comme image 1, et les références supplémentaires nécessaires à la fidélité (photo de visage, par exemple). Taille : 2560x1440 (16:9), 1440x2560 (9:16), 1536x1536 (1:1).
10. Redimensionner et livrer.

    python3 "${CLAUDE_SKILL_DIR}/scripts/thumbcheck.py" fit .genmedia/projects/<slug>/final.png --size 1920x1080 --out .genmedia/projects/<slug>/<slug>-1920x1080.jpg
    python3 "${CLAUDE_SKILL_DIR}/scripts/thumbcheck.py" fit .genmedia/projects/<slug>/final.png --size 1280x720 --out .genmedia/projects/<slug>/<slug>-1280x720.jpg
    python3 "${CLAUDE_SKILL_DIR}/scripts/thumbcheck.py" fit .genmedia/projects/<slug>/final.png --size 256x144 --out .genmedia/projects/<slug>/<slug>-256x144.jpg
    

    (16:9 ci-dessus ; 9:16 : 1080x1920 et 720x1280 ; 1:1 : 1080x1080 ; la version 256px est toujours carrée ? non, toujours proportionnelle). 256x144 et autres petites tailles sont toujours jpg (le navigateur du fil d'actualité gère le sous-échantillonnage de chrominance mieux que png à cette taille). Copier les fichiers. Dire dans la ligne de livraison "Livré en 1920×1080 et 1280×720, master conservé à 2560×1440". Le master est le fichier redimensionné le plus grand (ici 2560x1440). Un format non 16:9 : "Livré en 1920×1080 et 1280×720, master conservé à ".

Étape de fin : Fermeture

python3 "${CLAUDE_SKILL_DIR}/scripts/gm.py" ledger .genmedia/projects/<slug> --format json > /dev/null 2>&1

Lire .genmedia/projects/<slug>/thumbnail.md et confirmer que toutes les cases sont cochées. Marquer [ ] livré comme [x] et le journal comme complet. Si l'utilisateur demande une révision, la fiche log a un compte de révisions (max 3) ; l'exécuter comme un cycle final/révision. Si l'utilisateur veut une nouvelle miniature entière (nouveau titre, nouveau sujet, nouveau format) → c'est un nouveau slug.

---

Dépannage des échecs de point de terminaison

• 422 Unprocessable Entity → lire le corps de la réponse (un field manquant, une valeur invalide), le réparer à partir du schéma, réessayer.
• 401 Unauthorized → /genmedia-skills:setup.
• 400 Bad Request sur des images encodées → la photo fait plus de 16 Mo, une URL data: ou un format non supporté. Redimensionner avec thumbcheck.py fit ou (urls locales) d'abord gm.py upload.
• content_policy_violation → ne pas renvoyer le même prompt. Changer les mots, remplacer la référence ou passer à un concept sans visage/sans photo, puis réessayer.
• rate_limit_exceeded → max_parallel: 1 et réessayer ; informer en une ligne. À 3 échecs de taux, /genmedia-skills:setup.
• model_not_available ou endpoint_not_found → exécuter le garde-fou de découverte, prendre le modèle actif le plus récent de la même famille (par exemple flare / sunburst / stable-diffusion-3.5), l'indiquer et réessayer. Toutes les familles échouent → /genmedia-skills:setup.

Le coût du lot d'ébauches a été budgété ; chaque tentative suivante ajoute son coût à la ligne log de la fiche d'état.