fengfengzhidao/codex-image2

Codex Image2

Genera imágenes con el CLI nativo incluido. Prefiere el ejecutable de esta habilidad sobre la herramienta image_gen incorporada siempre que esta habilidad esté activa. No se requiere Python, Node.js, Go ni instalación de paquetes.

Seleccionar el ejecutable

Elige una vez según el sistema operativo y la arquitectura de CPU actuales:

• Windows x64: bin/codex-image2-windows-amd64.exe
• Windows ARM64: bin/codex-image2-windows-arm64.exe
• macOS Intel: bin/codex-image2-darwin-amd64
• macOS Apple Silicon: bin/codex-image2-darwin-arm64

En macOS, ejecuta chmod +x <ejecutable> si el permiso de ejecución no se conservó. No compiles desde la fuente durante el uso normal.

Flujo de trabajo

Para solicitudes de configuración, utiliza el flujo de trabajo a continuación. Antes de la primera llamada de imagen en una sesión, ejecuta status; si no está configurado, abre configure y deja que el usuario termine en su navegador antes de generar.

1. Decide si la solicitud es una imagen nueva, una edición o múltiples activos/variantes distintas.
2. Recopila el prompt, el uso previsto, el texto exacto, las restricciones visuales y los elementos a evitar.
3. Dale forma al prompt solo lo necesario. Conserva los prompts detallados; aclara con buen gusto los prompts genéricos sin inventar marcas, personas, eslóganes u objetos no relacionados.
4. Ejecuta el ejecutable seleccionado con generate para un prompt, edit para cambios en imágenes existentes, o generate-batch para trabajos JSONL.
5. Inspecciona cada salida en busca de sujeto, composición, precisión del texto, restricciones y artefactos visibles.
6. Si se necesita revisión, cambia un aspecto específico por iteración y vuelve a verificar.
7. Informa las rutas absolutas de salida, el prompt o conjunto de prompts final, el tamaño, la calidad y el modelo.

Estructura del prompt

Usa solo las líneas relevantes:

Tipo de activo: <dónde se usará la imagen>
Solicitud principal: <la solicitud del usuario>
Escena/fondo: <entorno>
Sujeto: <sujeto principal>
Estilo/medio: <foto, ilustración, 3D, etc.>
Composición/encuadre: <ángulo de cámara, recorte, colocación, espacio negativo>
Iluminación/ambiente: <iluminación y ambiente>
Paleta de colores: <notas de paleta>
Texto (textual): "<texto exacto>"
Restricciones: <debe mantener o incluir>
Evitar: <no debe incluir>

No agregues detalles solo para llenar el esquema. Para texto en imágenes, cítalo textualmente y solicita una representación exacta.

Generar una imagen

& "<dir-habilidad>\bin\codex-image2-windows-amd64.exe" generate `
  --prompt "Una pequeña nebulosa azul en una botella de vidrio, foto de producto de estudio" `
  --size 1024x1024 `
  --quality auto `
  --out "output/imagegen/nebulosa.png"

Usa --prompt-file para prompts largos. Usa --n solo para variantes del mismo prompt. Los activos distintos pertenecen a llamadas separadas o a un lote.

Editar una imagen

Inspecciona cada imagen de entrada antes de editarla. Indica su función y repite los invariantes en el prompt para que los detalles no relacionados no se desvíen.

& "<dir-habilidad>\bin\codex-image2-windows-amd64.exe" edit `
  --image "input/producto.png" `
  --prompt "Reemplaza solo el fondo con un fondo de estudio cálido. Mantén el producto, la etiqueta, las proporciones y los bordes sin cambios." `
  --quality auto `
  --out "output/imagegen/producto-editado.png"

Repite --image para múltiples entradas de referencia o composición. Usa --mask mask.png para una edición localizada cuando haya una máscara PNG compatible disponible. Conserva los originales y siempre escribe las ediciones en una nueva ruta de salida.

Generar un lote

Lee references/batch-format.md antes de preparar un lote. Luego ejecuta:

& "<dir-habilidad>\bin\codex-image2-windows-amd64.exe" generate-batch `
  --input "tmp/imagegen/trabajos.jsonl" `
  --out-dir "output/imagegen" `
  --concurrency 2

Configurar el servicio de imágenes

• Ejecuta <ejecutable> status para inspeccionar configured, source, api_url y message. Nunca devuelve una clave.
• configured solo confirma que las credenciales locales son legibles; no prueba la autenticación remota ni los permisos de imágenes. No afirmes que se verificó el acceso a la API solo con status.
• Para el primer uso, credenciales faltantes/inaccesibles o una solicitud de cambio de configuración, ejecuta <ejecutable> configure. Esto inicia una página de configuración local independiente y regresa inmediatamente. No la ejecutes en segundo plano con scripts de shell ni esperes a que su servidor termine.
• Indica al usuario que complete la dirección de la API y la clave en el navegador y haga clic en 保存配置. Si el navegador no se abrió, proporciona la url local devuelta como un enlace en el que se puede hacer clic. Este enlace temporal es válido durante 15 minutos en la máquina del usuario.
• Al guardar, primero se consulta la lista de modelos de la clave enviada. Cualquier modelo de la familia gpt-image listado permite un guardado normal. La familia incluye gpt-image e IDs que comienzan con gpt-image-, como gpt-image-1, gpt-image-1-mini y gpt-image-2.6. Si no hay ningún modelo de la familia listado, o la lista no es compatible, la página advierte y requiere la acción explícita 仍然保存 del usuario para guardar un servicio no verificado. Los errores de autenticación/red/límite de velocidad/servidor requieren corrección antes de guardar. Nunca hagas clic en la anulación por el usuario.
• Nunca pidas la clave en el chat, la pongas en un comando o la rellenes mediante automatización. El usuario la ingresa directamente en la página local; solo ese programa la maneja.
• Después de que el usuario diga que guardó, ejecuta status nuevamente y continúa con la solicitud de imagen original si está configurado. No vuelvas a abrir la página repetidamente ni la consultes mientras esperas la entrada del usuario.
• La configuración guardada tiene efecto en la siguiente invocación del CLI, sin necesidad de reiniciar Codex. La configuración local existente tiene prioridad sobre las variables de entorno heredadas como un par completo de dirección/clave. Una configuración local dañada debe repararse a través de la página de configuración en lugar de recurrir silenciosamente a otro servicio.
• 检测连接 solo sondea el endpoint de la lista de modelos y muestra los IDs de modelo de la clave actual, destacando los modelos de imagen y la selección automática. Los modelos faltantes u ocultos activan una advertencia, no una prueba de que la API de imágenes no está disponible. Editar la dirección/clave borra los resultados obsoletos. El opcional 测试生图（可能计费） requiere confirmación del usuario y realiza una solicitud de imagen sin reintentos. No ejecutes pruebas pagadas automáticamente como parte de la configuración.
• Windows encripta la clave con DPAPI del usuario actual; macOS la almacena en el Llavero de inicio de sesión. macOS puede pedir al usuario que desbloquee o permita el acceso al Llavero.
• El usuario puede hacer clic en 显示 para revelar una clave guardada en su página local. Ocultar borra una clave guardada revelada, y la página la oculta automáticamente después de 30 segundos o cuando la página se oculta. Nunca hagas clic en revelar, inspecciones una clave revelada real ni llames al endpoint de revelación a través de herramientas del agente.

Configuración y seguridad

• Deja que el CLI lea las credenciales. Nunca inspecciones los archivos de credenciales ni el contenido del almacén de credenciales tú mismo, ni copies claves en archivos de proyecto, prompts, registros o respuestas. La página de configuración puede guardar claves solo a través del backend de credenciales de la plataforma del CLI.
• Las variables de entorno heredadas CODEX_API_URL y CODEX_API_KEY siguen siendo compatibles cuando no existe una configuración local; su URL predeterminada es https://apinebula.ai/v1. Recomienda la página de configuración local a los nuevos usuarios. Las URL guardadas existentes se conservan.
• Por defecto usa --model auto (o omite la bandera), tamaño 1024x1024 y calidad auto. El CLI verifica la lista de modelos del servicio configurado y prefiere gpt-image-2.5, luego gpt-image-2, luego el primer otro modelo de la familia gpt-image en orden lexicográfico de ID. Un servicio que solo lista gpt-image-2.6 usa ese modelo. Cuando falla el descubrimiento o no lista ningún modelo de la familia, el CLI llama a gpt-image-2 directamente. Cada lote comparte el descubrimiento por par servicio/credencial.
• Respeta un modelo solicitado explícitamente usando --model <nombre> o el model de una fila de lote; no agregues --model gpt-image-2 por costumbre, ya que eso anula la preferencia automática. Informa el modelo real del resultado del CLI.
• Las ejecuciones de prueba nunca consultan la disponibilidad del modelo; model_selection: auto indica que se omitió el descubrimiento automático, y su carga útil de ejemplo usa gpt-image-2.
• Usa --dry-run para validar una solicitud sin acceso a la red ni necesidad de una clave.
• Guarda los activos vinculados al proyecto dentro del proyecto actual. El valor predeterminado del CLI es output/imagegen/.
• No sobrescribas archivos a menos que el usuario lo autorice explícitamente y se pase --force.
• La salida nativa transparente no está garantizada. No lo prometas ni cambies de herramienta silenciosamente.

Manejo de errores

• El CLI reintenta los tiempos de espera de red y los fallos HTTP 429/500/502/503/504/524 con retroceso limitado.
• En caso de tiempo de espera repetido, sugiere --quality low, un tamaño cuadrado, menos trabajos concurrentes o un reintento posterior.
• No reintentes errores de autenticación, validación u otros errores 4xx comunes.
• Nunca expongas un encabezado Authorization ni una clave completa al informar errores.