zsio/gpt-image

CLI de GPT Image

Usa el CLI gpt-image para producir la imagen que el usuario solicitó y devolver su ruta local. Se requiere Node.js 22+. El modelo por defecto es gpt-image-2.6-flare; la calidad predeterminada es la del auto de la API. Mantén estos valores a menos que el usuario elija configuraciones diferentes.

Encontrar el CLI y la configuración

Usa un comando gpt-image instalado cuando esté disponible. De lo contrario, ejecuta el CLI directamente desde el repositorio público con npm:

npx --yes --package=github:zsio/openai-image-cli#v1.0.0 gpt-image --help

Usa el mismo prefijo en lugar de gpt-image en los ejemplos siguientes. Esto también funciona cuando la habilidad fue instalada en una máquina sin una instalación separada del CLI. No requiere un checkout ni una ruta específica de la máquina.

Verifica la configuración con gpt-image config show. Solo se requiere OPENAI_API_KEY; tamaño, modelo, calidad, formato y ubicación de salida tienen valores predeterminados. El CLI lee primero las variables de entorno, luego la configuración del usuario en ${XDG_CONFIG_HOME:-$HOME/.config}/gpt-image/.env. gpt-image config path imprime la ruta resuelta. Respeta una opción --config o GPT_IMAGE_CONFIG seleccionada explícitamente.

Si no hay ninguna clave configurada, ejecuta gpt-image config init si es necesario e indica al usuario que rellene OPENAI_API_KEY en ese archivo local. Mantén la clave fuera de los repositorios de código y archivos de habilidades; no le pidas que la pegue en el chat, que la imprima o que la ponga en argumentos de comandos. Verifica su presencia usando config show, nunca mostrando el archivo de configuración. No generes una imagen de muestra solo para verificar la configuración; usa --dry-run para una vista previa de la solicitud.

Generar o editar

Para una imagen nueva, pasa el prompt como un solo argumento. Para prompts largos o multilínea, escribe un archivo de prompt UTF-8 y usa --prompt-file.

gpt-image generate "Un gatito acuarela con bufanda roja" --name kitten --json

gpt-image generate --prompt-file ./prompt.txt --out-dir ./assets --name cover --json

Para ediciones o generación basada en referencias, usa edit y repite --image para múltiples referencias. El orden de entrada importa: la primera imagen es la imagen principal para una máscara o capa de marcado.

gpt-image edit "Cambia el fondo a montañas nevadas; conserva la cara y la ropa de la persona" \
  --image ./portrait.png --name snowy-portrait --json

gpt-image edit "Coloca ambos productos en una foto de producto con fondo blanco" \
  --image ./product-a.png --image ./product-b.jpg --name product-pair --json

gpt-image edit "Reemplaza la región enmascarada transparente con un jarrón azul" \
  --image ./room.png --mask ./mask.png --name blue-vase --json

Usa --background transparent --format png para un recorte transparente o sticker. Para ediciones de un activo transparente existente, conserva la transparencia cuando eso sea parte de la solicitud. --mask y --markup toman archivos PNG y no se pueden combinar; sus dimensiones deben coincidir con la primera imagen. Se soportan hasta 16 imágenes de referencia, incluyendo PNG/JPEG/WebP locales, URLs de imágenes e IDs de archivos de OpenAI.

El prompt debe conservar el sujeto del usuario, el texto exacto solicitado, el estilo y las restricciones. Para una edición, indica tanto el cambio deseado como los detalles a conservar. No cambies silenciosamente la cantidad de imágenes solicitadas, el modelo ni la calidad. Cada invocación del CLI genera una imagen final; los reintentos están desactivados, así que inspecciona los fallos antes de decidir si otra solicitud facturable está justificada.

Salida y opciones útiles

• La salida predeterminada es una carpeta única name-YYYYMMDD-HHmmss-SSS-suffix en el directorio temp del sistema. Usa --name para un nombre de archivo corto útil.
• Usa --output FILE para una ruta de archivo exacta, o --out-dir DIR --name NAME para un directorio de destino. Estas alternativas no se pueden combinar. Los archivos de salida existentes se conservan.
• Usa --json para leer image_path, metadata_path, prompt_path, request_id y uso de la API. El progreso va a stderr. Devuelve la ruta real de la imagen guardada; previsualiza la imagen con un visor de imágenes local disponible cuando sea útil.
• --size WIDTHxHEIGHT, --quality auto|low|medium|high|xhigh|max, --background auto|opaque|transparent, y --format png|jpeg|webp|gif|svg mapean a configuraciones de la API. Aún aplica el soporte de modelo/proyecto.
• Usa --model gpt-image-2.6-sunburst cuando el usuario elija la rama destinada para trabajo visual detallado. Mantén Flare para solicitudes ordinarias sin preferencia de modelo.
• --stream --partial-images 1 guarda una vista previa más la imagen final. Solo la imagen completada es el resultado final.
• --params '{"complexity":"medium"}' o --params @params.json pasa campos adicionales de la API. n permanece fijo en 1. Lee gpt-image --help antes de usar opciones poco comunes.
• --timeout SECONDS cubre toda la solicitud. En caso de timeout/cancelación, el servicio ya puede haber aceptado la solicitud. No reenvíes automáticamente.

Detalles del CLI y la API: https://github.com/zsio/openai-image-cli