Search and download GIFs via the Tenor API
Search and download GIFs directly through the Tenor API using curl, with no extra tools needed.
Requirements
- Requires a Tenor API key set in the environment plus the curl and jq commands.
- Set your Tenor API key in your environment, adding it to
${HERMES_HOME:-~/.hermes}/.env. - Get a free API key at the Tenor quickstart guide — the Google Cloud Console Tenor API key is free and has generous rate limits.
- You need
curlandjq, both standard on macOS/Linux. - The
TENOR_API_KEYenvironment variable must be set. - Search requests are configured with parameters including
q,limit,key,media_filter,contentfilterandlocale.
How to use
This is useful for finding reaction GIFs, creating visual content, and sending GIFs in chat.
Each result has multiple formats under .media_formats: gif for full quality, tinygif for a small preview, mp4 as a smaller video version, tinymp4 as a small preview video, webm video, and nanogif as a tiny thumbnail.
URL-encode the query: spaces as + and special characters as %XX.
For sending in chat, tinygif URLs are lighter weight.
GIF URLs can be used directly in markdown: 
Complete the setup by storing your key so the commands can use it.
Set your Tenor API key in your environment (add to ${HERMES_HOME:-~/.hermes}/.env).
TENOR_API_KEY=your_key_here
Run a search query against the API to retrieve GIF URLs for your results.
# 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'
To download, search for the GIF you want and save the top result to a local file.
# 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
Fetch full metadata for a search to see each result's title, URL, preview and dimensions.
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}'
Parameters: q is the search query (URL-encode spaces as +); limit sets max results (1-50, default 20); key is the API key from the $TENOR_API_KEY env var; media_filter filters formats (gif, tinygif, mp4, tinymp4, webm); contentfilter sets safety (off, low, medium, high); locale sets language (en_US, es, fr, etc.).
Source: nousresearch/hermes-agent and its contributors. License: MIT.
Copyright (c) 2025 Nous Research
Translation and editorial adaptation by ClawCases.
>Resources
>Related Use Cases
AI Video Editing via Chat
Describe your edit to an agent to trim videos, add music, subtitles, or crops — no timeline or GUI. Install two skills, then editing is done by conversation.
AI Video Generation: HTML-to-MP4 Pipeline
Hermes writes HTML video compositions with Open Design and renders them to finished MP4 files through HyperFrames, using Chrome headless plus FFmpeg instead of a timeline editor.
Family Calendar Aggregation & Household Assistant
Turn OpenClaw into an always-on household coordinator that aggregates family calendars into a morning briefing, monitors messages for actionable items, and manages household logistics through a shared chat interface.