buzz77/buzz-image

¿Qué hace buzz-image?

Genera y edita imágenes con GPT Image a través de la pasarela BUZZ a la que está conectado este Claude Code. Reutiliza la propia clave BUZZ de Claude Code; no es necesario instalar ni configurar nada más. Usa siempre el script incluido — nunca escribas tus propias llamadas API para imágenes, y nunca busques ni imprimas claves API.

Responde al usuario en el idioma que use.

Ejecución del script

Siempre pasa timeout: 600000 (una imagen normalmente tarda entre 30 y 90 segundos; las imágenes grandes o de alta calidad tardan más).

Si tienes una herramienta Bash, úsala. Esta forma exacta del comando está pre-aprobada:

bash ${CLAUDE_SKILL_DIR}/scripts/gen.sh -p "PROMPT" -o RUTA [opciones]

De lo contrario, usa la herramienta PowerShell (típica en Windows). Llama a la ruta del script directamente como primera palabra — sin &, sin comillas alrededor de la ruta, sin proceso powershell anidado, nada encadenado antes o después — para que coincida con la forma pre-aprobada:

${CLAUDE_SKILL_DIR}/scripts/gen.ps1 -Prompt "PROMPT" -Out RUTA [-Size ..] [-Quality ..] [-Background ..] [-Format ..] [-N ..] [-Ref a.png,b.png] [-Mask m.png] [-Model ..]

Si Claude Code aún pide al usuario que apruebe el comando, está bien — espera la aprobación; nunca busques soluciones alternativas.

Opción	Valores
-p	Descripción de la imagen (obligatorio). Escríbela tú mismo a partir de la solicitud del usuario.
-o	Ruta de salida. Elige una que se ajuste al uso (ej. public/favicon.png, assets/og.png); de lo contrario, colócala en generated/. Los archivos existentes nunca se sobrescriben (se añade -2, -3…).
-s	WxH exacto (cualquier tamaño, ej. 32x32, 1200x630) o square / landscape / portrait / wide / tall / 2k / 4k. Los tamaños que el modelo no puede producir directamente se generan cercanos y se recortan/redimensionan localmente al tamaño exacto. Omítelo para que el modelo decida.
-b	transparent para recortes/pegatinas/iconos sin fondo (solo png o webp); opaque; auto.
-q	low / medium / high / xhigh / max. Omítelo a menos que el usuario lo pida o el activo necesite detalles finos.
-f	png (predeterminado) / jpeg / webp.
-n	Número de imágenes, predeterminado 1.
-r	Imagen de origen/referencia; repite para varias. Cualquier -r cambia al modo de edición.
--mask	Máscara PNG para ediciones locales (transparente = repintar); necesita -r.
-m	Modelo. Omítelo para que el script seleccione automáticamente el mejor disponible para la clave del usuario.
--models	Lista los modelos de imagen disponibles para esta clave, sin generar.

El script imprime una línea JSON. Éxito: {"ok":true,"model":..,"files":[..],"size":..,"generated_size":..,"resized":..,"seconds":..}. Fallo: {"ok":false,"code":..,"message":..}.

Flujo de trabajo

1. Comprende la solicitud: para qué es la imagen, dónde va, texto exacto a renderizar, tamaño, transparencia. Si falta algo esencial, haz una pregunta breve; de lo contrario, continúa.
2. Usa referencias reales, nunca inventes activos de marca.
   • Si el usuario nombra o adjunta imágenes ("como esta captura de pantalla", "usa nuestro logo", "coincide con este estilo"), pásalas todas con -r.
   • Si la imagen debe mostrar o coincidir con la marca/producto del usuario (logo, tarjeta OG/social, banner, favicon, icono de aplicación, cualquier cosa con el nombre del producto), busca primero los activos existentes del proyecto — ej. archivos llamados logo*, icon*, favicon*, brand*, og* en public/, assets/, static/, src/assets/, images/, y el logo referenciado en el HTML/manifest — y pasa la(s) mejor(es) coincidencia(s) con -r, describiendo en el prompt cómo usarlas ("usa el logo de la imagen de referencia exactamente como está, no lo redibujes").
   • Si no se encuentra nada adecuado, pide al usuario su logo/referencia en lugar de inventarlo. Solo diseña un nuevo logo cuando el usuario lo solicite explícitamente.
   • Las imágenes de referencia deben ser png, jpeg o webp; si un logo existe solo como SVG, informa al usuario y pídele una exportación PNG (o continúa sin ella solo si él acepta).
3. Escribe el prompt a partir de la descripción del usuario (y del contexto del proyecto, como colores de marca). Mantén la intención del usuario y el texto exacto; no añadas cosas que no haya pedido. A menos que el usuario lo solicite, indica al modelo que no incluya logotipos, marcas comerciales o marcas de terceros (a los modelos les gusta decorar imágenes técnicas con logotipos de empresas conocidas).
4. Cantidad: genera 1 imagen a menos que el usuario pida más. Antes de generar más de 4 de una sola vez, pide confirmación al usuario.
5. Modelo: deja que el script elija a menos que el usuario nombre uno. Informa al usuario qué modelo se usó. Sugiere gpt-image-2.5-sunburst para ediciones, trabajos con muchas referencias o texto denso/preciso cuando esté disponible; cambia de modelo cuando el usuario lo pida.
6. Ejecuta el script.
7. Revisa el resultado: Lee cada imagen de salida una vez. Informa al usuario: ruta(s) de archivo(s), modelo, tamaño final, qué imágenes de referencia se usaron y cualquier cosa que no coincida con la solicitud (texto mal escrito, logo alterado, diseño incorrecto, fondo no transparente…), con una sugerencia concreta. No regeneres por tu cuenta — el usuario decide.
8. Muestra: si el usuario quiere verlo, ábrelo con el visor del sistema (open en macOS, start "" <archivo> en Windows, xdg-open en Linux).
9. Cambios: aplica lo que pida el usuario — regenera con un prompt ajustado, o edita el resultado anterior con -r <archivo anterior>. Al editar, pasa -s con el tamaño de la imagen de origen para que el resultado mantenga sus dimensiones (a menos que el usuario quiera un tamaño diferente). Nunca sobrescribas el original; escribe un nuevo archivo.
10. No hagas git add de las imágenes generadas a menos que el usuario lo pida.

Errores (code en el JSON)

código	Qué decir al usuario / hacer
not_buzz	Este Claude Code no está conectado a BUZZ, por lo que buzz-image no puede ejecutarse. Detente.
no_key	No hay clave API en la configuración de Claude Code. Detente.
no_image_model	El grupo de la clave del usuario no tiene ningún modelo GPT Image; cambia el grupo de la clave en la consola de BUZZ (página de claves API) a uno que incluya modelos gpt-image. Detente.
model_unavailable	Ese modelo no está disponible para la clave del usuario; muestra available_models y deja que elija.
insufficient_balance	Saldo insuficiente; recarga en la consola de BUZZ. Detente.
content_policy	Transmite el mensaje; deja que el usuario decida cómo reformular. No reformules y reintentes por tu cuenta.
timeout	Informa al usuario que se agotó el tiempo de espera. No reintentes automáticamente (la imagen puede ya haberse facturado); ofrece reintentar.
http_error / bad_args	Informa del mensaje. Corrige tus propios errores de argumentos; no entres en bucle.

Nunca cambies de modelo ni sigas reintentando por tu cuenta después de un error.