Image Tools

Use these tools when you encounter images you cannot read natively, or when you need to generate new images.

image_read

Send an image to a vision-capable model and get a text description.

Local file (most common):

tai tool image_read --image_path /path/to/image.png --prompt "Describe this image"

URL:

tai tool image_read --image_path https://example.com/photo.jpg --prompt "What is shown?"

With a specific vision provider:

tai tool image_read --image_path /path/to/image.png --prompt "Describe" --provider llm.my-openai:gpt-4o

Parameter	Type	Required	Description
image_path	string	yes	Image file path or URL
prompt	string	no	Analysis instruction (default: describe in detail)
max_size	integer	no	Max dimension in pixels for longest edge (default: 1080)
provider	string	no	Vision provider connector ID. If omitted, uses default vision model

Images are automatically resized (preserving aspect ratio) before sending to the vision model. Supported formats: PNG, JPEG, GIF, WebP.

image_generate

Generate a new image from a text prompt (text-to-image). For editing an existing image, use image_edit instead.

Basic usage (always specify output):

tai tool image_generate --prompt "A serene mountain landscape at sunset" --output landscape.png

With specific provider, model and size:

tai tool image_generate --prompt "A futuristic city skyline" --provider llm.my-openai --model gpt-image-1 --dimensions 1792x1024 --output output/city.png

Transparent background (for icons, stickers, product shots):

tai tool image_generate --prompt "A cute fox mascot" --background transparent --output_format png --output fox.png

WebP output with quality control:

tai tool image_generate --prompt "A landscape painting" --output_format webp --quality high --output painting.webp

Parameter	Type	Required	Description
prompt	string	yes	Text description of the image to generate
output	string	yes	Output file path for the generated image
provider	string	no	Provider connector ID (use image_providers to list). Auto-selects if omitted
dimensions	string	no	Image dimensions (default: 1024x1024). Common: 1024x1024, 1024x1792, 1792x1024
model	string	no	Model name to use. Overrides the provider's default model
background	string	no	transparent, opaque, or auto. Use transparent for PNG/WebP with no background
output_format	string	no	png, jpeg, or webp. Default: png
output_compression	integer	no	Compression level 0-100 for jpeg/webp. Higher = better quality. Default: 100
quality	string	no	low, medium, high, or auto. Higher takes longer. Default: auto
extra	JSON	no	Provider-specific parameters as a JSON object (e.g. --extra '{"moderation":"low"}')

If output is omitted, the image is saved to a default path in the working directory.

image_edit

Edit or transform an existing image based on a text prompt (image-to-image). Use for style transfer, background replacement, adding/removing elements, or any modification that requires a reference image.

Basic usage:

tai tool image_edit --image_path /path/to/photo.png --prompt "Change the background to a beach scene" --output edited.png

With URL image:

tai tool image_edit --image_path https://example.com/photo.jpg --prompt "Make it look like a watercolor painting" --output watercolor.png

With specific provider and model:

tai tool image_edit --image_path /path/to/original.png --prompt "Remove the person in the foreground" --provider llm.my-openai --model gpt-image-1 --dimensions 1024x1024 --output result.png

With mask (edit only the masked region):

tai tool image_edit --image_path /path/to/photo.png --mask /path/to/mask.png --prompt "Replace with a garden" --output edited.png

Transparent background edit:

tai tool image_edit --image_path /path/to/product.png --prompt "Remove background" --background transparent --output_format png --output cutout.png

Parameter	Type	Required	Description
image_path	string	yes	Reference image file path or URL
prompt	string	yes	Text description of the desired edit or transformation
output	string	yes	Output file path for the edited image
provider	string	no	Provider connector ID (use image_providers with capability=image_editing). Auto-selects if omitted
dimensions	string	no	Output dimensions (default: 1024x1024). Common: 1024x1024, 1024x1792, 1792x1024
model	string	no	Model name to use. Overrides the provider's default model
mask	string	no	Mask image path/URL. Transparent areas in the mask define the editable region
background	string	no	transparent, opaque, or auto. Use transparent for PNG/WebP with no background
output_format	string	no	png, jpeg, or webp. Default: png
output_compression	integer	no	Compression level 0-100 for jpeg/webp. Higher = better quality. Default: 100
quality	string	no	low, medium, high, or auto. Higher takes longer. Default: auto
extra	JSON	no	Provider-specific parameters as a JSON object (e.g. --extra '{"input_fidelity":"high"}')

If output is omitted, the image is saved to a default path in the working directory.

image_providers

List available image providers filtered by capability.

List image generation providers (default):

tai tool image_providers

List image editing providers:

tai tool image_providers --capability image_editing

List vision (image reading) providers:

tai tool image_providers --capability vision

Parameter	Type	Required	Description
capability	string	no	image_generation (default), image_editing, or vision

Returns a list of providers with their available models and connector IDs that can be passed to image_generate, image_edit, or image_read.

Constraints

Use only the parameters listed above for each tool. The supported first-class parameters are: prompt, output, provider, dimensions, model, background, output_format, output_compression, quality, mask (edit only), and extra.

Do not pass n, style, or response_format — they are unsupported and will be ignored or cause errors.

For provider-specific parameters not covered above (e.g. moderation, input_fidelity), pass them through the extra JSON object.