README.md

---
title: Personal Tenor Scraper API
emoji: 🐈
colorFrom: yellow
colorTo: pink
sdk: docker
app_port: 7860
pinned: false
---

# Personal Tenor Scraper API

Unofficial personal replacement for the Tenor public API, which Google
shut down on **June 30, 2026**. Tenor.com itself is still online for
humans, so this scrapes the live site instead of calling the (now dead)
`api.tenor.com` endpoints.

**Heads up**: this depends on Tenor's page markup not changing. It uses
two independent extraction strategies (embedded JSON state blob, then a
raw-HTML regex fallback) so it should survive minor site tweaks, but a
big redesign on Tenor's end could break it. Check `scraper.py` if search
results suddenly come back empty.

## Deploying on Hugging Face Spaces

1. Create a new Space, SDK = **Docker**.
2. Push these files (`app.py`, `scraper.py`, `cache.py`, `requirements.txt`, `Dockerfile`, this `README.md`).
3. (Optional but recommended once it's public) Set a Space secret `API_KEY` to require auth — see below.
4. (Optional) Enable persistent storage on the Space so the SQLite cache/favorites survive restarts. Without it, everything resets when the Space sleeps/restarts.
5. Space builds and starts listening on port 7860 automatically.

## Auth

If you set the `API_KEY` environment variable/secret on the Space,
every endpoint requires it via either:

- Header: `X-API-Key: your-key-here`
- Query param: `?api_key=your-key-here`

Leave `API_KEY` unset for open access (fine if you're the only one who
knows the Space URL, less fine once people share it around).

## Endpoints

### `GET /search`
```
/search?q=cats&limit=10&format=full
```
Params:
- `q` (required) — search term
- `limit` — max results, default 20, capped at 50
- `page` — pagination, default 1
- `format` — `full` (default, full metadata), `urls` (flat list of direct URLs), or `discord` (list of `{url, embed_url, title}`)

### `GET /random`
```
/random?q=thumbs+up&limit=1&format=urls
```
Same params as `/search` minus `page`, returns shuffled picks.

### `GET /direct`
```
/direct?q=high+five
```
No JSON — just **302 redirects straight to a gif URL**. Great for
sticking directly into a Discord message as a link, or hitting from a
webhook/bot that just wants a URL back with zero parsing:
```
Just paste https://your-space.hf.space/direct?q=high+five directly in Discord chat and it unfurls as the gif.
```

### `POST /favorites`
Save a gif you like for quick reuse later (e.g. your most-used reaction gifs).
```json
{
  "gif_url": "https://media.tenor.com/xyz.gif",
  "mp4_url": "https://media.tenor.com/xyz.mp4",
  "title": "thumbs up guy",
  "tag": "reactions"
}
```

### `GET /favorites?tag=reactions`
List saved favorites, optionally filtered by tag.

### `DELETE /favorites/<id>`
Remove a saved favorite by its numeric id.

### `GET /favorites/random?tag=reactions`
Random pick from your saved favorites — good for a Discord bot's
"random reaction gif" command without re-scraping every time.

### `GET /health`
Basic liveness check, returns `{"status": "ok", "time": ...}`.

## Using it from a Discord bot later

Since you said the bot wiring comes later — the API is shaped so a
future bot command can just do:

```python
import requests

resp = requests.get(
    "https://your-space.hf.space/random",
    params={"q": query, "format": "discord", "limit": 1},
)
gif = resp.json()["results"][0]
await ctx.send(gif["embed_url"])  # Discord auto-embeds the URL
```

## Rate limiting

In-memory sliding window, default 60 requests / 60 seconds per API
key (or per IP if no key is set). Adjust via `RATE_LIMIT_MAX` and
`RATE_LIMIT_WINDOW` env vars. This is per-instance, not distributed —
fine for a single free-tier Space.

## Caching

Search results are cached in SQLite for `CACHE_TTL_SECONDS` (default
3600 = 1 hour) so repeated searches for the same term don't re-scrape
Tenor every time. Cache path defaults to `/data/tenor_cache.db` if
persistent storage is enabled on the Space, otherwise falls back to a
local file that resets on restart.

## Env vars summary

| Var | Default | Purpose |
|---|---|---|
| `API_KEY` | unset (auth disabled) | require `X-API-Key` header/`api_key` param |
| `RATE_LIMIT_MAX` | 60 | max requests per window |
| `RATE_LIMIT_WINDOW` | 60 | window length in seconds |
| `CACHE_TTL_SECONDS` | 3600 | how long cached search results stay fresh |
| `TENOR_CACHE_PATH` | `/data/tenor_cache.db` | SQLite path when persistent storage is enabled |
| `PORT` | 7860 | server port (HF Spaces expects 7860) |

## Known limitations

- Scraping HTML is inherently more fragile than a real API — expect occasional breakage if Tenor changes their frontend.
- No official support/guarantee from Tenor; this is purely a personal workaround now that the API is gone.
- Rate limiting is per-instance/in-memory, resets on restart.
- If Tenor ever moves to fully client-rendered results with nothing in the initial HTML, you'd need to add a headless-browser fallback (see the `render_with_browser()` stub in `scraper.py` for notes on wiring up Playwright).