Quickstart Guide

Welcome to Tenor! Tenor takes a data-centric approach to delivering the most relevant GIF search in over 35 languages worldwide. Integrate Tenor GIF search into your application in a matter of minutes.

API Highlights

Tenor’s GIF Keyboard is the top-downloaded mobile GIF-sharing app and developers can incorporate every feature of Tenor into their own application with our APIs. Highlights include:

Search across the most engaging and relevant GIFs on the internet

Rich features to ensure your users find the most precise GIF quickly

Support for 35+ languages, localized content and regional content appropriateness

Optimized to deliver GIFs that load and consume less bandwidth for every use case

BEFORE YOU BEGIN

Get a Tenor API Key

Get a free API key for your app in less than 60 seconds. View your key in your developer dashboard.

Step 1 - Implement Search

Tenor Search delivers the most relevant and engaging GIFs in 35+ languages. Tenor receives over 300 million searches per day and continuously learns the best GIF results for every query based on user search and share behavior.

We recommend that you initial load one of the smaller optimized GIF sizes for previews (response object “tinygif”), then load and display the full sized GIF (response object “gif“) when the user shares.

For our example search request, we’ll be using the search endpoint and requesting the top 8 ranked GIFs for the search term “excited”.

EXAMPLE REQUESTS

Curl

Python

Android/Java

Swift 2.0+ / iOS

Javascript

Objective-C

/* search for excited top 8 GIFs */
curl "https://g.tenor.com/v1/search?q=excited&key=LIVDSRZULELA&limit=8"

Step 2 - Implement Share Events

When a user selects a GIF to share, send a corresponding share event to Tenor. Share events help Tenor’s Search Engine AI tune search results, helping users find the perfect GIF.

For our example, we’re using the registered shared endpoint with the 1st GIF result returned for the search term “excited”

EXAMPLE REQUESTS

Curl

Python

Android/Java

Swift 2.0+ / iOS

Javascript

Objective-C

/* register share */

curl "https://g.tenor.com/v1/registershare?id=8776030&key=LIVDSRZULELA&q=excited"

ATTRIBUTION

Review Attribution Examples

All content retrieved from Tenor must be properly attributed by including one of the three Attribution options.

Congratulations! You’ve successfully integrated with Tenor’s API!

Now let’s improve the user experience!

Step 3 - Enrich the Search Experience

In this step we’ll review best practices that improve the user experience and increase searches and shares from your Tenor GIF integration.

A - Launching your Search experience

We have found the best initial experience is to display a clean search bar followed by categories of GIFs (from the categories endpoint) and trending search terms (from the Trending Search Terms endpoint). Alternatively, trending GIFs (from the Trending GIFs endpoint) can be displayed beneath search.

(Optional) Use the Locale parameter. As Tenor’s service evolves, locale will be used to better tune search results to your users’ specific languages, cultures, and social trends. Using Locale will give higher preference to the user’s given locale, though it will not limit trending results to only the provided code and language typed, but gives higher preference to the given locale. The default value is en_US.

In the example below we’ll fetch Tenor categories and trending GIFs to display to the user.

EXAMPLE REQUESTS

Curl

Python

Android/Java

Swift 2.0+ / iOS

Javascript

Objective-C

/* trending GIFs call */
curl "https://g.tenor.com/v1/trending?key=LIVDSRZULELA"

/* categories call */
curl "https://g.tenor.com/v1/categories?key=LIVDSRZULELA"

B - Autocomplete Suggestions

Displaying autocomplete search options as a user is typing helps users complete GIF searches faster, which increases GIF usage and retention.

We recommend passing up at least two characters and the user’s locale.

In the example below we call the autocomplete endpoint with partial search term of “exc” -- results are ordered by likelihood to drive a share for any given partial term.

EXAMPLE REQUESTS

Curl

Python

Android/Java

Swift 2.0+ / iOS

Javascript

Objective-C

/* autocomplete */

curl "https://g.tenor.com/v1/autocomplete?q=exc&key=LIVDSRZULELA"

C - Search Suggestions

Search suggestions helps a user narrow their search or discover related search terms to find a more precise GIF.

Often users don’t know exactly what they are looking for, and search suggestions help them correct spelling mistakes or find more similar terms.

Results are returned in order of what is most likely to drive a GIF share for a given term. The example below returns the top 5 search suggestions for the search term “smile”:

EXAMPLE REQUESTS

Curl

Python

Android/Java

Swift 2.0+ / iOS

Javascript

Objective-C

/* search suggestion */

curl "https://g.tenor.com/v1/search_suggestions?q=smile&key=LIVDSRZULELA&limit=5"

Endpoints

Search

Base Url:

https://g.tenor.com/v1/search?<parameters>

Get a json object containing a list of the most relevant GIFs for a given search term(s), category(ies), emoji(s), or any combination thereof.

Best Practices:

Provide the user’s search as typed, including punctuation and special characters.
Use the Locale parameter. As Tenor’s service evolves, locale will be used to better tune search results to your users’ specific languages, cultures, and social trends. Using Locale will give higher preference to the user’s given locale, though it will not limit search results to only the provided code and language typed, but gives higher preference to the given locale. The default value is en_US.
When a user decides which GIF to share, you should also include a corresponding call to Register Share. This optional call helps Tenor’s Search Engine AI tune results.
Use the limit and pos parameters to control the amount and flow of GIFs returned. For example, set limit = 10 for the user’s initial results of a given search and load previews of those GIFs for the user to browse. If the user requests more results, collect the next 10 results by making the same API call but with pos = the “next” field from the initial response. This pattern can be used to create a smooth lazy loading experience. Doing so will help keep bandwidth usage down and provide a quicker response time for the user — as less GIF previews will need to be loaded in parallel on the client’s side.
Use the ContentFilter parameter to maintain your internal content safety ratings for GIFs returned. The default value is off
Use the media_filter parameter to reduce the number of GIF formats returned. This can reduce the response object size by 25-75%.
Use the ar_range parameter to filter the GIF response list to only include aspect ratios that fall within the selected range.

PARAMETERS

