shijianjizhe/remotion

codex-image

Générez et modifiez des images avec GPT Image via l'abonnement ChatGPT de l'utilisateur. Les résultats sont enregistrés dans ./generated_images/ (ou via --out-dir / --out).

Comment exécuter

Tout passe par un seul script. Résolvez le répertoire absolu contenant ce SKILL.md (votre environnement l'annonce au chargement de la compétence – ci-dessous noté <skill-dir>), puis :

bash "<skill-dir>/scripts/generate.sh" "<prompt>" [flags]

N'invoquez jamais un scripts/generate.sh relatif : votre répertoire de travail est le projet de l'utilisateur, pas le répertoire d'installation de la compétence (qui varie selon l'agent – ~/.claude/skills/, ~/.agents/skills/, ~/.opencode/skills/, un .claude/skills/ local au projet, …).

Prérequis vérifiés automatiquement par le script :

• python3 ≥ 3.10 dans le PATH (bash + stdlib Python sinon).
• Pillow – seulement pour --format webp et --transparent-mode chroma. Pas installé par défaut ; ces exécutions échouent rapidement avec la commande d'installation (python3 -m pip install 'Pillow>=10'). Le simple --transparent n'en a pas besoin. Mentionnez ce prérequis avant la première utilisation de l'une ou l'autre option.
• Codex CLI connecté. Sinon, le script se termine avec Exécutez : codex login – relayez cela à l'utilisateur plutôt que de manipuler l'authentification vous-même.

bash "<skill-dir>/scripts/generate.sh" --help affiche l'ensemble des options ; consultez-le avant d'improviser des flags. Si l'agent hôte prend en charge les commandes slash typées, /codex-image "<prompt>" --flags est un raccourci utilisateur exactement équivalent à cet appel de script.

Le script est mécanique – il n'effectue aucun routage sémantique. La gestion des continuations, les décisions par lot et l'envoi de la suppression d'arrière-plan sont VOTRE responsabilité, en fonction de la conversation.

GPT Image 2.5

OpenAI propose gpt-image-2.5-sunburst pour l'édition précise et gpt-image-2.5-flare pour une génération quotidienne plus rapide. Pour en demander un, passez --image-model <model-id> ; omettez-le pour conserver la sélection par défaut des réponses Codex. Ce flag est expérimental sur le transport par abonnement : les vérifications en direct du 2026-09-08 ont demandé chaque variante mais les deux réponses ont rapporté gpt-image-2-codex. Ne prétendez pas à une mise à niveau 2.5 suite à une simple demande réussie. Un alias de réponse hérité ou une version C2PA 2.0 ne prouve pas non plus des poids plus anciens : une image publiée dans l'annonce 2.5 d'OpenAI porte cette même version de provenance. Le script prévient lorsque le modèle rapporté diffère ou est manquant ; inspectez le image_model du fichier sidecar séparément de requested_image_model. --orchestrator sélectionne le modèle principal qui appelle l'outil image, pas Sunburst ou Flare. Ne le spécifiez pas : le script utilise le modèle Sol le plus récent (gpt-<version>-sol) que le compte liste, afin qu'un modèle retiré ne le bloque jamais. Les requêtes vont là où la configuration de Codex envoie Codex : un model_provider personnalisé tel qu'un proxy, un relais openai_base_url ou chatgpt.com.

Lisez Compatibilité GPT Image 2.5 pour le comportement de transport vérifié et les sources officielles. La prise en charge par l'API publique de la sélection de modèle, de xhigh/max et de la transparence n'établit pas le même comportement sur les réponses Codex.

Gestion des continuations

Lorsque la demande modifie l'image générée au tour immédiatement précédent (« rends-le plus foncé », « ajoute maintenant un chapeau », « plus de contraste »), passez --from-last – le script réutilise automatiquement la dernière génération (suivie dans ~/.codex-image/last.json), vous n'avez donc pas à retrouver le chemin dans la transcription.

Pour des modifications sur un fichier explicite ou une génération plus ancienne, passez --input <chemin|url> à la place (répétable ; 16 références maximum combinées avec --from-last ; la limite de référence de la compétence).

