Docs | GIPHY Developers

GIPHY Alt Text for GIFs is now available! Email us to learn more at bd.team@giphy.com.

Migrating from Tenor to GIPHY API

This guide provides comprehensive information for developers migrating from the Tenor API to the GIPHY API. While both APIs provide access to GIF and sticker content, there are important differences in endpoints, parameters, response structures, and features.

🚀 Consider Using the GIPHY SDK

Want a faster, easier integration? Check out our official GIPHY SDKs for JavaScript, iOS, and Android. The SDK handles pagination, analytics tracking, and rendition optimization automatically, letting you focus on building great experiences instead of managing API details.

IMPORTANT

API keys from Tenor will not work with GIPHY.

You must create a new API key in the GIPHY Developer Dashboard.

Plan for testing time as pagination and analytics tracking work differently.

Authentication

Authentication differs between Tenor and GIPHY:

Apply for an API key in the GIPHY Developer Dashboard
Use api_key query parameter instead of Tenor's key parameter

Before (Tenor)

Copy Code

curl "https://tenor.googleapis.com/v2/search?q=excited&key=YOUR_TENOR_KEY"

After (GIPHY)

Copy Code

curl "https://api.giphy.com/v1/gifs/search?q=excited&api_key=YOUR_GIPHY_KEY"

Try in API Explorer →

Base URL

Platform	Base URL
Tenor	`https://tenor.googleapis.com`
GIPHY	`https://api.giphy.com`

Endpoint Mappings

Below is a comprehensive mapping of Tenor endpoints to their GIPHY equivalents:

Search GIFs

Tenor	GIPHY	Notes
`/v2/search`	`/v1/gifs/search`	See pagination differences below

Try GIF Search in API Explorer →

Search Stickers

Tenor	GIPHY	Notes
`/v2/search?searchfilter=sticker`	`/v1/stickers/search`	Uses URL slug instead of query parameter

Key Difference: GIPHY excludes low-contrast stickers if remove_low_contrast=true

Trending / Featured

Tenor	GIPHY
`/v2/featured`	`/v1/gifs/trending`
`/v2/featured?searchfilter=sticker`	`/v1/stickers/trending`

Try Trending in API Explorer →

Tenor	GIPHY	Notes
`/v2/categories`	`/v1/gifs/categories`	GIPHY provides the category's featured GIF

Autocomplete

Tenor	GIPHY
`/v2/autocomplete`	`/v1/gifs/search/tags`

Both require q parameter. Optional pagination parameters supported.

Search Suggestions

Tenor	GIPHY
`/v2/search_suggestions` (uses `q`)	`/v1/tags/related/<term>`

Trending Search Terms

Tenor	GIPHY
`/v2/trending_terms`	`/v1/trending/searches`

Fetch by IDs

Tenor	GIPHY	Notes
`/v2/posts?ids=<ids>`	`/v1/gifs?ids=<ids>`	Both use comma-separated list
—	`/v1/gifs/:id`	GIPHY also offers single-ID endpoint

Random

Tenor	GIPHY
`/v2/search?random=true`	`/v1/gifs/random`
`/v2/search?random=true&searchfilter=sticker`	`/v1/stickers/random`

KEY DIFFERENCE

Tenor returns a list of random results.

GIPHY returns a single random item.

Try Random in API Explorer →

Random ID

Tenor	GIPHY
`/v2/anonid`	`/v1/randomid`

Parameter Changes

Pagination

CRITICAL CHANGE

Tenor uses a token-based pagination system with pos and next values.

GIPHY uses a simple numeric offset model with offset and limit.

Unlike Tenor, which uses opaque cursor tokens, GIPHY uses a simple numeric offset representing how many results to skip.

offset=25 returns results starting from the 26th item
Calculate subsequent pages by incrementing the offset by your limit parameter
GIPHY responses do not include a next cursor
Pagination state is entirely controlled by request parameters

Before (Tenor)

Copy Code

// First page
const response1 = await fetch('https://tenor.googleapis.com/v2/search?q=cats&key=KEY');
const data1 = await response1.json();