NAME	TYPE	DEFAULT VALUE	DESCRIPTION
key REQUIRED	string	n/a	client key for privileged API access
DESCRIPTION client key for privileged API access
q REQUIRED	string	n/a	a search string
DESCRIPTION a search string
locale STRONGLY RECOMMENDED	string (xx_YY)	en_US	specify default language to interpret search string; xx is ISO 639-1 language code, _YY (optional) is 2-letter ISO 3166-1 country code
DESCRIPTION specify default language to interpret search string; xx is ISO 639-1 language code, _YY (optional) is 2-letter ISO 3166-1 country code
contentfilter STRONGLY RECOMMENDED	enum	off	(values: off \| low \| medium \| high) specify the content safety filter level
DESCRIPTION (values: off \| low \| medium \| high) specify the content safety filter level
media_filter STRONGLY RECOMMENDED	string	n/a	(values: basic \| minimal) Reduce the Number of GIF formats returned in the GIF_OBJECT list. minimal - tinygif, gif, and mp4. basic - nanomp4, tinygif, tinymp4, gif, mp4, and nanogif
DESCRIPTION (values: basic \| minimal) Reduce the Number of GIF formats returned in the GIF_OBJECT list. minimal - tinygif, gif, and mp4. basic - nanomp4, tinygif, tinymp4, gif, mp4, and nanogif
ar_range STRONGLY RECOMMENDED	string	all	(values: all \| wide \| standard ) Filter the response GIF_OBJECT list to only include GIFs with aspect ratios that fit with in the selected range. all - no constraints wide - 0.42 <= aspect ratio <= 2.36 standard - .56 <= aspect ratio <= 1.78
DESCRIPTION (values: all \| wide \| standard ) Filter the response GIF_OBJECT list to only include GIFs with aspect ratios that fit with in the selected range. all - no constraints wide - 0.42 <= aspect ratio <= 2.36 standard - .56 <= aspect ratio <= 1.78
limit OPTIONAL	integer	20	fetch up to a specified number of results (max: 50).
DESCRIPTION fetch up to a specified number of results (max: 50).
pos OPTIONAL	string	n/a	get results starting at position "value". Use a non-zero "next" value returned by API results to get the next set of results. pos is not an index and may be an integer, float, or string
DESCRIPTION get results starting at position "value". Use a non-zero "next" value returned by API results to get the next set of results. pos is not an index and may be an integer, float, or string
anon_id OPTIONAL	string	n/a	specify the anonymous_id tied to the given user
DESCRIPTION specify the anonymous_id tied to the given user

RESPONSE FORMAT

KEY	VALUE TYPE	DESCRIPTION
next	string	a position identifier to use with the next API query to retrieve the next set of results, or 0 if there are no further results.
DESCRIPTION a position identifier to use with the next API query to retrieve the next set of results, or 0 if there are no further results.
results	GIF_OBJECT[]	an array of GIF_OBJECTS containing the most relevant GIFs for the requested search term - Sorted by relevancy Rank
DESCRIPTION an array of GIF_OBJECTS containing the most relevant GIFs for the requested search term - Sorted by relevancy Rank

EXAMPLE REQUESTS

Curl

Python

Android/Java

Swift 2.0+ / iOS

Javascript

Objective-C

/* search for excited top 8 GIFs */

curl "https://g.tenor.com/v1/search?q=excited&key=LIVDSRZULELA&limit=8"

Trending GIFs

Base URL:

https://g.tenor.com/v1/trending?<parameters>

Get a json object containing a list of the current global trending GIFs. The trending stream is updated regularly throughout the day.

Best Practices:

Use the Locale parameter. As Tenor’s service evolves, locale will be used to better tune search results to your users’ specific languages, cultures, and social trends. Using Locale will give higher preference to the user’s given locale, though it will not limit trending results to only the provided code and language typed, but gives higher preference to the given locale. The default value is en_US.
When a user decides which GIF to share, you should also include a corresponding call to Register Share. This optional call helps Tenor’s Search Engine AI tune results.
Use the Limit and Pos parameters to control the amount and flow of GIFs returned and ultimately loaded. For example, set limit = 10 for the user’s initial results of a trending request and load previews of those GIFs for the user to browse. If the user requests more results, collect the next 10 results by making the same API call but with Pos = the “next” field from the initial response. This pattern can be used to create a smooth lazy loading experience. Doing so will help keep bandwidth usage down and provide a quicker response time for the user as less GIF previews will need to be loaded in parallel on client side.
Use the ContentFilter Parameter to specify the appropriate GIF content safety rating for your service or application.
Use the media_filter parameter to reduce the number of GIF formats returned. This can reduce the response object size by 25-75%.
Use the ar_range parameter to filter the GIF response list to only include aspect ratios that fall within the selected range.

PARAMETERS

NAME	TYPE	DEFAULT VALUE	DESCRIPTION
key REQUIRED	string	n/a	client key for privileged API access
DESCRIPTION client key for privileged API access
locale STRONGLY RECOMMENDED	string (xx_YY)	en_US	specify default language to interpret search string; xx is ISO 639-1 language code, _YY (optional) is 2-letter ISO 3166-1 country code
DESCRIPTION specify default language to interpret search string; xx is ISO 639-1 language code, _YY (optional) is 2-letter ISO 3166-1 country code
media_filter STRONGLY RECOMMENDED	string	n/a	(values: basic \| minimal) Reduce the Number of GIF formats returned in the GIF_OBJECT list. minimal - tinygif, gif, and mp4. basic - nanomp4, tinygif, tinymp4, gif, mp4, and nanogif
DESCRIPTION (values: basic \| minimal) Reduce the Number of GIF formats returned in the GIF_OBJECT list. minimal - tinygif, gif, and mp4. basic - nanomp4, tinygif, tinymp4, gif, mp4, and nanogif
ar_range STRONGLY RECOMMENDED	string	all	(values: all \| wide \| standard ) Filter the response GIF_OBJECT list to only include GIFs with aspect ratios that fit with in the selected range. all - no constraints wide - 0.42 <= aspect ratio <= 2.36 standard - .56 <= aspect ratio <= 1.78
DESCRIPTION (values: all \| wide \| standard ) Filter the response GIF_OBJECT list to only include GIFs with aspect ratios that fit with in the selected range. all - no constraints wide - 0.42 <= aspect ratio <= 2.36 standard - .56 <= aspect ratio <= 1.78
contentfilter STRONGLY RECOMMENDED	enum	off	(values: off \| low \| medium \| high) specify the content safety filter level
DESCRIPTION (values: off \| low \| medium \| high) specify the content safety filter level
limit OPTIONAL	integer	20	fetch up to a specified number of results (max: 50).
DESCRIPTION fetch up to a specified number of results (max: 50).
pos OPTIONAL	string	n/a	get results starting at position "value". Use a non-zero "next" value returned by API results to get the next set of results. pos is not an index and may be an integer, float, or string
DESCRIPTION get results starting at position "value". Use a non-zero "next" value returned by API results to get the next set of results. pos is not an index and may be an integer, float, or string
anon_id OPTIONAL	string	n/a	specify the anonymous_id tied to the given user
DESCRIPTION specify the anonymous_id tied to the given user

