gif-search

GIF Search (Tenor API)

Search and download GIFs directly via the Tenor API using curl. No extra tools needed.

Setup

Set your Tenor API key in your environment (add to

~/.hermes/.env

TENOR_API_KEY=your_key_here

Get a free API key at https://developers.google.com/tenor/guides/quickstart — the Google Cloud Console Tenor API key is free and has generous rate limits.

Prerequisites

• curl

  and

  jq

  (both standard on macOS/Linux)

• TENOR_API_KEY

  environment variable

Search for GIFs

# 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'

Download a GIF

# 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

Get Full Metadata

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}'

API Parameters

q

+

limit

key

$TENOR_API_KEY

media_filter

gif

tinygif

mp4

tinymp4

webm

contentfilter

off

low

medium

high

locale

en_US

es

fr

Available Media Formats

Each result has multiple formats under

.media_formats

gif

tinygif

mp4

tinymp4

webm

nanogif

Notes

• URL-encode the query: spaces as

  +

  , special chars as

  %XX

• For sending in chat,

  tinygif

  URLs are lighter weight
• GIF URLs can be used directly in markdown:

  ![alt](url)