// Next page using token
const response2 = await fetch(`https://tenor.googleapis.com/v2/search?q=cats&key=KEY&pos=${data1.next}`);

After (GIPHY)

Copy Code

// First page
const response1 = await fetch('https://api.giphy.com/v1/gifs/search?q=cats&api_key=KEY&limit=25&offset=0');
const data1 = await response1.json();

// Next page using numeric offset
const response2 = await fetch('https://api.giphy.com/v1/gifs/search?q=cats&api_key=KEY&limit=25&offset=25');

Content Safety / Rating

Tenor Parameter	GIPHY Parameter	Values
`contentfilter`	`rating`	Tenor: off \| low \| medium \| high GIPHY: r \| pg-13 \| pg \| g

GIPHY defaults to r (restricted). Default and maximum rating can be configured for partners.

User Identifier

Tenor	GIPHY	Notes
`anon_id`	`random_id`	Can be supplied in every GIPHY request

Renditions / Media Formats

Tenor	GIPHY
`media_filter` (basic \| minimal)	`bundle` (clips_grid_picker \| messaging_non_clips \| sticker_layering \| low_bandwidth) OR `fields` parameter for fields on demand

Example: fields=images.original.url,slug

Locale

Tenor	GIPHY
`locale` (xx_YY or YY)	`lang` + `country_code`

Proxied Requests

GIPHY allows proxying user requests with:

country_code
region_code

Similarities

The following parameters work the same way in both APIs:

q - Search term(s)

Analytics & Tracking

MAJOR CHANGE

Tenor centralizes tracking through /v2/registershare endpoint.

GIPHY decentralizes tracking with per-item analytics URLs.

Tenor: Register Share

Tenor uses a dedicated endpoint /v2/registershare where your backend logs share events directly.

GIPHY: Analytics Object

Each GIPHY item includes an analytics object with event-specific URLs:

analytics.onload.url - Fire when item loads
analytics.onclick.url - Fire when user clicks
analytics.onsent.url - Fire when message is sent

To register interactions:

Fire URLs client-side (GET request)
Append random_id and ts (timestamp) parameters

IMPORTANT

The random_id should be obtained from the /v1/randomid endpoint and used consistently for that user across all API requests and analytics tracking.

Before (Tenor)

Copy Code

// Log share event to backend
await fetch('https://tenor.googleapis.com/v2/registershare', {
  method: 'POST',
  body: JSON.stringify({
    id: gifId,
    key: API_KEY,
    q: searchTerm
  })
});

After (GIPHY)

Copy Code

// Get random_id from GIPHY (once per user, store for future use)
const randomIdResponse = await fetch('https://api.giphy.com/v1/randomid?api_key=YOUR_API_KEY');
const { random_id } = await randomIdResponse.json();

// Use this random_id for all API requests and analytics for this user
const searchResponse = await fetch(`https://api.giphy.com/v1/gifs/search?q=cats&api_key=YOUR_API_KEY&random_id=${random_id}`);
const data = await searchResponse.json();

// Fire analytics URLs client-side
const gif = data.data[0];
const timestamp = Date.now();

// When GIF loads
fetch(`${gif.analytics.onload.url}?random_id=${random_id}&ts=${timestamp}`);

// When user clicks
fetch(`${gif.analytics.onclick.url}?random_id=${random_id}&ts=${timestamp}`);

// When message is sent
fetch(`${gif.analytics.onsent.url}?random_id=${random_id}&ts=${timestamp}`);

Response Schema

Response Body and Status

Platform	Response Structure
Tenor	• Uses standard HTTP status codes • Known errors return HTTP 200 with `error` field • Unknown errors use non-200 codes
GIPHY	• All responses include `meta` object • meta contains: `status`, `msg`, `response_id` • Errors indicated via `meta.status` • Some errors return empty `data` with 4xx status

SYNTHETIC ERROR CASE

If meta.status=200, meta.response_id="" and body is empty, treat as an error.

Always validate data presence in GIPHY responses.

Pagination Results

Tenor	GIPHY
`results`, `next`	`data`, `pagination`, `meta`

Tenor uses next token; GIPHY uses offset + limit in the pagination object.

Tenor Response

Copy Code