RESPONSE FORMAT

KEY	VALUE TYPE	DESCRIPTION
next	string	a position identifier to use with the next API query to retrieve the next set of results, or 0 if there are no further results.
DESCRIPTION a position identifier to use with the next API query to retrieve the next set of results, or 0 if there are no further results.
results	GIF_OBJECT[]	an array of Trending GIF_OBJECTS sorted by Trending Rank
DESCRIPTION an array of Trending GIF_OBJECTS sorted by Trending Rank

EXAMPLE REQUESTS

Curl

Python

Android/Java

Swift 2.0+ / iOS

Javascript

Objective-C

/* trending GIFs call */

curl "https://g.tenor.com/v1/trending?key=LIVDSRZULELA"

KEY	VALUE TYPE	DESCRIPTION
tags	CATEGORY_OBJECT[]	an array of CATEGORY_OBJECTS where the “name” field has been translated to the passed in locale language.
DESCRIPTION an array of CATEGORY_OBJECTS where the “name” field has been translated to the passed in locale language.

Search Suggestions

Base URL:

https://g.tenor.com/v1/search_suggestions?<parameters>

Get a json object containing a list of alternative search terms given a search term.

Search suggestions helps a user narrow their search or discover related search terms to find a more precise GIF. Results are returned in order of what is most likely to drive a share for a given term, based on historic user search and share behavior.

Best Practices:

Use the Locale parameter. As Tenor’s service evolves, locale will be used to better tune search results to your users’ specific languages, cultures, and social trends. Using Locale will give higher preference to the user’s given locale, though it will not limit search results to only the provided code and language typed, but gives higher preference to the given locale. The default value is en_US.
Display the results in the order provided by the response object.

PARAMETERS

NAME	TYPE	DEFAULT VALUE	DESCRIPTION
key REQUIRED	string	n/a	client key for privileged API access
DESCRIPTION client key for privileged API access
q REQUIRED	string	n/a	a search string
DESCRIPTION a search string
locale STRONGLY RECOMMENDED	string (xx_YY)	en_US	specify default language to interpret search string; xx is ISO 639-1 language code, _YY (optional) is 2-letter ISO 3166-1 country code
DESCRIPTION specify default language to interpret search string; xx is ISO 639-1 language code, _YY (optional) is 2-letter ISO 3166-1 country code
limit OPTIONAL	integer	20	fetch up to a specified number of results (max: 50).
DESCRIPTION fetch up to a specified number of results (max: 50).
anon_id OPTIONAL	string	n/a	specify the anonymous_id tied to the given user
DESCRIPTION specify the anonymous_id tied to the given user

RESPONSE FORMAT

KEY	VALUE TYPE	DESCRIPTION
results	String[]	An array of suggested search terms.
DESCRIPTION An array of suggested search terms.

EXAMPLE REQUESTS

Curl

Python

Android/Java

Swift 2.0+ / iOS

Javascript

Objective-C

/* search suggestion */

curl "https://g.tenor.com/v1/search_suggestions?q=excited&key=LIVDSRZULELA"

Autocomplete

Base URL:

https://g.tenor.com/v1/autocomplete?q=<term>&key=<API KEY>

Get a json object containing a list of completed search terms given a partial search term. The list is sorted by Tenor’s AI and the number of results will decrease as Tenor’s AI becomes more certain.

Best Practices:

Use the Locale parameter. As Tenor’s service evolves, locale will be used to better tune search results to your users’ specific languages, cultures, and social trends. Using Locale will give higher preference to the user’s given locale, though it will not limit search results to only the provided code and language typed, but gives higher preference to the given locale. The default value is en_US.
Display the results in the order provided by the response object.

PARAMETERS

NAME	TYPE	DEFAULT VALUE	DESCRIPTION
key REQUIRED	string	n/a	client key for privileged API access
DESCRIPTION client key for privileged API access
q REQUIRED	string	n/a	a search string
DESCRIPTION a search string
locale STRONGLY RECOMMENDED	string (xx_YY)	en_US	specify default language to interpret search string; xx is ISO 639-1 language code, _YY (optional) is 2-letter ISO 3166-1 country code
DESCRIPTION specify default language to interpret search string; xx is ISO 639-1 language code, _YY (optional) is 2-letter ISO 3166-1 country code
limit OPTIONAL	integer	20	fetch up to a specified number of results (max: 50).
DESCRIPTION fetch up to a specified number of results (max: 50).
anon_id OPTIONAL	string	n/a	specify the anonymous_id tied to the given user
DESCRIPTION specify the anonymous_id tied to the given user

RESPONSE FORMAT

KEY	VALUE TYPE	DESCRIPTION
results	String[]	An array of suggested search terms.
DESCRIPTION An array of suggested search terms.

EXAMPLE REQUESTS

Curl

Python

Android/Java

Swift 2.0+ / iOS

Javascript

Objective-C

/* autocomplete */

curl "https://g.tenor.com/v1/autocomplete?q=exc&key=LIVDSRZULELA"

Trending Search Terms

Base URL:

https://g.tenor.com/v1/trending_terms?<parameters>

Get a json object containing a list of the current trending search terms. The list is updated Hourly by Tenor’s AI.

Best Practices:

