bildomat

Image and video generation for agents and scripts. One command, 170+ models

Overview | Quickstart | Basic Usage | Agentic Use | Scripting | Providers and API Keys | Configuration

Overview

Image and video generation for scripts, agents, and your terminal

Bildomat provides a single unified interface to multiple image and video generation providers. The bild command handles requests, waits for generations, polls for results, and saves the media to disk.

Supported Providers:

• Google: 9 models (4 image models · 5 video models)
• OpenAI: 9 models (7 image models · 2 video models)
• Black Forest Labs: 25 models (22 image models · 3 video models)
• xAI: 7 models (4 image models · 3 video models)
• Sourceful: 4 models (4 image models)
• Recraft: 21 models (21 image models)
• Kling: 10 models (4 image models · 6 video models)
• OpenRouter (multi-provider aggregator): 86 models (56 image models · 30 video models)

See Providers and API Keys for setting up API keys and configuring them in your environment.

Script with bild for repeatable jobs. A shell loop can turn a folder of product photos into studio shots, animate product stills, or generate daily hero images for websites.

Teach your agent to use bild for images and illustrations. With bild, a design agent can generate, inspect, and refine images and videos for any design project. Generate images for web design, create uniform stylized illustrations for an app UI, or enhance a newsletter or report with suitable artwork.

Chain bild commands by using the output of one as input to another

Demo: animate a field of colorful turbine spinners

A rainbow spinner becomes a wind turbine, then a papercut illustration, then a landscape full of companions. Finally, the blades begin to turn. The sequence uses Sourceful, OpenAI, and xAI through the same bild interface, with each result available as the next request's input.

Download the video

Make your design agents more effective

Put bild into your agent skills to dramatically enhance their design capabilities.

For example, an app design skill already guides an agent through screens, copy, navigation, and layout. Give it bild, and it can make sets of illustrations in a uniform style. Each screen gets its own subject, with a shared material, palette, and lighting.

Add an instruction like this to your skill:

Your agent can then generate sets of illustrations for each screen, maintaining a consistent style across the entire app.

Turn everyday photos into professional product shots

The source photo and a generated studio treatment.

Do it once, then script it.

Refine the prompt by iterating as necessary. Then script it to automatically run the same task over full batches of everyday images:

#!/usr/bin/env bash
set -e

for source_photo in products/*.jpg; do
  photo=${source_photo##*/}
  bild -m openai/gpt-image-2 -i "$source_photo" \
    -o "studio/${photo%.jpg}.png" -p \
    "Create a professional studio-quality product shot of the product,
     seamless white background. Preserve its shape, materials, and details."
done

To vary it for different batches, change the prompt to describe a different setup, lighting style, or setting.

Advanced Workflow: Ensemble Product Shot

For a more advanced workflow, such as creating a fashion ensemble product shot, run separate commands to extract each item and then combine them back into a single shot.

The source photo: a street shot of a woman in a casual outfit.

Extracting the items: for best resutls, first create a product shot of each item individually.

Put it together: combine the individual product shots into a single ensemble image.

Quickstart

Install

With Homebrew (macOS or Linux):

brew install shdeen/tap/bild

Install script:

On macOS or Linux:

curl -fsSL https://bildomat.com/install.sh | sh

On Windows, in PowerShell:

irm https://bildomat.com/install.ps1 | iex

Go Installer:

With Go 1.26.5 or later on macOS, Linux, or Windows:

go install github.com/shdeen/bildomat/cmd/bild@latest

Go usually installs binaries to ~/go/bin. Make sure that directory is on your PATH.

For a standard Bash or Zsh setup, add this to ~/.bashrc or ~/.zshrc:

export PATH="$HOME/go/bin:$PATH"

Binaries:

Precompiled binaries for Bildomat (bild) are available for Windows, macOS and Linux.

Set up a provider API key

API keys may be set in the Bildomat configuration file or in shell environment variables.

Providers and API Keys | Configuration

The Bildomat configuration file

The Bildomat configuration file is in YAML format within the Bildomat directory under your home directory.

To set it up on macOS or Linux, create a config.yml file at the following path: ~/.bildomat/config.yml. On Windows, use %USERPROFILE%\.bildomat\config.yml.

Then add the key for each provider you use under api-keys, and omit the providers you don't use:

api-keys:
  google: your-google-api-key
  openai: your-openai-api-key
  xai: your-xai-api-key
  bfl: your-bfl-api-key
  sourceful: your-sourceful-api-key
  recraft: your-recraft-api-key
  kling: your-kling-api-key
  openrouter: your-openrouter-api-key

A key in the configuration file takes precedence over the environment variable for the same provider.

A shell environment variable

To set up an API key in your shell environment, export the environment variable for each provider you use, and omit the providers you don't use. The Providers and API Keys section below lists each provider's variable.

export GOOGLE_API_KEY="your-google-api-key"
export OPENAI_API_KEY="your-openai-api-key"
export XAI_API_KEY="your-xai-api-key"
export BFL_API_KEY="your-bfl-api-key"
export SOURCEFUL_API_KEY="your-sourceful-api-key"
export RECRAFT_API_KEY="your-recraft-api-key"
export KLING_API_KEY="your-kling-api-key"
export OPENROUTER_API_KEY="your-openrouter-api-key"

To have your shell load with your environment variables at startup, add these commands to your shell configuration file, such as ~/.bashrc or ~/.zshrc.

$env:GOOGLE_API_KEY = "your-google-api-key"
$env:OPENAI_API_KEY = "your-openai-api-key"
$env:XAI_API_KEY = "your-xai-api-key"
$env:BFL_API_KEY = "your-bfl-api-key"
$env:SOURCEFUL_API_KEY = "your-sourceful-api-key"
$env:RECRAFT_API_KEY = "your-recraft-api-key"
$env:KLING_API_KEY = "your-kling-api-key"
$env:OPENROUTER_API_KEY = "your-openrouter-api-key"

Generate your first image

Run bild with -m, --model to use a model from your configured provider.

bild -m google/gemini-3.1-flash-image \
  "a fox reading a storybook surrounded by forest friends"

By default, the file will save to your current directory. To specify a different output location, use the -o/--output-path option.

bild -m google/gemini-3.1-flash-image -o ~/your/path/ \
  "a fox reading a storybook surrounded by forest friends"

Alternatively, you can set an output directory in the configuration file to have bild save generated media there by default. Using the -o/--output-path flag overrides the both the system default and that of your config setup.

You may also set up a default model by setting it in the configuration file. Specifying the -m/--model option overrides both the system's default model and any model you set up in config.yml.

Without a model in the configuration file, bild uses the default model of the first provider, in the order that bild list shows, whose API key is set up. To see which model that is, run bild help and check the -m/--model option. If no provider has an API key set up, a run without -m fails and asks for a model.

Basic Usage

Put options before the quoted prompt. Select a model with -m, supply an image or video reference with -i, and choose an output path with -o.

# Generate an image
bild "logo for a neighborhood bread bakery"

# Choose a model and output file
bild -m openai/gpt-image-2 -o logo.png \
  "logo for a neighborhood bread bakery"

# Edit a photo or use it as a visual reference
bild -m google/gemini-3.1-flash-image -i product.jpg -o studio.png \
  "Place this product on a white studio background with soft lighting"

# Animate a still image
bild -m xai/grok-imagine-video -i landscape.png -d 6 -o landscape.mp4 \
  "A slow camera push toward the mountains as clouds drift overhead"

Model names can be aliases, such as gemini, gpt, or grok-video, or full provider/model names as above. A full name fixes the provider and model used by a script.

Find models and inspect their options

bild help                        # General usage
bild list                        # Providers and their models
bild search gpt                  # Search for a provider or model with a partial name
bild help search                 # Help for a command
bild info google                 # All info about a provider, its models, and supported flags
bild info gpt-image-2            # All info about a model and supported flags

Use the basic filters with list or search or provide a search term to search the beginning of any provider or model name. For more advanced pattern searches or to search for any part of a model or provider name, use the -r/--regex option.

# Basic filters
bild list -p                     # Show providers list only
bild list -m                     # Show models list only
bild list -i                     # Show image models only
bild list -v                     # Show video models only