{
  "results": [...],
  "next": "CAgQABokCOWW3Y8GMgYIChCAgBASJAj6z96PBjIGCAoQgJAQEiQIqqDejwYyBggKEIDgHA"
}

GIPHY Response

Copy Code

{
  "data": [...],
  "pagination": {
    "total_count": 50000,
    "count": 25,
    "offset": 0
  },
  "meta": {
    "status": 200,
    "msg": "OK",
    "response_id": "abc123def456"
  }
}

HTTP Status Codes

Code	Tenor Description	GIPHY Description	Migration Notes
200	OK or known error	OK; check meta	Validate data presence
3xx	Redirect (rare)	Not documented	Ignore or handle normally
400	Not documented	Bad request	Validate params
401	Not documented	Unauthorized	Verify API key
403	Not documented	Forbidden	Ensure permissions
404	Not found	Not found	Show user-friendly message
414	Not documented	URI too long	Trim queries
429	Rate limit exceeded	Too many requests	100 requests/hour beta limit
5xx	Server error	Synthetic 200	Retry with backoff

GIF / Sticker Object Field Mappings

Core Fields

Tenor Field	GIPHY Equivalent	Notes
`id`	`id`	String ID
`title`	`title`	—
`content_description`	`title` / `alt_text`	If available
`media_formats`	`images`	Remap renditions (see below)
`created`	`create_datetime` / `update_datetime` / `import_datetime` / `trending_datetime`	Unix timestamp → ISO 8601
`tags`	`tags` / `featured_tags` / `user_tags`	Partner-only

Additional Fields

Tenor	GIPHY	Notes
`content_rating`	`rating`	—
`url`	`url`	Also: `embed_url`, `source_post_url`
`itemurl`	`bitly_url`	Shareable short URL
`hasaudio`	—	No equivalent
`hascaption`	—	No equivalent
`flags`	`is_sticker` / `is_low_contrast`	Boolean flags

GIPHY user data includes username and public user info when available.

Rendition Mapping Guide

RECOMMENDATION

Use MP4 and WEBP formats where supported to maximize quality and reduce load time.

GIPHY provides more rendition options than Tenor for better optimization.

GIF & Video Renditions

Tenor Format	Typical Use	GIPHY Equivalent	Notes
`preview`	Single-frame GIF	`preview_gif` / `fixed_*_still`	Preloading
`gif`	Full GIF	`original`	Loops automatically
`mediumgif`	Reduced GIF	`downsized` / `downsized_medium`	2–5 MB
`tinygif`	Small GIF	`fixed_width` / `fixed_height`	~200px
`nanogif`	Very small GIF	`fixed_*_small`	~100px
`mp4`	Full MP4	`original.mp4` / `hd.mp4` / `4k.mp4`	Plays once
`loopedmp4`	Looping MP4	`looping.mp4`	15s loop
`tinymp4`	Reduced MP4	`fixed_*.mp4`	Mobile optimized
`nanomp4`	Smallest MP4	`fixed_*_small.mp4` / `preview.mp4`	Low bandwidth
`webm`	Video	`original.webp` (animated)	Not a video format

Transparent Sticker Renditions

Tenor Format	GIPHY Equivalent	Notes
`webp_transparent`	`original.webp`	Full quality WebP with transparency
`tinywebp_transparent`	`fixed_width.webp` / `fixed_height.webp`	~200px with transparency
`nanowebp_transparent`	`fixed_*_small.webp`	~100px with transparency
`gif_transparent`	`original.gif` (stickers)	GIF with transparency layer
`tinygif_transparent`	`fixed_width.gif` / `fixed_height.gif`	Small transparent GIF
`nanogif_transparent`	`fixed_*_small.gif`	Smallest transparent GIF

Accessing Renditions

Copy Code

// GIPHY response structure
const gif = data.data[0];

// Original (highest quality)
const originalUrl = gif.images.original.url;
const originalMp4 = gif.images.original.mp4;

// Fixed width (responsive)
const fixedWidth = gif.images.fixed_width.url;
const fixedWidthMp4 = gif.images.fixed_width.mp4;

