Quickstart Guide

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

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 30+ 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 and request new keys in your developer dashboard.

EXAMPLE REQUESTS

Curl
Python
Android/Java
Swift 2.0+ / iOS
Javascript
Objective-C
 

Step 2 - Implement Share Tracking

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 for your app, helping your 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
 
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 searches endpoint). Alternatively, trending GIFs (from the trending endpoints) can be displayed beneath search.

(Optional) Pass locale and an anonymous user id to Tenor to tune Tenor’s search engine to your user’s location and preferences.

In the example below we’ll fetch Tenor categories and trending GIFs to display to the user, and pass an anonymous id to Tenor.

EXAMPLE REQUESTS

Curl
Python
Android/Java
Swift 2.0+ / iOS
Javascript
Objective-C
 

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
 

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 “excited”:

EXAMPLE REQUESTS

Curl
Python
Android/Java
Swift 2.0+ / iOS
Javascript
Objective-C
 

Endpoints

Trending GIFs

Base URL:

https://api.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:

  1. Provide the user’s anonymous id. Doing so will help tune Tenor’s algorithms towards your user’s preferences over time.
  2. Use the Locale parameter to better tune search results to your users specific languages, cultures, and social trends. Using Locale will not limit trending results to only the provided code, but gives higher preference to the given locale. The more an accurate Locale is used for users, the better trending results will become at localization and accuracy. The default value is en_US.
  3. When the user decides which GIF to share, be sure to include a corresponding call to Register Share. Doing so will help tune Tenor’s algorithms towards your users preferences
  4. 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.
  5. Use the media_filter parameter to reduce the number of GIF formats returned. This can reduce the response object size by 25-75%.
  6. Use the ar_range parameter to filter the GIF response list to only include aspect ratios that fall within the selected range.

PARAMETERS

NAMETYPEDEFAULT VALUEDESCRIPTION
key
REQUIRED
stringn/aclient key for privileged API access
DESCRIPTION
client key for privileged API access
locale
STRONGLY RECOMMENDED
string (xx_YY)en_USspecify 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
anon_id
STRONGLY RECOMMENDED
stringn/aspecify the anonymous_id tied to the given user
DESCRIPTION
specify the anonymous_id tied to the given user
media_filter
STRONGLY RECOMMENDED
stringn/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
stringall

