Algovate/agnes-image

Agnes Generación de Imágenes

agnes-img es un envoltorio de agnes image generate: los mismos parámetros, con soporte adicional para el modelo 2.5 y degradado automático. Actualmente 2.5 (agnes-image-2.5-flash) es el predeterminado, y 2.1 (agnes-image-2.1-flash) actúa como opción de degradado y compatibilidad.

Verificación Previa

agnes key status

• "status": "missing" indica que no se ha configurado una clave. Indica al usuario que vaya a https://platform.agnes-ai.com para generar una API Key, y luego ejecute agnes key set <KEY> (para escribir en la configuración local) o establezca la variable de entorno AGNES_API_KEY.
• No inventes una clave ni la incluyas en archivos del proyecto o en el cuerpo de la respuesta.

Selección de Modelo

Necesidad	Uso
Predeterminado (entrega oficial)	Sin pasar nada → agnes-image-2.5-flash
Especificar 2.1	--model 2.1
Cambiar predeterminado	Variable de entorno AGNES_IMAGE_MODEL=2.1
Desactivar degradado automático	--no-fallback (o AGNES_IMAGE_FALLBACK=0)

• Prioridad: --model > AGNES_IMAGE_MODEL > predeterminado 2.5.
• Cuando 2.5 devuelve un error 5xx, se reintenta automáticamente con 2.1 una vez; stderr mostrará role=fallback; en la respuesta debes indicar el modelo realmente utilizado.
• stderr siempre imprime generated with <model>, usa esto para etiquetar el modelo en la respuesta.

Texto a Imagen

agnes-img --prompt "Descripción" --size 2K

• En caso de éxito, stdout contiene solo la URL de la imagen; el nombre del modelo, ID de tarea, información de degradado o errores van a stderr.
• --size admite los niveles 1K / 2K / 3K / 4K, y también valores exactos como 1024x768 (predeterminado 1024x768).
• Los niveles usan relación 1:1 por defecto; para relaciones 16:9, 9:16, etc., pasa las dimensiones nativas correspondientes, por ejemplo 16:9 usa 1312x736 (1K) o 2624x1472 (2K), 9:16 usa 736x1312.

Imagen a Imagen y Composición Múltiple

agnes-img --prompt "Cambia a una escena nocturna cyberpunk" --image ./ref.png
agnes-img --prompt "Fusiona estas dos imágenes de referencia en un póster" --image ./a.png --image ./b.png

• --image se puede repetir; admite rutas locales, URLs públicas o Data URIs; los archivos locales se convierten automáticamente a Data URI.
• Al modificar imágenes, las instrucciones que dicen "conserva esto, cambia aquello" dan mejores resultados.

Guardado y Visualización (Obligatorio)

Las URLs son temporales, deben descargarse al workspace:

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

• Verifica que el archivo no esté vacío (file / tamaño > 0) antes de entregarlo.
• Usa read_image para previsualizar la imagen final; en la respuesta, muéstrala con ![Descripción](output/xxx.png) o usa present según sea necesario.

Convenciones de Directorio de Salida (Obligatorio)

output/                       Imágenes de entrega, conservadas permanentemente
  <tema>.png                  Imagen principal del tema, por ejemplo eagle-hare.png
  <tema>-<variante>.png        Otra variante de entrega del mismo tema, por ejemplo eagle-hare-ink.png
output/drafts/               Borradores intermedios / versiones reemplazadas, se pueden limpiar tras 7 días
  <tema>-<variante>-<YYYYMMDD-HHMM>.png

Reglas:

1. Las imágenes de entrega se colocan directamente en output/<tema>.png; el nombre usa minúsculas con guiones, semántico en inglés, sin sufijos temporales como -v2, -final, -copia.
2. Las imágenes antiguas reemplazadas por una nueva versión, después de confirmar la nueva entrega, se mueven con mv a output/drafts/<tema>-<timestamp>.png, no deben permanecer en output/ para evitar confusiones.
3. Los borradores de prueba no destinados a entrega (pruebas de composición, parámetros) se escriben directamente en output/drafts/.
4. La limpieza siempre se hace con agnes-gc, nunca borres manualmente todo output:

agnes-gc              # Vista previa: drafts con más de 7 días
agnes-gc --apply      # Ejecutar
agnes-gc --all        # Vista previa: vaciar drafts

agnes-gc solo actúa sobre directorios llamados drafts; las imágenes de entrega en output/ nunca son eliminadas por él.

Preguntas Frecuentes

• {"ok":false,"error":{"type":"auth",...}}: La clave no está configurada o ha caducado, primero ejecuta agnes key status.
• type: "validation": Parámetros no válidos (por ejemplo, modelo no soportado, falta --prompt), corrígelos según el hint y no reintentes ciegamente.
• Error 5xx en 2.5: se degradará automáticamente a 2.1; si stderr muestra role=fallback, significa que esta es una salida degradada, indícalo en la entrega.
• La generación suele tomar de 10 a 60 segundos; establece el timeout de Bash al menos en 180000 ms.
• Ejecuta solo una tarea de generación a la vez, evita concurrencia para no exceder la cuota.

Notas de Compatibilidad

El antiguo agnes image generate sigue disponible, pero su --model solo acepta agnes-image-2.1-flash / agnes-image-2.0-flash, no soporta 2.5. Cuando necesites 2.5 o degradado automático, usa siempre agnes-img.