getimage

A Go program to fetch random images. Good if you're developing something where you need some images to test with. It will find a random image, download it, resize it however you want, convert it to the format of your choice and save it with a specified name, all in a single command.

Config

When you first run getimage it will create a config file in ~/.config/getimage/config. It looks like this:

# must enter at least one of these
pixabay_api_key = ""
pexels_api_key = ""

# Leave blank to randomly use either api
api = ""

# default image size
width = 800
height = 800

# default image name
name = "image.png"

# add or remove search terms
# if list is empty it will search for "random"
search_terms = [
  "airplane",
  "animals",
  "art",
  ...
]

You'll need to enter an API key for either https://pexels.com or https://pixabay.com there. You can enter both. Note: both services are free to sign up for and will give you an API key no questions asked. The rate limits are very generous.

You can set the api value to either pexels or pixabay to restrict it to one of those even if you have entered both keys. If you only have one key, you can safely leave this blank and it will use the service you specified the key for. If you have both keys and leave api blank, it will randomly choose between the two services for each image call.

Here you can also set the default width, height and name for downloaded images.

api, width, height, and name can all be overridden by command line flags when you run the app.

Finally, there is a list of search terms that getimage will randomly use. You can add or remove terms to this list. If the list is empty, it will use the search term "random".

Sources

Uses pexels.com and/or pixabay.com. You'll need to get an api key from at least one them and set it in the config as described above. You can pass "pexels" or "pixabay" via the -a flag to force that api on each call.

Searching

The app will pick a random image chosen from a number of random search terms, which you can configure as mentioned above. But you can specify your own search term using the -s flag. Multi-word search terms should be ok, if enclosed in quotes or separated by + characters. Examples:

getimage -s "bald eagle"
getimage -s red+fox

Alternately, you can specify the URL of an image to download directly using the -u flag.

Image Name

Images will be saved as image.png (or as otherwise set in the config file) in the current directory, but you can specify an alternate image and file type with the -o flag.

Images will be resized to 800x800 pixels, but you can specify a width and/or height with -w or -h or a geometry (e.g. 640x480) with -g. Again, these defaults can be set in the config file.

If you search for an image, the author's user name and a URL to the photo page will be output on the command line, suitable for crediting the work.

Usage

getimage <flags>

Flags:

-w the width of the saved image (default: 800px)
-h the height of the saved image (default: 800px)
-g geometry of image defined was `widthxheight` - overrides w and h if set
-s a search term for the kind of image to download
-u a direct URL to an image - will bypass search, download and resize image
-o the output file name. extension can be any valid image type (default: "image.png")
-a which api to use ("pexels" or "pixabay").

Usage examples

Examples assume default configuration.

• Download a random image, sized and cropped to 800x800, as "image.png":

getimage

• Download a random image, sized to 800px wide, as "photo.jpg".

getimage -w 800 -n photo.jpg

• Download a random image of "snow" from pexels sized and cropped to 640x480, saved as "snow.png":

getimage -s snow -a pexels -g 640x480 -o snow.png

• Download a specific jpg image from a URL, converted to a png and saved as "image.png", sized and cropped to 800x800:

getimage -u http://somesite.com/someimage.jpg

• Download a random image of an old book, using config defaults:

getimage -s "old book"

Dependencies:

• ImageMagick must be installed for the conversion and resizing.

Install:

If you have Go installed...

go install codeberg.org/bit101/getimage@latest

Or check out the code and build with Go.

Developed in Linux.

Installation and functionality tested in Linux, MacOS and Windows.