Use the Locale parameter. As Tenor’s service evolves, locale will be used to better tune search results to your users’ specific languages, cultures, and social trends. Using Locale will give higher preference to the user’s given locale, though it will not limit search results to only the provided code and language typed, but gives higher preference to the given locale. The default value is en_US.
Display the results in the order provided by the response object.

PARAMETERS

NAME	TYPE	DEFAULT VALUE	DESCRIPTION
key REQUIRED	string	n/a	client key for privileged API access
DESCRIPTION client key for privileged API access
locale STRONGLY RECOMMENDED	string (xx_YY)	en_US	specify default language to interpret search string; xx is ISO 639-1 language code, _YY (optional) is 2-letter ISO 3166-1 country code
DESCRIPTION specify default language to interpret search string; xx is ISO 639-1 language code, _YY (optional) is 2-letter ISO 3166-1 country code
limit OPTIONAL	integer	20	fetch up to a specified number of results (max: 50).
DESCRIPTION fetch up to a specified number of results (max: 50).
anon_id OPTIONAL	string	n/a	specify the anonymous_id tied to the given user
DESCRIPTION specify the anonymous_id tied to the given user

RESPONSE FORMAT

KEY	VALUE TYPE	DESCRIPTION
results	String[]	An array of suggested search terms. Sorted by Trending Rank.
DESCRIPTION An array of suggested search terms. Sorted by Trending Rank.

EXAMPLE REQUESTS

Curl

Python

Android/Java

Swift 2.0+ / iOS

Javascript

Objective-C

/* trending Terms call */

curl "https://g.tenor.com/v1/trending_terms?key=LIVDSRZULELA"

Register Share

Base URL:

https://g.tenor.com/v1/registershare?<parameters>

Best Practices:

Provide the search term. This helps further tune Tenor’s Search Engine AI, helping users more easily find the perfect GIF.
Use the Locale parameter. As Tenor’s service evolves, locale will be used to better tune search results to your users’ specific languages, cultures, and social trends. The default value is en_US.

PARAMETERS

NAME	TYPE	DEFAULT VALUE	DESCRIPTION
key REQUIRED	string	n/a	client key for privileged API access
DESCRIPTION client key for privileged API access
id REQUIRED	string	n/a	the “id” of a GIF_OBJECT
DESCRIPTION the “id” of a GIF_OBJECT
locale STRONGLY RECOMMENDED	string (xx_YY)	en_US	specify default language to interpret search string; xx is ISO 639-1 language code, _YY (optional) is 2-letter ISO 3166-1 country code
DESCRIPTION specify default language to interpret search string; xx is ISO 639-1 language code, _YY (optional) is 2-letter ISO 3166-1 country code
q STRONGLY RECOMMENDED	string	n/a	The search string that lead to this share
DESCRIPTION The search string that lead to this share
anon_id OPTIONAL	string	n/a	specify the anonymous_id tied to the given user
DESCRIPTION specify the anonymous_id tied to the given user

RESPONSE FORMAT

KEY	VALUE TYPE	DESCRIPTION
status	String	set to “ok” if share registration was successful
DESCRIPTION set to “ok” if share registration was successful

EXAMPLE REQUESTS

Curl

Python

Android/Java

Swift 2.0+ / iOS

Javascript

Objective-C

/* register share */

curl "https://g.tenor.com/v1/registershare?id=8776030&q=excited&key=LIVDSRZULELA"

GIFs

Base URL:

https://g.tenor.com/v1/gifs?<parameters>

Get the GIF(s) for the corresponding id(s)

Best Practices:

Use the media_filter parameter to reduce the number of GIF formats returned. This can reduce the response object size by 25-75%.

PARAMETERS

NAME	TYPE	DEFAULT VALUE	DESCRIPTION
ids REQUIRED	string	n/a	a comma separated list of GIF IDs (max: 50)
DESCRIPTION a comma separated list of GIF IDs (max: 50)
key REQUIRED	string	n/a	client key for privileged API access
DESCRIPTION client key for privileged API access
media_filter STRONGLY RECOMMENDED	string	n/a	(values: basic \| minimal) Reduce the Number of GIF formats returned in the GIF_OBJECT list. minimal - tinygif, gif, and mp4. basic - nanomp4, tinygif, tinymp4, gif, mp4, and nanogif
DESCRIPTION (values: basic \| minimal) Reduce the Number of GIF formats returned in the GIF_OBJECT list. minimal - tinygif, gif, and mp4. basic - nanomp4, tinygif, tinymp4, gif, mp4, and nanogif
limit OPTIONAL	integer	20	fetch up to a specified number of results (max: 50).
DESCRIPTION fetch up to a specified number of results (max: 50).
pos OPTIONAL	string	n/a	get results starting at position "value". Use a non-zero "next" value returned by API results to get the next set of results. pos is not an index and may be an integer, float, or string
DESCRIPTION get results starting at position "value". Use a non-zero "next" value returned by API results to get the next set of results. pos is not an index and may be an integer, float, or string
anon_id OPTIONAL	string	n/a	specify the anonymous_id tied to the given user
DESCRIPTION specify the anonymous_id tied to the given user

RESPONSE FORMAT

KEY	VALUE TYPE	DESCRIPTION
next	string	a position identifier to use with the next API query to retrieve the next set of results, or 0 if there are no further results.
DESCRIPTION a position identifier to use with the next API query to retrieve the next set of results, or 0 if there are no further results.
results	GIF_OBJECT[]	an array of GIF_OBJECTS corresponding to the passed in GIF id list
DESCRIPTION an array of GIF_OBJECTS corresponding to the passed in GIF id list

EXAMPLE REQUESTS

Curl

Python

Android/Java

Swift 2.0+ / iOS

Javascript

Objective-C

/* GIFs endpoint */

curl "https://g.tenor.com/v1/gifs?ids=8776030&key=LIVDSRZULELA"

Random GIFs

Base URL:

https://g.tenor.com/v1/random?<parameters>

Get a randomized list of GIFs for a given search term. This differs from the search endpoint which returns a rank ordered list of GIFs for a given search term.

Best Practices:

Use the Locale parameter. As Tenor’s service evolves, locale will be used to better tune search results to your users’ specific languages, cultures, and social trends. Using Locale will give higher preference to the user’s given locale, though it will not limit search results to only the provided code and language typed, but gives higher preference to the given locale. The default value is en_US.
Use the ContentFilter parameter to maintain your internal content safety ratings for GIFs returned. The default value is off
Use the media_filter parameter to reduce the number of GIF formats returned. This can reduce the response object size by 25-75%.
Use the ar_range parameter to filter the GIF response list to only include aspect ratios that fall within the selected range.

PARAMETERS

NAME	TYPE	DEFAULT VALUE	DESCRIPTION
key REQUIRED	string	n/a	client key for privileged API access
DESCRIPTION client key for privileged API access
q REQUIRED	string	n/a	a search string
DESCRIPTION a search string
locale STRONGLY RECOMMENDED	string (xx_YY)	en_US	specify default language to interpret search string; xx is ISO 639-1 language code, _YY (optional) is 2-letter ISO 3166-1 country code
DESCRIPTION specify default language to interpret search string; xx is ISO 639-1 language code, _YY (optional) is 2-letter ISO 3166-1 country code
contentfilter STRONGLY RECOMMENDED	enum	off	(values: off \| low \| medium \| high) specify the content safety filter level
DESCRIPTION (values: off \| low \| medium \| high) specify the content safety filter level
media_filter STRONGLY RECOMMENDED	string	n/a	(values: basic \| minimal) Reduce the Number of GIF formats returned in the GIF_OBJECT list. minimal - tinygif, gif, and mp4. basic - nanomp4, tinygif, tinymp4, gif, mp4, and nanogif
DESCRIPTION (values: basic \| minimal) Reduce the Number of GIF formats returned in the GIF_OBJECT list. minimal - tinygif, gif, and mp4. basic - nanomp4, tinygif, tinymp4, gif, mp4, and nanogif
ar_range STRONGLY RECOMMENDED	string	all	(values: all \| wide \| standard ) Filter the response GIF_OBJECT list to only include GIFs with aspect ratios that fit with in the selected range. all - no constraints wide - 0.42 <= aspect ratio <= 2.36 standard - .56 <= aspect ratio <= 1.78
DESCRIPTION (values: all \| wide \| standard ) Filter the response GIF_OBJECT list to only include GIFs with aspect ratios that fit with in the selected range. all - no constraints wide - 0.42 <= aspect ratio <= 2.36 standard - .56 <= aspect ratio <= 1.78
limit OPTIONAL	integer	20	fetch up to a specified number of results (max: 50).
DESCRIPTION fetch up to a specified number of results (max: 50).
pos OPTIONAL	string	n/a	get results starting at position "value". Use a non-zero "next" value returned by API results to get the next set of results. pos is not an index and may be an integer, float, or string
DESCRIPTION get results starting at position "value". Use a non-zero "next" value returned by API results to get the next set of results. pos is not an index and may be an integer, float, or string
anon_id OPTIONAL	string	n/a	specify the anonymous_id tied to the given user
DESCRIPTION specify the anonymous_id tied to the given user

RESPONSE FORMAT

KEY	VALUE TYPE	DESCRIPTION
next	string	a position identifier to use with the next API query to retrieve the next set of results, or 0 if there are no further results.
DESCRIPTION a position identifier to use with the next API query to retrieve the next set of results, or 0 if there are no further results.
results	GIF_OBJECT[]	an array of GIF_OBJECTS containing the most relevant GIFs for the requested search term - Sorted by relevancy Rank
DESCRIPTION an array of GIF_OBJECTS containing the most relevant GIFs for the requested search term - Sorted by relevancy Rank

EXAMPLE REQUESTS

Curl

Python

Android/Java

Swift 2.0+ / iOS

Javascript

Objective-C

/* random endpoint */

curl "https://g.tenor.com/v1/random?q=excited&key=LIVDSRZULELA"

Anonymous ID

Base URL:

https://g.tenor.com/v1/anonid?<parameters>

Get an anonymous ID for a new user. Store the ID in the client’s cache for use on any additional API calls made by the user, either in this session or any future sessions. Note: using anonymous ID to personalize API responses requires custom development. Please see the Custom APIs section for more detail.

PARAMETERS

NAME	TYPE	DEFAULT VALUE	DESCRIPTION
key REQUIRED	string	n/a	client key for privileged API access
DESCRIPTION client key for privileged API access

RESPONSE FORMAT

KEY	VALUE TYPE	DESCRIPTION
anon_id	string	an anonymous id used to represent a user. This allows for tracking without the use of personally identifiable information
DESCRIPTION an anonymous id used to represent a user. This allows for tracking without the use of personally identifiable information

EXAMPLE REQUESTS

Curl

Python

Android/Java

Swift 2.0+ / iOS

Javascript

Objective-C

/* anon_id */

curl "https://g.tenor.com/v1/anonid?key=LIVDSRZULELA"

g.tenor.com Domain

Tenor is excited to offer a new domain for our API developers, g.tenor.com. While the domain api.tenor.com will continue to be supported, g.tenor.com offers significant benefits. g.tenor.com has an additional cache layer and is located at edge nodes across the world, resulting in lower average API latencies across all regions. As such, Tenor recommends using g.tenor.com and has updated the documentation to reflect that.

How to switch domains in an existing integration:

Switching domains is a painless process, simply replace any reference to "api.tenor.com" with "g.tenor.com" in your Tenor API url requests. For example, a search call would be updated as follows.

from
"https://api.tenor.com/v1/search?q=excited&key=LIVDSRZULELA&limit=8"
to
"https://g.tenor.com/v1/search?q=excited&key=LIVDSRZULELA&limit=8"

Custom APIs & Extended Access

We develop custom endpoints and offer extended access to deliver the most engaging experience for a partner and their users.

What type of custom APIs?

Custom APIs that increase searches and shares. This tends to be unique to a particular partner’s use case and userbase. For example, using the anonymous ID (anon_id) parameter which personalizes the GIF experience per user by tuning Tenor’s algorithms towards a user’s preferences over time. Note anonymous ID (anon_id) and other custom work requires development partner by partner and the best candidates are partners with a sizable install base, eg DAU of tens of millions or more.

What type of extended access?