// Downsized (optimized)
const downsized = gif.images.downsized.url;

// Preview (still frame)
const previewGif = gif.images.preview_gif.url;

// For stickers with transparency
const stickerWebp = gif.images.original.webp;

Migration Checklist

Follow this checklist to ensure a smooth migration from Tenor to GIPHY:

1. Authentication & Setup

☐ Create a new API key in the GIPHY Developer Dashboard
☐ Update base URL from tenor.googleapis.com to api.giphy.com
☐ Replace key parameter with api_key in all requests

2. Update Endpoints

☐ Map search endpoints: /v2/search → /v1/gifs/search
☐ Update sticker searches: use /v1/stickers/search instead of searchfilter param
☐ Map trending: /v2/featured → /v1/gifs/trending
☐ Update autocomplete: /v2/autocomplete → /v1/gifs/search/tags
☐ Map random: /v2/search?random=true → /v1/gifs/random
☐ Update ID fetching: /v2/posts → /v1/gifs

3. Modify Request Parameters

☐ Replace pagination: pos token → offset numeric value
☐ Update content filtering: contentfilter → rating
☐ Change user ID: anon_id → random_id
☐ Update locale: locale → lang + country_code
☐ Modify rendition requests: media_filter → bundle or fields

4. Update Response Parsing

☐ Change array access: results → data
☐ Add meta object validation
☐ Handle synthetic error cases (empty body with status 200)
☐ Update pagination logic (no more next token)
☐ Map object fields: media_formats → images
☐ Update timestamp parsing: Unix → ISO 8601

5. Implement Analytics Tracking

☐ Remove /v2/registershare backend calls
☐ Implement client-side analytics URL firing
☐ Fire analytics.onload.url when GIF loads
☐ Fire analytics.onclick.url when user clicks
☐ Fire analytics.onsent.url when message sent
☐ Append random_id (from /v1/randomid endpoint) and ts to analytics URLs

6. Update Rendition Logic

☐ Map Tenor renditions to GIPHY equivalents
☐ Prefer MP4 formats for better performance
☐ Use WebP for stickers with transparency
☐ Update preview/still frame logic
☐ Handle random endpoint difference (list → single item)

7. Testing & Validation

☐ Test all migrated endpoints with the API Explorer
☐ Verify pagination works correctly with numeric offsets
☐ Confirm analytics tracking fires properly
☐ Test error handling for synthetic 200 errors
☐ Validate renditions display correctly
☐ Check rate limiting (100 requests/hour for beta keys)
☐ Test with different rating values

8. Production Deployment

☐ Update production API keys
☐ Monitor error rates and response times
☐ Set up alerts for rate limit warnings
☐ Document any partner-specific configurations
☐ Update API documentation for your integration

Privacy Terms

Migrating from Tenor to GIPHY API

🚀 Consider Using the GIPHY SDK

IMPORTANT

Authentication

Before (Tenor)

After (GIPHY)

Base URL

Endpoint Mappings

Search GIFs

Search Stickers

Trending / Featured

Categories

Autocomplete

Search Suggestions

Trending Search Terms

Fetch by IDs

Random

KEY DIFFERENCE

Random ID

Parameter Changes

Pagination

CRITICAL CHANGE

Before (Tenor)

After (GIPHY)

Content Safety / Rating

User Identifier

Renditions / Media Formats

Locale

Proxied Requests

Similarities

Analytics & Tracking

MAJOR CHANGE

Tenor: Register Share

GIPHY: Analytics Object

IMPORTANT

Before (Tenor)

After (GIPHY)

Response Schema

Response Body and Status

SYNTHETIC ERROR CASE

Pagination Results

Tenor Response

GIPHY Response

HTTP Status Codes

GIF / Sticker Object Field Mappings

Core Fields

Additional Fields

Rendition Mapping Guide

RECOMMENDATION

GIF & Video Renditions

Transparent Sticker Renditions

Accessing Renditions

Migration Checklist

1. Authentication & Setup

2. Update Endpoints

3. Modify Request Parameters

4. Update Response Parsing

5. Implement Analytics Tracking

6. Update Rendition Logic

7. Testing & Validation

8. Production Deployment