weber87na/openai-image

OpenAI 繪圖與原生 GIF

Este skill es un paquete de habilidades para agentes que se puede copiar de forma independiente, compatible con instalaciones de proyecto y personales. El directorio donde se encuentra este archivo es el directorio raíz del skill; no asuma una ubicación fija ni el directorio de trabajo actual. Todos los comandos de Python deben ejecutarse a través de uv, sin usar python, pip ni crear un venv manualmente.

Capacidades y limitaciones

• Imágenes estáticas: PNG, JPEG, WebP.
• GIF animados nativos: use output_format=gif, frame_count, frame_duration_ms, una sola llamada a /v1/images/generations.
• Modelo predeterminado: gpt-image-2.6-sunburst; para iteraciones rápidas puede usar gpt-image-2.6-flare. No use nombres coloquiales como gpt-image2.6 como ID de modelo.
• Los GIF actualmente requieren acceso a la vista previa de GIF del modelo seleccionado; no basta con la suscripción a ChatGPT / Codex / Copilot.
• Los GIF admiten de 2 a 16 fotogramas, con 9 por defecto; cada fotograma tiene 200 ms por defecto, mínimo 20 ms, la API redondea a 10 ms, con un límite de 655350 ms. La animación predeterminada dura aproximadamente 1.8 segundos; el tiempo real depende de los datos de salida.
• No duplique la misma imagen en varios fotogramas, no renombre PNG como GIF, ni reemplace en silencio con múltiples generaciones de imágenes u otros servicios de pago en caso de fallo.
• Este CLI se centra en generar imágenes a partir de texto; no proporciona edición de imágenes, streaming, generación de video ni composición de animaciones locales. Sin dependencias de Pillow, FFmpeg ni el SDK de OpenAI.

Flujo de trabajo

1. Determine si la solicitud es para una imagen estática o animación; conserve el sujeto, composición, texto, estilo y ruta de salida especificados por el usuario.
2. Para animaciones, complete la descripción con "movimiento, cámara fija, fondo consistente, transición suave al inicio/fin". No cambie los requisitos sin consentimiento. Si no se especifican, use valores predeterminados para fotogramas y velocidad; si exceden los límites de la API, explique y pregunte al usuario cómo proceder.
3. Recuerde que se consumirán créditos de la API de OpenAI; solo invoque la API cuando el usuario haya autorizado la generación de imágenes. Simplemente crear el skill, ver la ayuda o hacer un dry-run no representa autorización para pruebas de pago. No envíe código fuente, credenciales ni datos confidenciales.
4. Verifique uv --version. Si uv no está instalado, pida al usuario que instale uv; no instale herramientas del sistema por su cuenta.
5. Verifique que OPENAI_API_KEY exista; nunca imprima el contenido de .env o la clave, no pida que se pegue en la conversación, ni lo escriba en código fuente o repositorios. Use variables de entorno existentes; si necesita dotenv, confirme la ruta absoluta del .env del proyecto del usuario o la especificada explícitamente, y cárguela con uv run --env-file <ruta>. No busque credenciales de otros proyectos en el directorio de instalación del skill. Esta herramienta solo se conecta a https://api.openai.com; no lea OPENAI_BASE_URL.
6. Resuelva la ruta absoluta del CLI desde el directorio raíz del skill. Primero haga un dry-run para verificar los parámetros, luego ejecute una solicitud real. La ruta de salida debe estar en el proyecto de trabajo del usuario, no en el directorio de instalación del skill. Para la configuración inicial, use la plantilla de configuración vacía y la guía de uso; no sobrescriba configuraciones existentes.
7. Verifique el código de salida y el JSON de resultado. La herramienta valida el formato de retorno, para GIF analiza los bloques, confirma al menos dos fotogramas, informa las dimensiones reales, número de fotogramas y duración total, y luego escribe el archivo. Esto es una verificación de contenedor y formato, no una decodificación completa de píxeles ni una validación de calidad visual; solo revise la imagen si el agente tiene capacidad de previsualización.
8. Proporcione un enlace al archivo de salida; si el GIF no se ha previsualizado, no afirme que los efectos visuales han sido verificados. Si el número de fotogramas no coincide, muestre una advertencia, no lo oculte.

