gpt-image

Runbook d'agent pour la génération/édition GPT Image 2. Utilisez la bibliothèque de prompts + CLI packagée. Ne réimplémentez pas le code API image.

Boucle d'exploitation

Classifier la demande : generate, edit, inpaint, ou multi-reference ; identifier le type d'asset, le texte exact, le ratio d'aspect, les références, les contraintes de sécurité, et le budget/qualité.
Chercher les références en premier : ouvrez references/gallery.md ; chargez/cherchez le fichier references/gallery-<category>.md le plus proche. Lisez le texte réel **Prompt** avant de choisir un pattern.
Affiner avec craft : chargez references/craft.md pour texte dense, diagrammes, UI, visualisation de données, layouts multi-panneaux, prompts faibles, ou pas de correspondance gallery proche.
Conférer quand utile : avant des appels coûteux/ambigus/haute-polish, présentez 1–3 directions correspondantes plus taille/qualité prévue ; posez au maximum une question concise. Évitez longue discussion pour demandes précises "generate now".
Préflight, pas d'effets secondaires : utilisez CLI/skill existant si présent. Vérifiez disponibilité commande (command -v gpt-image), listes d'outils installés quand le gestionnaire d'outils existe, ou registre de skill du runtime quand disponible. N'assumez pas chemin home local dans runtimes cloud/hébergés.
Pas d'aveugle setup : ne réinstallez pas, n'écrasez pas dossiers skill, ne créez/modifiez pas .env, ou n'écrivez clés API sauf si l'utilisateur l'a explicitement demandé. Les installs globales/partagées sont opt-in seulement.
Exécuter via CLI uniquement : appelez gpt-image ou scripts/generate.py. Ne créez pas nouveau generate.py, wrapper SDK, ou script ad-hoc pour requêtes image normales.
Rapporter : chemins fichier(s) sortie, flags clés, et une suggestion raffinement concise si utile.

Chemin rapide : prompt précis + "generate now" explicite → vérification rapide reference/craft, puis CLI.

Résolution CLI

Ordre d'appel préféré :

# CLI existant sur PATH
gpt-image -p "PROMPT" [-f OUT] [-i REF...] [-m MASK] [options]

# Dossier skill installé ; utilisez chemin skill fourni par runtime quand disponible
uv run "$SKILL_DIR/scripts/generate.py" -p "PROMPT" [-f OUT] [-i REF...] [-m MASK] [options]

# CLI transient direct quand l'utilisateur a demandé setup/exécution CLI unique
uvx --from git+https://github.com/wuyoscar/gpt_image_2_skill gpt-image -p "PROMPT" [options]

scripts/generate.py est un lanceur : repo-local src/gpt_image_cli → installé gpt-image → PATH gpt-image → fallback transient uvx/uv.

Règles clé et coût

CLI lit OPENAI_API_KEY depuis env processus, puis .env, puis ~/.env sans écraser env existant ; appels API réussis peuvent facturer le compte OpenAI de l'utilisateur.
Si host/runtime a génération image native gérée plateforme et l'utilisateur veut ce chemin, utilisez outil host au lieu cette CLI.
Si OPENAI_API_KEY non défini, rapportez clé manquante ou utilisez génération native host si demandé ; n'écrivez pas secrets.
Si utilisateur veut éviter utilisation clé locale, respectez unset OPENAI_API_KEY ; si clé existe dans .env/~/.env, dites-leur la supprimer/renommer pour la session plutôt que contourner.
Ne printez jamais valeurs secrets.

Flags

Flag	Valeurs	Usage
`-p, --prompt`	string	Prompt/instruction édition requis
`-f, --file`	path	Chemin sortie ; auto-nommé si omis
`-i, --image`	path répétable	Utiliser endpoint édits ; supporte références multiples
`-m, --mask`	chemin PNG	Inpaint avec masque alpha ; requiert `-i`
`--model`	défaut `gpt-image-2`	Modèle image
`--size`	`1k`, `2k`, `4k`, `portrait`, `landscape`, `square`, `wide`, `tall`, ou littéral	Taille canvas
`--quality`	`low`, `medium`, `high`, `auto`	Dial coût/qualité
`-n, --n`	integer	Nombre d'images
`--background`	`auto`, `opaque`	Arrière-plan génération
`--moderation`	`auto`, `low`	Paramètre modération génération
`--format`	`png`, `jpeg`, `webp`	Encodage sortie
`--compression`	`0-100`	Compression JPEG/WebP
`--user`	string	Identifiant utilisateur final optionnel

Politique qualité :

low : brouillons bon marché, exploration large, nombreuses variantes.
medium : exploration normal, sondage style, coût équilibré.
high : assets finaux, texte chinois, posters, diagrammes, UI, figures papier, labels denses.

Politique taille :

défaut/carré social : 1k / 1024x1024
poster/mobile/beauté : portrait
paysage/gameplay/photo : landscape
impression/figure papier : 2k
héros widescreen : 4k
story/bannière vertical : tall

Routage endpoint

Mode	Déclencheur	Endpoint
Texte-to-image	pas `-i`	`/v1/images/generations`
Édition référence	une ou plusieurs `-i`	`/v1/images/edits`
Inpaint	`-i` + `-m`	`/v1/images/edits` avec masque

Surfacez erreurs API assez verbatim pour debug ; codes exit : 0 succès, 1 API/refusal, 2 mauvais args/clé manquante.

Chargement références

references/gallery.md : index routage pour Atlas Galerie Référence 162-prompts. Chargez en premier.
references/gallery-*.md : prompts concrets, aperçus, chemins, métadonnées, attribution. Chargez 1 catégorie pour requêtes normales ; 2–3 pour hybrides.
references/craft.md : checklist craft-prompt. Chargez pour réparation prompt, texte exact, grammaire UI/data/diagramme, invariants édition, et cohérence multi-panneaux.
references/openai-cookbook.md : sémantique paramètre/modèle officiel. Chargez pour questions comportement API ou capacités modèle.

Politique chargement références : chargez la plus petite tranche utile ; ne chargez jamais tous fichiers catégorie par défaut.

Vérification

Avant appel API : confirmez mode endpoint, taille, qualité, chemin sortie, et fichiers référence/masque requis.
Après appel CLI : rapportez chemin(s) printés par CLI et surfacez stderr sur failure.
Pour édits/inpaints : vérifiez chemins -i existent ; vérifiez -m existe quand utilisé.

Préservez métadonnées Curated vs Author + Source quand adaptant exemples. Ajoutez nouveaux prompts collectés à Galerie Référence avant promotion README.