We also provide extended access to a number of features that enable a partner to have more granular controls in creating the GIF experience that best fits their users. Note like the custom work above, the best candidates for extended access are partners with a sizable install base. Examples include:

Flagging - ability for a partner to flag a particular GIF, notifying Tenor and removing the GIF from the partner’s library until investigated
Graylist - access to a list of search terms that can be blocked. This functions independently of contentfilter
Tagging - access to richer metadata per GIF
Regional Filters - the capability to limit certain content based on a particular locale or locales

How do I learn more?

Please email api@tenor.com and we will quickly get back to you with additional information.

Response Objects

GIF_OBJECT

KEY	VALUE TYPE	DESCRIPTION
created	float	a unix timestamp representing when this post was created.
DESCRIPTION a unix timestamp representing when this post was created.
hasaudio	boolean	true if this post contains audio (only video formats support audio, the gif image file format can not contain audio information).
DESCRIPTION true if this post contains audio (only video formats support audio, the gif image file format can not contain audio information).
id	string	Tenor result identifier
DESCRIPTION Tenor result identifier
media	[ { GIF_FORMAT : MEDIA_OBJECT } ]	An array of dictionaries with GIF_FORMAT as the key and MEDIA_OBJECT as the value
DESCRIPTION An array of dictionaries with GIF_FORMAT as the key and MEDIA_OBJECT as the value
tags	string[]	an array of tags for the post
DESCRIPTION an array of tags for the post
title	string	the title of the post.
DESCRIPTION the title of the post.
itemurl	string	the full URL to view the post on tenor.com.
DESCRIPTION the full URL to view the post on tenor.com.
hascaption	boolean	true if this post contains captions
DESCRIPTION true if this post contains captions
url	string	a short URL to view the post on tenor.com.
DESCRIPTION a short URL to view the post on tenor.com.

CATEGORY_OBJECT

KEY	VALUE TYPE	DESCRIPTION
searchterm	string	The english search term that corresponds to the category
DESCRIPTION The english search term that corresponds to the category
path	string	the search url to request if the user selects the category
DESCRIPTION the search url to request if the user selects the category
image	string	a url to the media source for the category’s example GIF
DESCRIPTION a url to the media source for the category’s example GIF
name	string	Category name to overlay over the image. The name will be translated to match the locale of the corresponding request
DESCRIPTION Category name to overlay over the image. The name will be translated to match the locale of the corresponding request

MEDIA_OBJECT

KEY	VALUE TYPE	DESCRIPTION
preview	string	a url to a preview image of the media source
DESCRIPTION a url to a preview image of the media source
url	string	a url to the media source
DESCRIPTION a url to the media source
dims	int[]	width and height in pixels
DESCRIPTION width and height in pixels
size	int	size of file in bytes
DESCRIPTION size of file in bytes

GIF FORMATS

Tenor’s API offers 3 different base formats -- GIF, MP4, and webm -- in a variety of sizes. The MP4 and webm formats will play the clip once -- except for the loopedmp4, which will play the clip a few times. The GIF format will play the clip on a continuous loop.

FORMAT TYPES:

FORMAT TYPE (STRING)	FORMAT INFO	MEDIA FILTERS SUPPORTED
gif	Resolution and size: High quality GIF format, largest file size available Dimensions: Original upload dimensions (no limits) Usage Notes: Use this size for GIF shares on desktop	default, basic, minimal
Format Info Resolution and size: High quality GIF format, largest file size available Dimensions: Original upload dimensions (no limits) Usage Notes: Use this size for GIF shares on desktop
mediumgif	Resolution and size: small reduction in size of the GIF format Dimensions: Original upload dimensions (no limits) but much higher compression rate Usage Notes: Use this size for GIF previews on desktop	default
Format Info Resolution and size: small reduction in size of the GIF format Dimensions: Original upload dimensions (no limits) but much higher compression rate Usage Notes: Use this size for GIF previews on desktop
tinygif	Resolution and size: reduced size of the GIF format Dimensions: Up to 220 pixels wide, Height scaled with aspect ratio preserved Usage Notes: Use this size for GIF previews and shares on mobile	default, basic, minimal
Format Info Resolution and size: reduced size of the GIF format Dimensions: Up to 220 pixels wide, Height scaled with aspect ratio preserved Usage Notes: Use this size for GIF previews and shares on mobile
nanogif	Resolution and size: smallest size of the GIF format Dimensions: Up to 90 pixels tall, Width scaled with aspect ratio preserved Usage Notes: Use this size for GIF previews on mobile	default, basic
Format Info Resolution and size: smallest size of the GIF format Dimensions: Up to 90 pixels tall, Width scaled with aspect ratio preserved Usage Notes: Use this size for GIF previews on mobile
mp4	Resolution and size: highest quality video format, largest of the video formats, but smaller than GIF Dimensions: Similar to gif, but padded to fit video container specifications (usually 8-pixel increments) Usage Notes: Use this size for MP4 previews and shares on desktop	default, basic, minimal
Format Info Resolution and size: highest quality video format, largest of the video formats, but smaller than GIF Dimensions: Similar to gif, but padded to fit video container specifications (usually 8-pixel increments) Usage Notes: Use this size for MP4 previews and shares on desktop
loopedmp4	Resolution and size: highest quality video format, larger in size than mp4 Dimensions: Same as mp4 Usage Notes: Use this size for mp4 shares if you want the video clip to run a few times rather than only once	default
Format Info Resolution and size: highest quality video format, larger in size than mp4 Dimensions: Same as mp4 Usage Notes: Use this size for mp4 shares if you want the video clip to run a few times rather than only once
tinymp4	Resolution and size: reduced size of the mp4 format Dimensions: Variable width and height, with maximum bounding box of 320x320 Usage Notes: Use this size for mp4 previews and shares on mobile	default, basic
Format Info Resolution and size: reduced size of the mp4 format Dimensions: Variable width and height, with maximum bounding box of 320x320 Usage Notes: Use this size for mp4 previews and shares on mobile
nanomp4	Resolution and size: smallest size of the mp4 format Dimensions: Variable width and height, with maximum bounding box of 150x150 Usage Notes: Use this size for mp4 previews on mobile	default, basic
Format Info Resolution and size: smallest size of the mp4 format Dimensions: Variable width and height, with maximum bounding box of 150x150 Usage Notes: Use this size for mp4 previews on mobile
webm	Resolution and size: Lower quality video format, smaller in size than MP4 Dimensions: Same as mp4 Usage Notes: Use this size for webm previews and shares on desktop	default
Format Info Resolution and size: Lower quality video format, smaller in size than MP4 Dimensions: Same as mp4 Usage Notes: Use this size for webm previews and shares on desktop
tinywebm	Resolution and size: reduced size of the webm format Dimensions: Same as tinymp4 Usage Notes: Use this size for GIF shares on mobile	default
Format Info Resolution and size: reduced size of the webm format Dimensions: Same as tinymp4 Usage Notes: Use this size for GIF shares on mobile
nanowebm	Resolution and size: smallest size of the webm format Dimensions: Same as nanomp4 Usage Notes: Use this size for GIF previews on mobile	default
Format Info Resolution and size: smallest size of the webm format Dimensions: Same as nanomp4 Usage Notes: Use this size for GIF previews on mobile