Modo de ejecución

Primero, configure $skillDir como la ruta absoluta del directorio raíz del skill según la ubicación de carga, luego ejecute desde el proyecto de trabajo del usuario. Consulte la guía de uso para la configuración completa, ejemplos de imágenes estáticas/GIF y parámetros.

$script = Join-Path $skillDir 'scripts\openai_image.py'
uv run --no-env-file --script "$script" --prompt 'Paisaje de montañas y niebla matutina en Taiwán, estilo acuarela original, sin texto' --output outputs\mountains.png --dry-run

• --dry-run no necesita API key, no llama a la API, no escribe archivos; muestra el prompt, no use contenido confidencial. uv puede descargar el entorno de ejecución de Python si falta, la primera vez.
• Solo después de obtener autorización para generar imágenes, elimine --dry-run. Si necesita dotenv, reemplace --no-env-file con --env-file <ruta absoluta del .env especificado por el usuario>.
• Los GIF usan la extensión .gif; puede especificar --frames 9 --frame-duration-ms 200; n=1 representa la animación completa, no el número de fotogramas.
• No envíe parámetros no aplicables a GIF como response_format, stream, partial_images, output_compression.
• Por defecto no especifique dimensiones; las dimensiones personalizadas deben ser múltiplos de 16, con una relación de aspecto entre 1:3 y 3:1. Los GIF tienen restricciones de tamaño de modelo adicionales; no asuma que las dimensiones estáticas siempre son aplicables.
• No proporcione --overwrite a menos que el usuario acepte explícitamente reemplazar archivos existentes.

Manejo de errores

• Falta de clave: deténgase, pida al usuario que configure la clave en su entorno; no pegue la clave en la conversación.
• HTTP 401 / 403 / 404: verifique las credenciales, el ID completo del modelo, la validación de la organización y los permisos de vista previa de GIF.
• HTTP 400: verifique dimensiones, formato, parámetros de fotogramas y compatibilidad del modelo; no degrade automáticamente a otros formatos o esquemas de composición.
• HTTP 429, 5xx, tiempo de espera o interrupción de conexión: puede que se haya procesado y facturado; informe primero y, con el consentimiento del usuario, reenvíe.
• GIF no animado, formato incorrecto, Base64 no válido o GIF incompleto: rechace el informe de éxito, no escriba el archivo de destino.
• Si la ruta de salida no existe, cree automáticamente las carpetas padre; los archivos existentes no se sobrescriben por defecto. El sistema de archivos debe soportar enlaces duros para guardar atómicamente sin sobrescribir; si no es compatible, se reportará un error, no se sobrescribirá en silencio.

Validación

Las pruebas offline solo usan un servidor HTTP simulado local, sin leer claves reales, sin conexión a OpenAI, sin costo:

$tests = Join-Path $skillDir 'tests\test_openai_image.py'
uv run --no-env-file --script "$tests"

Las pruebas no representan que se haya obtenido acceso al modelo / vista previa de GIF ni que se haya completado una validación de extremo a extremo paga. La generación real requiere una clave válida y la autorización del usuario.

Invocación en el agente

• Copilot: use /openai-image, o simplemente diga "Usa OpenAI para dibujar una imagen / hacer un GIF animado".
• Codex: use $openai-image, o solicite en lenguaje natural usar este skill; la configuración de interfaz de Codex no afecta los comandos compartidos.
• Si no se encuentra, verifique la ubicación de instalación compatible con el harness actual y reinicie la conversación o recargue la lista de skills. Copilot CLI y Codex pueden compartir .agents/skills; algunos harness de Copilot usan .github/skills. Mueva la carpeta completa, no copie el mismo skill en varios lugares que se escanean simultáneamente.

Referencias oficiales

Los parámetros de implementación se basan en la documentación oficial consultada el 9 de noviembre de 2026; el acceso al modelo, las limitaciones y los precios pueden variar.

• Guía de generación de imágenes: GPT Image 2.6
• API de Images: parámetros de GIF nativos
• Modelo Sunburst
• Modelo Flare
• Codex skills
• Copilot CLI skills