# Advanced search, list, and info options
bild search flux                 # Any name beginning with "flux"
bild search -v flux              # Any name beginning with "flux" and is a video model 
bild search -r vector            # Any name with "vector" in it
bild search -r 'pro|max'         # Any name with either "pro" or "max" in it
bild search -r 'gemini.*pro'     # All gemini pro versions
bild list -j                     # Full provider and model list in JSON
bild search -j flux              # All model names beginning with "flux", in JSON
bild info -j google              # All info about google and its models, in JSON

list and search share the -p, -m, -i, and -v filters. A normal search matches the beginning of any slash-delimited part of a full model name, or an alias, without regard to case. -r/--regex searches anywhere and supports more complex patterns.

list, search, and info all accept -j/--json. Help is text-only. Model capabilities differ; bild info <model> shows the supported flags, limits, and allowed values.

Specify where files are saved

An explicit -o replaces the configured output directory. Bare filenames and relative paths resolve from the current directory. Existing media files are preserved under numbered filenames. The saved extension follows the actual media format, so use the returned path when passing a result to another command.

Agentic Use

Add bild to your agent instructions (e.g. AGENTS.md, CLAUDE.md) for all image and video generation tasks. Specify bild in agent skills (e.g. a design skill for a web frontend or app UI) to have image and video generation become part of the agent's existing workflow.

Calling provider APIs directly makes an agent spend a large amount of tokens finding and reading API documentation, building requests and payloads, polling jobs, then downloading and decoding the requested media. Bildomat puts that work behind one discoverable CLI.

Your agents deserve better!

Scripting

Capture a filename. -p/--print-filename makes saved paths the only non-error output, one per line. Use it to connect generation to the next edit:

#!/usr/bin/env bash
set -e

reference_image=$(bild -m openai/gpt-image-2 -o reference.png -p \
  "A blue felt suitcase and a folded map, pale blue background")

bild -m openai/gpt-image-2 -i "$reference_image" -o companion.png -p \
  "Create a companion illustration of a tent and backpack.
   Match the reference's felt materials, colors, light, and composition."

Capture a report. -j/--json returns the generation status, model, submitted flags, saved paths, adjustments, and errors:

bild -m google/gemini-3.1-flash-image -o fox.png -j \
  "a fox reading a storybook surrounded by forest friends" > generation.json

The saved files are in artifacts[].path. A completed generation has status: "completed". To save the JSON report and print only filenames to the shell at the same time:

bild -m google/gemini-3.1-flash-image -o fox.png \
  -j --save-results generation.json -p \
  "a fox reading a storybook surrounded by forest friends"

The report file is replaced if it already exists. Use a distinct report name for each run when keeping a history.

Bildomat handles requests, polling, downloads, and file saving. Your script controls the sequence and what happens on failure. For deterministic workflows, select a full model name, specify the output location, and check the exit status and report. Bildomat reports adjustments to unsupported settings; inspect those when exact dimensions or other constraints matter.

Providers and API Keys

To generate images with Bildomat, you need an API key from a supported provider.

To create an API key, see the list below and the API key URL for each provider. If prompted to, set up an account with the desired provider, and then follow the site's instructions to generate an API key.

An API key is usually associated with a billing account, which may require a payment method and/or the purchase of API usage credits. Image generation costs vary widely, so check the provider's pricing page carefully before using. For a very rough range, image generations may cost anywhere from $0.01–$0.25 per generated image; video generation is typically higher cost. Your exact usage cost will depend on the provider, model, generation type, and other factors. Be sure to monitor your usage and to track costs for your image and video generations.

All configuration keys in this table belong under api-keys in config.yml. See below for a config file example.

Note: An OpenRouter API key allows access to models from many of the above providers with a single API key. Use bild list -m to see which models are available through each provider.

Configuration

All settings in ~/.bildomat/config.yml are optional. default-model applies when -m is omitted; output-dir applies when -o is omitted. Without a configured model, Bildomat uses the default model of the first provider in bild list that has an API key. A provider's default model may change between releases. Keys in this file take precedence over environment variables.

default-model: google/gemini-3.1-flash-image
output-dir: ~/Pictures/bildomat

api-keys:
  google: your-google-api-key
  openai: your-openai-api-key
  bfl: your-bfl-api-key
  xai: your-xai-api-key
  sourceful: your-sourceful-api-key
  recraft: your-recraft-api-key
  kling: your-kling-api-key
  openrouter: your-openrouter-api-key

MIT license.