Best Practices:

For mobile, use the nano(or tiny) sized files for previews and the tiny sized files for shares
If you’re using the GIF or MP4 formats only, add the following parameter to each search call: &media_filter=basic -- doing so will reduce the API response size by roughly 30%.
If you’re using the tinygif format only, change the parameter to: &media_filter=minimal -- doing so will reduce the API response size by roughly 50-70%.

GIF Format Sizes

The file size for each GIF format is dependent on the dimensions and length of the specific GIF selected. Therefore, the mean and medians provided below should be considered as a general guide rather than hard values.

GIF FORMAT	MEAN(KB)	MEDIAN(KB)
gif	1,472	956
mediumgif	883	574
tinygif	215	101
nanogif	77	56
mp4	125	91
loopedmp4	314	228
tinymp4	98	81
nanomp4	36	28
webm	76	61
tinywebm	57	45
nanowebm	35	25

RESPONSE CODES

HTTP STATUS CODE	DESCRIPTION
200 or 202	ok or accepted; no error
429	Rate limit exceeded: This is not expected on most API calls, but the client should try to support graceful failure and retry (allow for a 30 second timeout) if this condition is encountered.
3xx	We generally do not expect redirect status codes to come from our API, but the client should try to support this.
404	Not found - bad resource
5xx	Unexpected server error

ERRORS

In general, known errors return an http 200 status code with attributes “error” and “code”, whereas unknown errors return non-200 status codes.

KEY	VALUE TYPE	DESCRIPTION
code	int	an optional numeric code
error	string	a string message describing the error

Language Support & Localized Content

We support the following languages and have locale specific content for many regions where these languages are spoken:

Content Filtering

We offer flexible content filters that enable you to offer the type of content that is the best fit for your users. Our filters are designed to map to the MPAA though important to note we do not surface the type of nudity that may be found in R rated films. If you become aware of such content, please inform us immediately by contacting support@tenor.com.

Note: this feature was previously called SafeSearch.

ContentFilter options:

high - G
medium - G and PG
low - G, PG, and PG-13
off - G, PG, PG-13, and R (no nudity)

VIOLENCE

DESCRIPTION	G	PG	PG-13	R
Mild cartoon violence
Humorous violence & Comic Mischief
Realistic Violence
Graphic Violence

DESCRIPTION
Mild cartoon violence
G	PG	PG-13	R

DESCRIPTION
Humorous violence & Comic Mischief
G	PG	PG-13	R

DESCRIPTION
Realistic Violence
G	PG	PG-13	R

DESCRIPTION
Graphic Violence
G	PG	PG-13	R

PROFANITY

DESCRIPTION	G	PG	PG-13	R
Mild Profanity
Censored Profanity
Strong Profanity

DESCRIPTION
Mild Profanity
G	PG	PG-13	R

DESCRIPTION
Censored Profanity
G	PG	PG-13	R

DESCRIPTION
Strong Profanity
G	PG	PG-13	R

SEXUAL CONTENT

DESCRIPTION	G	PG	PG-13	R
Partial/non-detailed nudity (includes cartoon)
Animated depiction of genitals
Non-sexual kisses
Mention of sex, genitals, etc
Suggestive sexual content
Strong sexual content

DESCRIPTION
Partial/non-detailed nudity (includes cartoon)
G	PG	PG-13	R

DESCRIPTION
Animated depiction of genitals
G	PG	PG-13	R

DESCRIPTION
Non-sexual kisses
G	PG	PG-13	R

DESCRIPTION
Mention of sex, genitals, etc
G	PG	PG-13	R

DESCRIPTION
Suggestive sexual content
G	PG	PG-13	R

DESCRIPTION
Strong sexual content
G	PG	PG-13	R

SUBSTANCE USE

DESCRIPTION	G	PG	PG-13	R
Implied Alcohol or Tobacco Use
Depicts Alcohol or Tobacco Use
Implied Drug Use
Depicts Drug Use

DESCRIPTION
Implied Alcohol or Tobacco Use
G	PG	PG-13	R

DESCRIPTION
Depicts Alcohol or Tobacco Use
G	PG	PG-13	R

DESCRIPTION
Implied Drug Use
G	PG	PG-13	R

DESCRIPTION
Depicts Drug Use
G	PG	PG-13	R

MISC

DESCRIPTION	G	PG	PG-13	R
Depicts Gambling
Inflammatory Content
Mild Horror
Intense Horror
Depicts firearms or weapons
Firearms or weapons in use
Firearms or weapons in use with a serious intent to harm

DESCRIPTION
Depicts Gambling
G	PG	PG-13	R

DESCRIPTION
Inflammatory Content
G	PG	PG-13	R

DESCRIPTION
Mild Horror
G	PG	PG-13	R

DESCRIPTION
Intense Horror
G	PG	PG-13	R

DESCRIPTION
Depicts firearms or weapons
G	PG	PG-13	R

DESCRIPTION
Firearms or weapons in use
G	PG	PG-13	R

DESCRIPTION
Firearms or weapons in use with a serious intent to harm
G	PG	PG-13	R

SDKs

Check out our github page: https://github.com/Tenor-Inc

API Terms