(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
integer20fetch up to a specified number of results (max: 50).
DESCRIPTION
fetch up to a specified number of results (max: 50).
pos
OPTIONAL
stringn/aget 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

RESPONSE FORMAT

KEYVALUE TYPEDESCRIPTION
next
stringa position identifier to use with the next API query to retrieve the next set of results, or null 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 null 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
 

Categories

Base URL:

https://api.tenor.com/v1/categories?<parameters>

Get a json object containing a list of GIF categories associated with the provided type. Each category will include a corresponding search URL to be used if the user clicks on the category. The search URL will include the apikey, anonymous id, and locale that were used on the original call to the categories endpoint.

Supported types:

  1. featured (default) - The current featured emotional / reaction based GIF categories including a preview GIF for each term.
  2. emoji - The current featured emoji GIF categories
  3. trending - The current trending search terms including a preview GIF for each term.

Best Practices:

  1. Provide the user’s anonymous id. Doing so will help tune Tenor’s algorithms towards your user’s preferences over time.
  2. Use the Locale parameter to convert category names to the user’s language. The default value is EN_US.

PARAMETERS

NAMETYPEDEFAULT VALUEDESCRIPTION
key
REQUIRED
stringn/aclient key for privileged API access
DESCRIPTION
client key for privileged API access
locale
STRONGLY RECOMMENDED
string (xx_YY)en_USspecify 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
anon_id
STRONGLY RECOMMENDED
stringn/aspecify the anonymous_id tied to the given user
DESCRIPTION
specify the anonymous_id tied to the given user
Type
STRONGLY RECOMMENDED
stringfeatured(values: featured | emoji | trending ) determines the type of categories returned
DESCRIPTION
(values: featured | emoji | trending ) determines the type of categories returned

RESPONSE FORMAT

KEYVALUE TYPEDESCRIPTION
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.

EXAMPLE REQUESTS

Curl
Python
Android/Java
Swift 2.0+ / iOS
Javascript
Objective-C
 

Search Suggestions

Base URL:

https://api.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:

  1. Provide the user’s anonymous id. Doing so will help tune Tenor’s algorithms towards your user’s preferences over time.
  2. Use the Locale parameter to better tune search results to your users specific languages, cultures, and social trends. Using Locale will not limit trending results to only the provided code, but rather is used as an input to Tenor’s algorithm. The more an accurate Locale is used for users, the better search suggestion results will become at localization and accuracy. The default value is en_US.
  3. Display the results in the order provided by the response object.

PARAMETERS

NAMETYPEDEFAULT VALUEDESCRIPTION
q
REQUIRED
stringn/aa search string
DESCRIPTION
a search string
locale
STRONGLY RECOMMENDED
string (xx_YY)en_USspecify 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
anon_id
STRONGLY RECOMMENDED
stringn/aspecify the anonymous_id tied to the given user
DESCRIPTION
specify the anonymous_id tied to the given user
limit
OPTIONAL
integer20fetch up to a specified number of results (max: 50).
DESCRIPTION
fetch up to a specified number of results (max: 50).

RESPONSE FORMAT

KEYVALUE TYPEDESCRIPTION
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

Base URL:

https://api.tenor.com/v1/autocomplete?tag=<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:

  1. Provide the user’s anonymous id. Doing so will help tune Tenor’s algorithms towards your user’s preferences over time.
  2. Use the Locale parameter to better tune search results to your users specific languages, cultures, and social trends. Using Locale will not limit trending results to only the provided code but gives higher preference to the given locale. The more an accurate Locale is used for users, the better autocomplete results will become at localization and accuracy. The default value is en_US.
  3. Display the results in the order provided by the response object.

PARAMETERS

NAMETYPEDEFAULT VALUEDESCRIPTION
key
REQUIRED
stringn/aclient key for privileged API access
DESCRIPTION
client key for privileged API access
q
REQUIRED
stringn/aa search string
DESCRIPTION
a search string
locale
STRONGLY RECOMMENDED
string (xx_YY)en_USspecify 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
anon_id
STRONGLY RECOMMENDED
stringn/aspecify the anonymous_id tied to the given user
DESCRIPTION
specify the anonymous_id tied to the given user
limit
OPTIONAL
integer20fetch up to a specified number of results (max: 50).
DESCRIPTION
fetch up to a specified number of results (max: 50).

RESPONSE FORMAT

KEYVALUE TYPEDESCRIPTION
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
 

Trending Search Terms

Base URL:

https://api.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:

  1. Provide the user’s anonymous id. Doing so will help tune Tenor’s algorithms towards your user’s preferences over time.
  2. Use the Locale parameter to better tune search results to your users specific languages, cultures, and social trends. Using Locale will not limit trending results to only the provided code, but rather is used as an input to Tenor’s algorithm. The more an accurate Locale is used for users, the better trending results will become at localization and accuracy. The default value is en_US.
  3. Display the results in the order provided by the response object.

PARAMETERS

NAMETYPEDEFAULT VALUEDESCRIPTION
key
REQUIRED
stringn/aclient key for privileged API access
DESCRIPTION
client key for privileged API access
locale
STRONGLY RECOMMENDED
string (xx_YY)en_USspecify 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
anon_id
STRONGLY RECOMMENDED
stringn/aspecify the anonymous_id tied to the given user
DESCRIPTION
specify the anonymous_id tied to the given user
limit
OPTIONAL
integer20fetch up to a specified number of results (max: 50).
DESCRIPTION
fetch up to a specified number of results (max: 50).

RESPONSE FORMAT

KEYVALUE TYPEDESCRIPTION
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
 

Register Share

Base URL:

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

Register a user’s sharing of a GIF.

Best Practices:

  1. Provide the user’s anonymous id, locale, and search term to better tune Tenor’s AI to your users

PARAMETERS

NAMETYPEDEFAULT VALUEDESCRIPTION
key
REQUIRED
stringn/aclient key for privileged API access
DESCRIPTION
client key for privileged API access
Id
REQUIRED
stringn/athe “id” of a GIF_OBJECT
DESCRIPTION
the “id” of a GIF_OBJECT
locale
STRONGLY RECOMMENDED
string (xx_YY)en_USspecify 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
anon_id
STRONGLY RECOMMENDED
stringn/aspecify the anonymous_id tied to the given user
DESCRIPTION
specify the anonymous_id tied to the given user
q
STRONGLY RECOMMENDED
stringn/aThe search string that lead to this share
DESCRIPTION
The search string that lead to this share

RESPONSE FORMAT

KEYVALUE TYPEDESCRIPTION
status
Stringset 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
 

GIFs

Base URL:

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

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

Best Practices:

  1. Provide the user’s anonymous id for tuning of Tenor’s AI
  2. Use the media_filter parameter to reduce the number of GIF formats returned. This can reduce the response object size by 25-75%.

PARAMETERS

NAMETYPEDEFAULT VALUEDESCRIPTION
ids
REQUIRED
stringn/aa comma separated list of GIF IDs (max: 50)
DESCRIPTION
a comma separated list of GIF IDs (max: 50)
key
REQUIRED
stringn/aclient key for privileged API access
DESCRIPTION
client key for privileged API access
anon_id
STRONGLY RECOMMENDED
stringn/aspecify the anonymous_id tied to the given user
DESCRIPTION
specify the anonymous_id tied to the given user
media_filter
STRONGLY RECOMMENDED
stringn/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
integer20fetch up to a specified number of results (max: 50).
DESCRIPTION
fetch up to a specified number of results (max: 50).
pos
OPTIONAL
stringn/aget 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

RESPONSE FORMAT

KEYVALUE TYPEDESCRIPTION
next
stringa position identifier to use with the next API query to retrieve the next set of results, or null 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 null 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
 

Anonymous ID

Base URL:

https://api.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.

Best Practices:

  1. We recommend getting an anonymous ID for each user. This, along with use of the locale parameter, will allow Tenor’s AI to adjust to your users without the use of personally identifiable information

PARAMETERS

NAMETYPEDEFAULT VALUEDESCRIPTION
key
REQUIRED
stringn/aclient key for privileged API access
DESCRIPTION
client key for privileged API access

RESPONSE FORMAT

KEYVALUE TYPEDESCRIPTION
anon_id
stringan 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
 

Random GIFs

Base URL:

https://api.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:

  1. Provide the user’s anonymous id. Doing so will help tune Tenor’s algorithms towards your user’s preferences over time.
  2. Use the Locale parameter to better tune search results to your users’ specific languages, cultures, and social trends. Using Locale will not limit search results to only the provided code and language typed, but gives higher preference to the given locale. The more an accurate Locale is used for users, the better search results will become at localization and accuracy. The default value is en_US.
  3. Use the Safesearch parameter to maintain your internal content safety ratings for GIFs returned. The default value is off
  4. Use the media_filter parameter to reduce the number of GIF formats returned. This can reduce the response object size by 25-75%.
  5. Use the ar_range parameter to filter the GIF response list to only include aspect ratios that fall within the selected range.

PARAMETERS

NAMETYPEDEFAULT VALUEDESCRIPTION
key
REQUIRED
stringn/aclient key for privileged API access
DESCRIPTION
client key for privileged API access
q
REQUIRED
stringn/aa search string
DESCRIPTION
a search string
locale
STRONGLY RECOMMENDED
string (xx_YY)en_USspecify 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
safesearch
STRONGLY RECOMMENDED
enumoff(values:off|moderate|mild|strict) specify the content safety filter level
DESCRIPTION
(values:off|moderate|mild|strict) specify the content safety filter level
anon_id
STRONGLY RECOMMENDED
stringn/aspecify the anonymous_id tied to the given user
DESCRIPTION
specify the anonymous_id tied to the given user
media_filter
STRONGLY RECOMMENDED
stringn/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
stringall

(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
integer20fetch up to a specified number of results (max: 50).
DESCRIPTION
fetch up to a specified number of results (max: 50).
pos
OPTIONAL
stringn/aget 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

RESPONSE FORMAT

KEYVALUE TYPEDESCRIPTION
next
stringa position identifier to use with the next API query to retrieve the next set of results, or null 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 null 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
 

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 API?

Custom work that increases searches and shares. This tends to be unique to a particular partner’s use case and userbase. For example, custom file formats and endpoints that personalize results for a particular region, holidays, events, or corporate initiatives.

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. Features like:

  • 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 safesearch
  • 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

KEYVALUE TYPEDESCRIPTION
created
floata unix timestamp representing when this post was created.
DESCRIPTION
a unix timestamp representing when this post was created.
hasaudio
booleantrue 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
stringTenor 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
stringthe title of the post.
DESCRIPTION
the title of the post.
itemurl
stringthe full URL to view the post on tenor.com.
DESCRIPTION
the full URL to view the post on tenor.com.
hascaption
booleantrue if this post contains captions
DESCRIPTION
true if this post contains captions
url
stringa short URL to view the post on tenor.com.
DESCRIPTION
a short URL to view the post on tenor.com.

CATEGORY_OBJECT

KEYVALUE TYPEDESCRIPTION
searchterm
stringThe english search term that corresponds to the category
DESCRIPTION
The english search term that corresponds to the category
path
stringthe search url to request if the user selects the category
DESCRIPTION
the search url to request if the user selects the category
image
stringa 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
stringCategory 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

KEYVALUE TYPEDESCRIPTION
preview
stringa url to a preview image of the media source
DESCRIPTION
a url to a preview image of the media source
url
stringa 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
intsize of file in bytes
DESCRIPTION
size of file in bytes

GIF_FORMAT

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

  1. For mobile, use the nano(or tiny) sized files for previews and the tiny sized files for shares
  2. 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%.
  3. 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)
gif1,472956
mediumgif883574
tinygif215101
nanogif7756
mp412591
loopedmp4314228
tinymp49881
nanomp43628
webm7661
tinywebm5745
nanowebm3525

RESPONSE CODES

HTTP STATUS CODE DESCRIPTION
200 or 202ok or accepted; no error
429Rate 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.
3xxWe generally do not expect redirect status codes to come from our API, but the client should try to support this.
404Not found - bad resource
5xxUnexpected 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
codeintan optional numeric code
errorstringa 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:

  • Portuguese
  • English
  • Spanish
  • Italian
  • German
  • Arabic
  • Russian
  • French
  • Albanian
  • Slovak
  • Indonesian
  • Simplified Chinese
  • Traditional Chinese
  • Japanese
  • Korean
  • Hindi
  • Turkish
  • Dutch
  • Bengali
  • Tagalog
  • Hebrew
  • Finnish
  • Swedish
  • Danish
  • Czech
  • Polish
  • Romanian
  • Malay
  • Cantonese
  • Urdu
  • Norwegian (Bokmal)
  • Norwegian (Nynorsk)
  • Catalan
  • Greek
  • Hungarian
  • Thai
  • Farsi
  • Ukrainian
  • Croatian
  • Vietnamese

SafeSearch

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.

SafeSearch options:

  1. strict - G
  2. mild - G and PG
  3. moderate - G, PG, and PG-13
  4. off - G, PG, PG-13, and R (no nudity)

VIOLENCE

DESCRIPTIONGPGPG-13R
Mild cartoon violence
Humorous violence & Comic Mischief
Realistic Violence
Graphic Violence
DESCRIPTION
Mild cartoon violence
GPGPG-13R
DESCRIPTION
Humorous violence & Comic Mischief
GPGPG-13R
DESCRIPTION
Realistic Violence
GPGPG-13R
DESCRIPTION
Graphic Violence
GPGPG-13R

PROFANITY

DESCRIPTIONGPGPG-13R
Mild Profanity
Censored Profanity
Strong Profanity
DESCRIPTION
Mild Profanity
GPGPG-13R
DESCRIPTION
Censored Profanity
GPGPG-13R
DESCRIPTION
Strong Profanity
GPGPG-13R

SEXUAL CONTENT

DESCRIPTIONGPGPG-13R
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)
GPGPG-13R
DESCRIPTION
Animated depiction of genitals
GPGPG-13R
DESCRIPTION
Non-sexual kisses
GPGPG-13R
DESCRIPTION
Mention of sex, genitals, etc
GPGPG-13R
DESCRIPTION
Suggestive sexual content
GPGPG-13R
DESCRIPTION
Strong sexual content
GPGPG-13R

SUBSTANCE USE

DESCRIPTIONGPGPG-13R
Implied Alcohol or Tobacco Use
Depicts Alcohol or Tobacco Use
Implied Drug Use
Depicts Drug Use
DESCRIPTION
Implied Alcohol or Tobacco Use
GPGPG-13R
DESCRIPTION
Depicts Alcohol or Tobacco Use
GPGPG-13R
DESCRIPTION
Implied Drug Use
GPGPG-13R
DESCRIPTION
Depicts Drug Use
GPGPG-13R

MISC

DESCRIPTIONGPGPG-13R
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
GPGPG-13R
DESCRIPTION
Inflammatory Content
GPGPG-13R
DESCRIPTION
Mild Horror
GPGPG-13R
DESCRIPTION
Intense Horror
GPGPG-13R
DESCRIPTION
Depicts firearms or weapons
GPGPG-13R
DESCRIPTION
Firearms or weapons in use
GPGPG-13R
DESCRIPTION
Firearms or weapons in use with a serious intent to harm
GPGPG-13R

SDKs

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

API Terms

Tenor API Terms of Service

Last revised: March 13, 2017

Tenor, Inc. (“Tenor”, “we”, “our”, or “us”) maintains a library of content (“Content”), application programming interfaces (“Tenor API”), platform and applications (collectively, the “Services”), which enable the selection, retrieval and use of GIFs and other short animations and videos in communication on websites and through email and messaging applications.

THIS IS A LEGAL AGREEMENT BETWEEN YOU AND TENOR STATING THE TERMS THAT GOVERN YOUR USE OF AND ACCESS TO THE SERVICES THROUGH THE TENOR API. PLEASE READ THESE API TERMS OF SERVICE (THE “TERMS”) CAREFULLY BEFORE USING THE TENOR DEVELOPER MATERIALS (DEFINED BELOW). BY USING THE TENOR DEVELOPER MATERIALS, YOU ARE AGREEING TO BE BOUND BY THESE TERMS.

IF YOU DO NOT AGREE TO THESE TERMS, DO NOT DOWNLOAD OR USE ANY TENOR DEVELOPER MATERIALS AS YOU ARE NOT PERMITTED TO USE THE TENOR DEVELOPER MATERIALS.

You certify that you are of the legal age of majority in the jurisdiction in which you reside (at least 18 years of age in many countries) and you represent that you are legally permitted to enter into these Terms, have the authority and capacity to accept these Terms, and agree to be bound by these Terms.

If you are using the Tenor API or Tenor Developer Materials on behalf of a company, organization, or other entity, then (i) “you” includes you and that entity, and (ii) you represent and warrant that you are an authorized representative of the entity with the authority to bind the entity to these Terms, and that you agree to these Terms on the entity’s behalf.

These Terms include functional rules and restrictions, and other legal terms, with which developers are required to agree and which developers must implement in order to access or use the Tenor APIs and any software, code, documentation, data, and other materials made available by Tenor to you (collectively, with the Tenor API, the “Tenor Developer Materials”) to develop a client for use in connection with the Services. If you use the Tenor API as an interface to, or in conjunction with, other Tenor products and services, then the terms of those products and services also apply to you and your end users.

Attribution

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

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

Attribution logos can be found here:

https://www.dropbox.com/sh/q6hokjtmfcswrk3/AACHPiVKPUjym2zC3ldyipM9a?dl=0

Support

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