Algovate/agnes-image

Agnes Image - Génération d'images

agnes-img est une enveloppe de agnes image generate : mêmes paramètres, avec support supplémentaire du modèle 2.5 et basculement automatique. Actuellement, le modèle 2.5 (agnes-image-2.5-flash) est le modèle par défaut, et le 2.1 (agnes-image-2.1-flash) sert de basculement et de compatibilité.

Vérification préalable

agnes key status

• "status": "missing" signifie que la clé n'est pas configurée. Demandez à l'utilisateur de générer une clé API sur https://platform.agnes-ai.com, puis d'exécuter agnes key set <CLE> (écriture dans la configuration locale) ou de définir la variable d'environnement AGNES_API_KEY.
• N'inventez pas de clé, et n'écrivez pas la clé dans un fichier du projet ou dans le corps de la réponse.

Sélection du modèle

Besoin	Utilisation
Par défaut (livraison normale)	Ne rien passer → agnes-image-2.5-flash
Spécifier 2.1	--model 2.1
Modifier le modèle par défaut	Variable d'environnement AGNES_IMAGE_MODEL=2.1
Désactiver le basculement automatique	--no-fallback (ou AGNES_IMAGE_FALLBACK=0)

• Priorité : --model > AGNES_IMAGE_MODEL > par défaut 2.5.
• En cas d'erreur 5xx avec le modèle 2.5, une nouvelle tentative est automatiquement effectuée avec le modèle 2.1 ; la sortie stderr affiche role=fallback ; la réponse doit indiquer le modèle réellement utilisé.
• La sortie stderr affiche toujours generated with <model> ; utilisez cette information pour indiquer le modèle dans la réponse.

Texte → Image

agnes-img --prompt "description" --size 2K

• En cas de succès, la sortie stdout ne contient que l'URL de l'image ; le nom du modèle, l'ID de la tâche, les informations de basculement et les erreurs passent par stderr.
• --size supporte les niveaux 1K / 2K / 3K / 4K, ainsi que des valeurs précises comme 1024x768 (par défaut 1024x768).
• Les niveaux sont par défaut au format 1:1 ; pour des formats 16:9, 9:16, etc., passez les dimensions natives correspondantes, par exemple 16:9 avec 1312x736 (1K) ou 2624x1472 (2K), 9:16 avec 736x1312.

Image → Image et composition multi-image

agnes-img --prompt "transforme en nuit cyberpunk" --image ./ref.png
agnes-img --prompt "fusionne ces deux images de référence en une affiche" --image ./a.png --image ./b.png

• --image peut être répété ; supporte les chemins locaux, les URLs publiques ou les Data URIs ; les fichiers locaux sont automatiquement convertis en Data URIs.
• Pour la modification d'image, une invite de type "conserver quoi, changer quoi" donne de meilleurs résultats.

Sauvegarde et affichage (obligatoire)

L'URL est temporaire, vous devez télécharger l'image dans l'espace de travail :

mkdir -p output output/drafts
curl -sSL "<URL>" -o "output/agnes-$(date +%Y%m%d-%H%M%S).png"
ls -l output/*.png

• Vérifiez que le fichier n'est pas vide (commande file / taille > 0) avant de livrer.
• Utilisez read_image pour prévisualiser l'image finale ; dans la réponse, affichez-la avec ![description](output/xxx.png) ou selon les besoins avec present.

Conventions du répertoire de sortie (à respecter impérativement)

output/                       Images livrées, conservées définitivement
  <sujet>.png                 Image principale du sujet, ex. eagle-hare.png
  <sujet>-<variante>.png      Autre style de livraison pour le même sujet, ex. eagle-hare-ink.png
output/drafts/                Brouillons / versions remplacées, nettoyables après 7 jours
  <sujet>-<variante>-<AAAAMMJJ-HHMM>.png

Règles :

1. Les images livrées sont placées directement dans output/<sujet>.png ; nommez en minuscules avec des tirets, en anglais sémantique, sans suffixes temporaires comme -v2, -final, -copie.
2. Les anciennes images remplacées par une nouvelle version sont déplacées (mv) dans output/drafts/<sujet>-<horodatage>.png après confirmation de la nouvelle livraison, sans les laisser dans output/ pour éviter toute confusion.
3. Les essais non destinés à la livraison (croquis de composition, tests de paramètres) sont directement écrits dans output/drafts/.
4. Le nettoyage s'effectue exclusivement avec agnes-gc, jamais avec un rm manuel de tout output :

agnes-gc              # Aperçu : brouillons de plus de 7 jours
agnes-gc --apply      # Exécution
agnes-gc --all        # Aperçu : vider tous les brouillons

agnes-gc ne peut agir que sur un dossier nommé drafts ; les images livrées dans output/ ne seront jamais supprimées par cette commande.

Problèmes courants

• {"ok":false,"error":{"type":"auth",...}} : la clé n'est pas configurée ou est invalide. Lancez d'abord agnes key status.
• type: "validation" : paramètre invalide (par exemple modèle non supporté, --prompt manquant). Corrigez selon hint, ne relancez pas aveuglément.
• Erreur 5xx avec le modèle 2.5 : basculement automatique vers 2.1 ; si stderr affiche role=fallback, cela signifie que l'image a été générée par basculement, mentionnez-le dans la livraison.
• La génération prend généralement entre 10 et 60 secondes ; réglez le délai d'attente du shell à au moins 180000 ms.
• Exécutez une seule tâche de génération à la fois pour éviter de dépasser les limites de quota.

Notes de compatibilité

L'ancienne commande agnes image generate reste disponible, mais --model n'accepte que agnes-image-2.1-flash / agnes-image-2.0-flash et ne supporte pas le modèle 2.5. Utilisez agnes-img chaque fois que vous avez besoin du modèle 2.5 ou du basculement automatique.