Tenor API Terms of Service

Last revised: March 3, 2021

Thank you for your interest in Google’s Tenor API Services. The "Tenor API Services" means (1) the Tenor API services made available by Google, including those Tenor API services made available on the Tenor Developer Site, (2) documentation, information, materials, sample code and software relating to the Tenor API services that are made available on the Tenor Developer Site or by Google, (3) data, content (including audiovisual content) and information provided to API Clients through the Tenor API services ("Content"), and (4) the credentials assigned to you and your API Clients by Google.

The Terms.

Components. To use the Tenor API Services, you must accept the Google API Terms of Service at https://developers.google.com/terms/ (or such other URL as Google may provide, the "Google API Terms of Service") and these Tenor API Additional Terms (the "Tenor Additional Terms").

Terms. Collectively, we refer to the Google API Terms of Service, these Tenor Additional Terms, any accompanying documentation, and any applicable policies and guidelines as the "Terms".

Precedence. You agree to comply with the Terms and that the Terms control your relationship with us. To the extent that there are any conflicts, the following order of precedence will apply: (i) other agreements with the parties covering the same subject (for example, if you have a separate Tenor API Content Access Agreement), (ii) Tenor Developer Policies, (iii) the Tenor Additional Terms, and (iv) Google’s API Terms of Service.

Google. We may refer to "Google" as "we", "our", or "us" in the Terms. Google may use its Affiliates in connection with performing its obligations and exercising its rights under the Terms.

Definitions. Capitalized terms used but not defined in these Tenor Additional Terms have the meaning given to them in the Google API Terms of Service.

Affiliates means the entity that directly or indirectly controls, is controlled by, or is under common control with, Google, including Tenor, Inc.

Tenor Developer Policies means the policies relating to the Tenor API Services currently located at https://support.google.com/tenor.

Tenor Developer Site means the Tenor developer website including the webpages currently located at https://tenor.com/gifapi.

Use of the Tenor API Services.

Permitted Commercial Uses. As long as you follow these Terms, you may use the Tenor API for the following commercial uses or as otherwise described in the Tenor Developer Policies:

charging fees to access your API Client or the online service that uses your API Client;

ii.

using the Tenor API to show Content on an ad-enabled API Client (such as an ad-enabled app, blog, or website), subject to Section 3(c) (Prohibited Commercial Uses) below;

iii.

placing your own branding on the API Client, as long as it does not interfere with the display of any Content or with any Tenor Branding.

Prohibited Commercial Uses. Unless you obtain Google’s prior written approval, you will not (or allow those acting on your behalf to) use the Tenor API Services to sell advertising, sponsorships, or promotions on or through the Content (including pop-up ads or ads linked to from the Content).

General Prohibitions. Your API Client will not, you will not, and you will not encourage or allow your users or other third parties to do the following in connection with the Tenor API Services:

modify or replace the text, images, or other content of the Tenor search results;

ii.

change the order in which Tenor search results are presented;

iii.

intermix sources other than Tenor when attributing search results as Tenor search results;

iv.

modify, replace, or disable links to Tenor or third-party websites provided in the Tenor search results or otherwise provided through the Tenor Services;

modify, replace, interfere with, or block advertisements placed by Tenor in the Tenor search results or Content;

vi.

promote or condone violence, or incite hate against an individual or group based on any characteristic that is associated with systemic discrimination or marginalization (including race, ethnicity, nationality, religion, disability, age, veteran status, sexual orientation, gender, or gender identity);

vii.

promote, encourage, or support (A) graphic or gratuitous violence; (B) dangerous activities; (C) terrorism; (D) suicide or self-harm; (E) prostitution, escort services, and similar offerings; (F) bullying, blackmail, or revenge; (G) violating any person’s privacy or publicity rights; or

viii.

display sexually-explicit imagery (including pornographic content or behavior).

Attribution

All content retrieved from Tenor must be properly attributed by including one of the three following options:

Powered By Tenor - to be used in the GIF browsing experience
Search Tenor - to be used as the placeholder text in the search bar
Via Tenor - to be used in the footer of a shared GIF

Attribution logos can be found here:

https://media.tenor.com/website/gifapi-assets/index.html

Support

Please email api@tenor.com and we will quickly get back to you as soon as possible.

Quickstart Guide

API Highlights

BEFORE YOU BEGIN

Get a Tenor API Key

Step 1 - Implement Search

EXAMPLE REQUESTS

Step 2 - Implement Share Events

EXAMPLE REQUESTS

ATTRIBUTION

Review Attribution Examples

Congratulations! You’ve successfully integrated with Tenor’s API!

Step 3 - Enrich the Search Experience

A - Launching your Search experience

EXAMPLE REQUESTS

B - Autocomplete Suggestions

EXAMPLE REQUESTS

C - Search Suggestions

EXAMPLE REQUESTS

Endpoints

Search

Base Url:

Best Practices:

PARAMETERS

RESPONSE FORMAT

EXAMPLE REQUESTS

Trending GIFs

Base URL:

Best Practices:

PARAMETERS

RESPONSE FORMAT

EXAMPLE REQUESTS

Categories

Base URL:

Supported types:

Best Practices:

PARAMETERS

RESPONSE FORMAT

EXAMPLE REQUESTS

Search Suggestions

Base URL:

Best Practices:

PARAMETERS

RESPONSE FORMAT

EXAMPLE REQUESTS

Autocomplete

Base URL:

Best Practices:

PARAMETERS

RESPONSE FORMAT

EXAMPLE REQUESTS

Trending Search Terms

Base URL:

Best Practices:

PARAMETERS

RESPONSE FORMAT

EXAMPLE REQUESTS

Register Share

Base URL:

Best Practices:

PARAMETERS

RESPONSE FORMAT

EXAMPLE REQUESTS

GIFs

Base URL:

Best Practices:

PARAMETERS

RESPONSE FORMAT

EXAMPLE REQUESTS

Random GIFs

Base URL:

Best Practices:

PARAMETERS

RESPONSE FORMAT

EXAMPLE REQUESTS

Anonymous ID

Base URL:

PARAMETERS

RESPONSE FORMAT

EXAMPLE REQUESTS

g.tenor.com Domain