ai-openai-image-gen

ai-openai-image-gen — Generate images using GPT Image 1 API

Description

- step: ai-openai-image-gen
  args:
    - '${PROMPT}'
    - '${SIZE}'   # optional

The ai-openai-image-gen step generates images based on a text prompt using the OpenAI GPT Image 1 model.

Requires OPEN_AI_API_KEY set in the workflow context.
Optionally specify output_dir in the context to save images to a specific folder. Defaults to output.
Generated images are saved as PNG files with unique filenames and their paths are returned in context.

Usage in a workflow YAML:

workflow:
  - step: ai-openai-image-gen
    args:
      - "A futuristic city skyline at sunset"
      - "512x512"   # optional

Parameters

Parameter	Type	Description
`prompt`	`string`	Text prompt describing the image to generate.
`size`	`string`	Optional. Image size, e.g., `"256x256"`, `"512x512"`, or `"1024x1024"`. Defaults to `"1024x1024"`.

Context requirements:

Context Key	Type	Description
`OPEN_AI_API_KEY`	`string`	Required. OpenAI API key for authentication.
`output_dir`	`string`	Optional. Directory where images are saved. Defaults to `output`.

Return Values

Returns 0 on success, 1 on failure.
On success, context (${prev} by default, or custom via set_context) contains a list of saved image file paths or URLs:

[
  "/full/path/to/output/uuid1.png",
  "/full/path/to/output/uuid2.png"
]

On failure, context contains:

{
  "error": "Error message describing the failure"
}

Behavior

Sends a request to OpenAI GPT Image 1 API with the given prompt and optional size.
Saves generated images as PNG files in output_dir, creating the directory if it doesn’t exist.
Filenames are generated using UUIDv4 for uniqueness.
If the API returns URLs instead of base64 images, the URLs are returned.
Handles API errors and network issues, storing errors in ${prev}.error (or custom context).

Examples

Example #1 — Basic image generation

workflow:
  - step: ai-openai-image-gen
    args:
      - "A cyberpunk cityscape at night"

Saves images in output/ and stores their paths in ${prev}.

Example #2 — Custom size and context key

workflow:
  - step: ai-openai-image-gen
    args:
      - "A majestic mountain landscape"
      - "512x512"
    context:
      set_context: mountain_images

Stores generated image paths under ${mountain_images}.

Example #3 — Specifying output directory

workflow:
  - step: ai-openai-image-gen
    args:
      - "A cute cartoon robot"
    context:
      output_dir: '/tmp/robot_images'

Saves images to /tmp/robot_images/.

Notes

Ensure OPEN_AI_API_KEY is valid and has permissions for image generation.
Multiple images may be returned; all are saved and returned as a list.
Default image size is 1024x1024 if not specified.
Uses unique filenames (UUIDv4) to prevent overwriting existing images.