Tenor Compatibility API Guide

One URL change. Same integration. This guide is the primary entry point for clients migrating an existing Tenor integration to GIPHY's Tenor-compatible endpoints with minimal code changes.

In most cases you can be up and running by creating a GIPHY API key, swapping your API host from tenor.googleapis.com to api.giphy.com, and confirming your product follows GIPHY branding requirements.

The sections below document supported endpoints, parameters, and a few compatibility differences.

This guide helps you migrate an existing Tenor client to GIPHY’s Tenor-compatible endpoints with minimal code changes. It is intended for clients that already know the Tenor API shape and want to send Tenor-style requests to GIPHY with minimal changes.

Important Compatibility Notes

Guarded Fields

Some response fields depend on API key capabilities.

If a guarded field is not available for your API key, it is omitted from the response.

Sticker Filtering Limitations

searchfilter=sticker,static and searchfilter=sticker,-static are not supported. Use searchfilter=sticker only.

Client Key & Query Handling

• Use the same client_key value across all API calls for a given integration.
• Send the user's query exactly as typed, including punctuation and special characters.

Pagination

Pagination is supported on /v2/search and /v2/featured.

• The response may include next.
• Send that next value back as pos.
• Treat pos as opaque.
• /v2/posts does not return next.

curl "https://api.giphy.com/v2/search?q=cat&key=$API_KEY&limit=20"
curl "https://api.giphy.com/v2/search?q=cat&key=$API_KEY&limit=20&pos=$NEXT"

Content Filtering

contentfilter maps to the Motion Picture Association rating system:

• off - G, PG, PG-13, R
• low - G, PG, PG-13
• medium - G, PG
• high - G

Refer to GIPHY rating guide for more details

Renditions

media_filter supports the following rendition names:

Register Share

/v2/registershare is not implemented as a direct compatibility endpoint. For share analytics, use the analytics URLs returned on each GIPHY item instead.

Fire these URLs client-side as GET requests and append random_id and ts for tracking.

Example Request

const gif = data.results[0];
const timestamp = Date.now();

// Share/send event equivalent for /v2/registershare
fetch(`${gif.analytics.onsent.url}?random_id=${random_id}&ts=${timestamp}`);

// Additional supported analytics events
fetch(`${gif.analytics.onclick.url}?random_id=${random_id}&ts=${timestamp}`);
fetch(`${gif.analytics.onload.url}?random_id=${random_id}&ts=${timestamp}`);

Endpoint Details

Search Endpoint

Search for GIFs or stickers while keeping the Tenor-compatible request and response shape.

• Responses include top-level results and optional next.
• Use searchfilter=sticker for sticker content.
• searchfilter=static, searchfilter=-static, ar_range, and random are not supported.

Successful Response (200 OK)

Example Request

curl "https://api.giphy.com/v2/search?q=cat&key=$API_KEY&client_key=my_app&limit=10&country=US&locale=en_US"
curl "https://api.giphy.com/v2/search?q=cat&key=$API_KEY&client_key=my_app&searchfilter=sticker&limit=10"
curl "https://api.giphy.com/v2/search?q=cat&key=$API_KEY&media_filter=gif,mp4,tinygif"

Featured Endpoint

Get featured or trending GIFs or stickers through the compatibility layer.

• Responses include top-level results and optional next.
• Use searchfilter=sticker for sticker content.
• searchfilter=static, searchfilter=-static, and ar_range are not supported.

Successful Response (200 OK)

Example Request

curl "https://api.giphy.com/v2/featured?key=$API_KEY&client_key=my_app&limit=10&country=US&locale=en_US"
curl "https://api.giphy.com/v2/featured?key=$API_KEY&searchfilter=sticker&limit=10"

Posts Endpoint

Fetch content by ID while preserving the Tenor-style response contract.

• Responses include top-level results and do not include next.
• This compatibility layer also accepts contentfilter on this route.

Successful Response (200 OK)

Example Request

curl "https://api.giphy.com/v2/posts?key=$API_KEY&client_key=my_app&ids=id1,id2,id3"
curl "https://api.giphy.com/v2/posts?key=$API_KEY&ids=id1,id2,id3&media_filter=gif,mp4"

Categories Endpoint

Fetch category metadata in a Tenor-style format.

• Responses include top-level tags.
• Only featured and trending values are supported for type.

Successful Response (200 OK)

Example Request

curl "https://api.giphy.com/v2/categories?key=$API_KEY&client_key=my_app&country=US&locale=en_US&type=featured&contentfilter=medium"

Autocomplete Endpoint

Get search autocomplete suggestions. Returns up to 20 terms.

• Responses include top-level results.
• Empty or missing q returns empty results.

Successful Response (200 OK)

Example Request

curl "https://api.giphy.com/v2/autocomplete?key=$API_KEY&client_key=my_app&q=exc&limit=10&country=US&locale=en_US"

Search Suggestions Endpoint

Get related search terms. Returns up to 20 terms.

• Responses include top-level results.
• Empty or missing q returns empty results.

Successful Response (200 OK)

Example Request

curl "https://api.giphy.com/v2/search_suggestions?key=$API_KEY&client_key=my_app&q=smile&limit=10&country=US&locale=en_US"

Trending Terms Endpoint

Get trending search terms. Returns up to 20 terms.

• Responses include top-level results.
• limit is not currently implemented on this compatibility route.

Successful Response (200 OK)

Example Request

curl "https://api.giphy.com/v2/trending_terms?key=$API_KEY&client_key=my_app&country=US&locale=en_US"

Native GIPHY Experience Guide

The compatibility guide above is the fastest path for existing Tenor clients. Use the following migration guide to understand and implement a native GIPHY experience with direct /v1/* endpoints, native schema mapping, and deeper integration details.

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.

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

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

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

Base URL

Endpoint Mappings

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

Search GIFs

Search Stickers

Trending / Featured

Categories

Autocomplete

Both require q parameter. Optional pagination parameters supported.

Search Suggestions

Trending Search Terms

Fetch by IDs

Random

Random ID

Parameter Changes

Pagination

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

// 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}`);

// 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

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

User Identifier

Renditions / Media Formats

Example: fields=images.original.url,slug

Locale

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

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 customer_id and ts (timestamp) parameters

// 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
  })
});

// Use your own stable user ID, or the value returned by GIPHY's Random ID endpoint
const customerId = getUserIdFromYourPlatform(); // or (await fetch('https://api.giphy.com/v1/randomid?api_key=YOUR_API_KEY').then((res) => res.json())).random_id

// Use this customer_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&customer_id=${customerId}`);
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}?customer_id=${customerId}&ts=${timestamp}`);

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

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

Response Schema

Response Body and Status

Pagination Results

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

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

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

HTTP Status Codes

GIF / Sticker Object Field Mappings

Core Fields

Additional Fields

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

Rendition Mapping Guide

GIF & Video Renditions

Transparent Sticker Renditions

// 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: