OpenAI Image Generation


ID	`gpt_image_gen`
Category	Media
Features	None
Dependencies	`session_file_system`, `session_storage`

Generate new raster images and edit existing ones with OpenAI’s gpt-image-1 model.

This capability resolves credentials server-side, persists durable image artifacts, and can also write generated outputs into the session filesystem under /workspace/.outputs/images/.

Credential Resolution

The tool layer never reads provider environment variables directly. Resolution order:

Session secret OPENAI_API_KEY (or openai_api_key)
Session secret OPENAI_BASE_URL (or openai_base_url) for endpoint override
Default OpenAI provider credentials from the control plane

Use secret_store for per-session overrides.

Tools

`generate_image`

Generate one or more images from a prompt.

Parameter	Type	Required	Description
`prompt`	string	yes	Image generation prompt
`size`	enum	no	`1024x1024`, `1536x1024`, `1024x1536`, `auto`
`quality`	enum	no	`low`, `medium`, `high`, `auto`
`background`	enum	no	`transparent`, `opaque`, `auto`
`format`	enum	no	`png`, `jpeg`, `webp`
`count`	integer	no	Number of images to generate (1-10)
`save_to_session_fs`	boolean	no	Save images into the session filesystem
`output_dir`	string	no	Filesystem output directory (default `/workspace/.outputs/images`)
`filename_prefix`	string	no	Prefix for artifact and file names
`persist_artifact`	boolean	no	Persist into durable image storage (default `true`)

`edit_image`

Edit one or more existing images using a prompt.

Parameter	Type	Required	Description
`prompt`	string	yes	Editing prompt
`image_id`	string	conditional	Durable image artifact ID to use as an edit source
`path`	string	conditional	Session filesystem path to use as an edit source
`size`	enum	no	`1024x1024`, `1536x1024`, `1024x1536`, `auto`
`quality`	enum	no	`low`, `medium`, `high`, `auto`
`background`	enum	no	`transparent`, `opaque`, `auto`
`format`	enum	no	`png`, `jpeg`, `webp`
`count`	integer	no	Number of images to produce (1-10)
`save_to_session_fs`	boolean	no	Save outputs into the session filesystem
`output_dir`	string	no	Filesystem output directory (default `/workspace/.outputs/images`)
`filename_prefix`	string	no	Prefix for artifact and file names
`persist_artifact`	boolean	no	Persist into durable image storage (default `true`)

At least one of image_id or path is required. When both are present, both source images are sent to the edit request.

Result Shape

Both tools return:

Native image blocks for direct model consumption
Structured JSON with:
- artifact_id when durable storage is enabled
- session_file when workspace save is enabled
- media_type, filename, size_bytes
- revised_prompt when OpenAI returns one

Notes

Transparent background requires png or webp output
Session file edits must be png, jpg, jpeg, or webp
Edit sources larger than 50 MB are rejected before the API call
Saved workspace files are written as base64-encoded binary files