Lorsque la demande concerne un nouveau sujet – même formulée comme « maintenant fais… » – ne passez ni l'un ni l'autre et générez à partir de zéro. Si vous vous trompez et que l'utilisateur dit « non, je voulais une nouvelle », relancez sans références.

Les images fournies par l'utilisateur uniquement pour le style, la composition ou l'ambiance sont des références pour une génération, pas des cibles d'édition – passez-les via --input mais formulez le prompt comme une nouvelle image (« dans le style de l'Image 2 »). Lorsque vous mélangez plusieurs entrées, étiquetez chacune par son index et son rôle dans le prompt (Image 1 : cible d'édition, Image 2 : référence de style).

Après la génération : regardez, puis rapportez

Avant de dire à l'utilisateur que vous avez terminé, visualisez le fichier image enregistré et vérifiez-le par rapport à la demande : sujet, composition, tout texte littéral rendu textuellement, et chaque contrainte énoncée par l'utilisateur. Si quelque chose ne va pas, itérez avec UN seul changement ciblé (via --from-last), en réitérant les invariants qui ne doivent pas dériver. N'empilez pas plusieurs corrections en une seule relance, et ne rapportez pas un chemin que vous n'avez pas inspecté.

Discipline de sauvegarde : les sorties sont par défaut dans ./generated_images/. Si l'image est destinée au projet de l'utilisateur, copiez-la ou déplacez-la à son emplacement réel (et mettez à jour tout code qui la référence) – ne laissez pas un élément du projet seulement dans le répertoire temporaire. Ne remplacez jamais un élément existant que l'utilisateur n'a pas demandé à remplacer ; écrivez une version numérotée (hero-v2.png à la place).

Images transparentes

Lorsque l'utilisateur souhaite un arrière-plan transparent, ajoutez --transparent. C'est tout – pas de décision d'envoi, pas de Pillow, pas d'étape de post-traitement pour vous à orchestrer.

Le script demande directement l'alpha au modèle : il envoie background: "auto" et ajoute une phrase au prompt, et le backend retourne du RGBA. Ne passez pas --background transparent ; cette valeur est rejetée par ce backend (docs/adr/0001-request-transparency-in-the-prompt.md explique pourquoi, et pourquoi la « correction » évidente est erronée).

Si vous testez le backend vous-même et voyez « L'arrière-plan transparent n'est pas pris en charge pour ce modèle. », ne concluez pas que la transparence est indisponible. Cette erreur 400 concerne le paramètre refusé, pas la capacité. Le modèle retourne un alpha réel lorsqu'on le lui demande dans le prompt, ce que fait --transparent. Les conseils indiquant que la transparence native nécessite gpt-image-1.5 ou une OPENAI_API_KEY sont antérieurs à la version 0.2.0 et erronés ; si vous les lisez, votre compétence installée est obsolète. Vérifiez metadata.version dans ce fichier – elle doit être 0.2.0 ou ultérieure.

Deux choses à bien faire lorsque vous écrivez le prompt :

• Décrivez le sujet, pas une scène. Le prompt prime sur le paramètre. « Une tasse sur une table en bois dans un studio ensoleillé » pourrait rendre ce studio au lieu d'isoler la tasse. Nommez le sujet et son matériau ; laissez les environs de côté.
• N'ajoutez pas vos propres interdictions. Le suffixe n'interdit délibérément rien. Si l'utilisateur a demandé une ombre portée, laissez-la lui – elle revient rendue dans l'alpha et se compose correctement. Ajouter vous-même « pas d'ombre, pas d'arrière-plan » annule son intention.

Après la génération, visualisez le fichier et vérifiez que l'alpha est bien arrivé. Le script prévient sur stderr lorsque le résultat n'a pas d'alpha ou est totalement opaque ; considérez cela comme un signal pour relancer avec UN changement ciblé, généralement en supprimant le langage de scène.

Échelle de repli, uniquement lorsque le mode natif déçoit (vérifié sur des sujets opaques ; cheveux, verre, fumée et translucidité non testés) :

Escalade	Action
Reprompt	Supprimez le langage de scène/d'arrière-plan, nommez le sujet seul
Augmenter la qualité	--quality medium pour les bords fins et les petits textes
Chroma	--transparent-mode chroma (nécessite Pillow) – vous contrôlez la plaque clé
Adobe MCP	--transparent-mode chroma --bg-tool=none, puis appelez l'outil de suppression d'arrière-plan Adobe exposé par cette session (cherchez un outil MCP dont le nom contient remove_background) et remplacez le fichier par le résultat alpha. Meilleure option pour la translucidité

Réparation des bords chroma : franges fines → --edge-contract 1 ; bords en escalier sur des sujets mats → --edge-feather 0.25. Modes de défaillance plus profonds : references/transparent-image-tips.md.

Garde-fous qualité, coût et temps

• La valeur par défaut est --quality high ; low, medium, high, xhigh, max et auto sont acceptés. Commencez par low pour les brouillons. Les réponses Codex peuvent remplacer la qualité ; inspectez resolved_quality dans le sidecar ou la sortie --verbose avant de prétendre qu'un niveau a été livré.
• Les générations sont déduites des limites du plan ChatGPT de l'utilisateur. La latence varie selon le modèle, le prompt, la qualité et la charge du service.
• Avant de générer plus de 3 images pour une seule demande, confirmez d'abord avec l'utilisateur.
• Ne bouclez jamais indéfiniment. « Beaucoup » / « tout un ensemble » → choisissez un nombre par défaut raisonnable (4) et proposez de continuer.
• HTTP 429 du backend = arrêtez immédiatement, ne réessayez pas.

Workflows courants

# Génération unique
bash "<skill-dir>/scripts/generate.sh" "un taxi jaune la nuit sous la pluie"

# Continuation de la génération précédente
bash "<skill-dir>/scripts/generate.sh" "ajoute maintenant de la vapeur qui monte" --from-last

# Modification d'une image de référence explicite
bash "<skill-dir>/scripts/generate.sh" "rends-le bleu" --input ./tasse.png

# Arrière-plan transparent (alpha natif du modèle ; pas de Pillow)
bash "<skill-dir>/scripts/generate.sh" "une tasse de café" --transparent

# Transparent, avec une ombre demandée par l'utilisateur (survit dans l'alpha)
bash "<skill-dir>/scripts/generate.sh" "une tasse de café avec une ombre portée légère" --transparent

# Repli chroma, lorsque le natif déçoit (nécessite Pillow)
bash "<skill-dir>/scripts/generate.sh" "un bocal en verre" --transparent --transparent-mode chroma

# Format / taille / qualité différents
bash "<skill-dir>/scripts/generate.sh" "bannière hero" --size 2048x1152 --format webp --quality low

Rédaction des tokens (sécurité)

N'imprimez et ne journalisez JAMAIS le access_token, id_token, refresh_token ou tout en-tête Authorization: Bearer ... de l'utilisateur. Les modules Python de la compétence les réduisent automatiquement ; vous ne devez pas annuler cela en lisant ~/.codex/auth.json vous-même ou en faisant écho aux tokens dans des messages d'erreur.

Quand NE PAS invoquer

• Art vectoriel, SVG, ASCII art ou diagrammes LaTeX → utilisez un outil vectoriel ou de diagramme dédié.
• L'utilisateur veut explicitement un modèle ou produit différent (DALL-E, Stable Diffusion, Midjourney) → déférez à celui-ci.

Pour le travail de logo/marque en production, invoquez – mais fixez les attentes : générez des explorations et affinez avec des itérations --from-last à changement unique plutôt que de promettre un actif final en une seule fois (modèles dans references/prompting-cookbook.md).

Références

Lorsque vous avez besoin de plus de profondeur, lisez dans <skill-dir>/references/ :

• api-recipe.md – corps de requête canonique, en-têtes, champs rejetés, mécanisme de transparence, analyse SSE
• prompting-cookbook.md – bases de la formulation des prompts + modèles par cas d'usage (logo, photo de produit, maquette d'interface, infographie)
• transparent-image-tips.md – comment fonctionne la transparence native, quand elle échoue, et le repli chroma

Contexte au niveau du dépôt : CONTEXT.md (glossaire – les trois transports y sont définis) et docs/adr/ (pourquoi la transparence est demandée dans le prompt plutôt que dans le paramètre).