Tenor GIF Search and Download Reference

This document covers how to search for and download GIFs using the Tenor API with curl and jq. Use this tool for finding reaction GIFs, creating visual content, or sending GIFs in chat.

Prerequisites

• curl installed (standard on macOS and Linux)
• jq installed (standard on macOS and Linux)
• A Tenor API key set as the TENOR_API_KEY environment variable

Setup

1. Get a free Tenor API key from the Google Cloud Console (https://developers.google.com/tenor/guides/quickstart).
2. Add the key to your environment by placing the following line in ${HERMES_HOME:-~/.hermes}/.env:

TENOR_API_KEY=your_key_here

Replace your_key_here with your actual API key.

Searching for GIFs

Construct the search URL using this pattern:

https://tenor.googleapis.com/v2/search?q=QUERY&limit=N&key=${TENOR_API_KEY}

Replace QUERY with your URL-encoded search term (spaces as +, special characters as %XX). Replace N with the desired number of results (1 to 50).

Get Full GIF URLs

# Search and get GIF URLs
curl -s "https://tenor.googleapis.com/v2/search?q=thumbs+up&limit=5&key=${TENOR_API_KEY}" | jq -r '.results[].media_formats.gif.url'

# Get smaller/preview versions
curl -s "https://tenor.googleapis.com/v2/search?q=nice+work&limit=3&key=${TENOR_API_KEY}" | jq -r '.results[].media_formats.tinygif.url'

The first command searches for "thumbs up" and returns 5 full GIF URLs. The second searches for "nice work" and returns 3 preview URLs using tinygif. For sending in chat, tinygif URLs are lighter weight.

Downloading a GIF

Search and extract the top result URL, then download it.

# Search and download the top result
URL=$(curl -s "https://tenor.googleapis.com/v2/search?q=celebration&limit=1&key=${TENOR_API_KEY}" | jq -r '.results[0].media_formats.gif.url')
curl -sL "$URL" -o celebration.gif

This searches for "celebration", gets the top result's GIF URL, and downloads it as celebration.gif.

Retrieving Full Metadata

To get the title, GIF URL, preview URL, and dimensions for multiple results:

curl -s "https://tenor.googleapis.com/v2/search?q=cat&limit=3&key=${TENOR_API_KEY}" | jq '.results[] | {title: .title, url: .media_formats.gif.url, preview: .media_formats.tinygif.url, dimensions: .media_formats.gif.dims}'

This returns a JSON object for each result with the title, full GIF URL, tinygif preview URL, and dimensions array.

Parameters

Parameter	Meaning	Required
q	Search query (URL-encode spaces as +, special chars as %XX)	Yes
key	API key (from $TENOR_API_KEY env var)	Yes
limit	Max results (1-50, default 20)	No
media_filter	Filter formats: gif, tinygif, mp4, tinymp4, webm, nanogif	No
contentfilter	Safety level: off, low, medium, high	No
locale	Language: en_US, es, fr, etc.	No

The media_filter parameter lets you restrict results to specific formats. The contentfilter parameter controls content safety. The locale parameter sets the language for search results.

Using GIFs in Markdown

GIF URLs obtained from the search can be used directly in markdown:

![alt](https://github.com/NousResearch/hermes-agent/blob/main/skills/media/gif-search/url)

Replace the URL with the actual GIF URL from the search results.

Failure Modes

• Missing TENOR_API_KEY environment variable: the API call will fail with an authentication error.
• Invalid API key: the API will reject the request.
• Network errors: curl will fail to connect or timeout.
• Rate limit exceeded: the API will return an error indicating too many requests.

Notes

• Always URL-encode the query: spaces as +, special characters as %XX.
• For sending in chat, prefer tinygif URLs as they are lighter weight.
• The API key is free with generous rate limits.
• The .media_formats object contains all available formats for each result.