Response objects and errors

This page provides information about the different JSON response and error objects used by the Tenor API.

Response object

The following table provides details on the properties for Response Objects:

Properties
created

float

A Unix timestamp that represents when this post was created.
hasaudio

boolean

Returns true if this post contains audio.
id

string

Tenor result identifier
media_formats

{ CONTENT_FORMAT : MEDIA_OBJECT }

A dictionary with a content format as the key and a Media Object as the value.
tags

string[]

An array of tags for the post
title

string

The title of the post
content_description

string

A textual description of the content.

We recommend that you use content_description for user accessibility features.
itemurl

string

The full URL to view the post on tenor.com.
hascaption

boolean

Returns true if this post contains captions.
flags

string

Comma-separated list to signify whether the content is a sticker or static image, has audio, or is any combination of these. If sticker and static aren't present, then the content is a GIF. A blank flags field signifies a GIF without audio.
bg_color

string

The most common background pixel color of the content
url

string

A short URL to view the post on tenor.com.

Category object

The following table provides details on the properties for Category Objects:

Properties
searchterm

string

The search term that corresponds to the category. The search term is translated to match the locale of the corresponding request.
path

string

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
name

string

Category name to overlay over the image. The name is translated to match the locale of the corresponding request.

Media object

The following table provides details on the properties for Media Objects:

Properties
url

string

A URL to the media source
dims

int[]

Width and height of the media in pixels
duration

float

Represents the time in seconds for one loop of the content. If the content is static, the duration is set to 0.
size

int

Size of the file in bytes

Content formats

Tenor's API offers the following five base formats in a variety of sizes:

  • GIF
  • MP4
  • WebM
  • Transparent WebP
  • Transparent GIF

The MP4 and WebM formats play their clip only once, with the exception of the loopedmp4, which plays the clip a few times. The GIF format plays its clip on a continuous loop. The transparent formats are for sticker content and aren't available in GIF search results.

Format types

The following table provides details on the available media format types for Tenor:

Format types
preview
  • Resolution and size: High quality single frame GIF format; smaller in size than the GIF format
  • Dimensions: Original upload dimensions (no limits)
  • Usage notes: Make this the first frame of the content. It's intended for use as a thumbnail preview.

This format is supported for GIFs and stickers.
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.

This format is supported for GIFs and stickers.
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.

This format is supported for GIFs and stickers.
tinygif
  • Resolution and size: Reduced size of the GIF format
  • Dimensions: Up to 220 pixels wide. Height scaled to preserve the aspect ratio.
  • Usage notes: Use this size for GIF previews and shares on mobile.

This format is supported for GIFs and stickers.
nanogif
  • Resolution and size: Smallest size of the GIF format
  • Dimensions: Up to 90 pixels tall. Width scaled to preserve the aspect ratio.
  • Usage notes: Use this size for GIF previews on mobile.

This format is supported for GIFs and stickers.
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, which are usually 8-pixel increments.
  • Usage notes: Use this size for MP4 previews and shares on desktop.

This format is supported for GIFs and stickers.
loopedmp4
  • Resolution and size: Highest quality video format; larger in size than MP4
  • Dimensions: Similar to GIF but padded to fit video container specifications, which are usually 8-pixel increments.
  • Usage notes: Use this size for MP4 shares when you want the video clip to run a few times rather than only once.

This format is supported for GIFs and stickers.
tinymp4
  • Resolution and size: Reduced size of the MP4 format
  • Dimensions: Variable width and height, with a maximum bounding box of 320x320 pixels
  • Usage notes: Use this size for MP4 previews and shares on mobile.

This format is supported for GIFs and stickers.
nanomp4
  • Resolution and size: Smallest size of the MP4 format
  • Dimensions: Variable width and height, with a maximum bounding box of 150x150 pixels
  • Usage notes: Use this size for MP4 previews on mobile.

This format is supported for GIFs and stickers.
webm
  • Resolution and size: Lower quality video format; smaller in size than MP4
  • Dimensions: Similar to GIF but padded to fit video container specifications, which are usually 8-pixel increments.
  • Usage notes: Use this size for WebM previews and shares on desktop.

This format is supported for GIFs and stickers.
tinywebm
  • Resolution and size: Reduced size of the WebM format
  • Dimensions: Variable width and height, with a maximum bounding box of 320x320 pixels
  • Usage notes: Use this size for GIF shares on mobile.

This format is supported for GIFs and stickers.
nanowebm
  • Resolution and size: Smallest size of the WebM format
  • Dimensions: Variable width and height, with a maximum bounding box of 150x150 pixels
  • Usage notes: Use this size for GIF previews on mobile.

This format is supported for GIFs and stickers.
webp_transparent
  • Resolution and size: High-quality WebP sticker format; largest file size available
  • Dimensions: Original upload dimensions (no limits)
  • Usage notes: Use this size for sticker shares for high-bandwidth users.

This format is supported for stickers.
tinywebp_transparent
  • Resolution and size: Reduced size of the WebP sticker format; maximum size of 500 KB
  • Dimensions: Up to 220x220 pixels, height scaled to preserve the aspect ratio.
  • Usage notes: Use this size for sticker previews for high-bandwidth users and shares for low-bandwidth users.

This format is supported for stickers.
nanowebp_transparent
  • Resolution and size: Smallest size of the WebP sticker format; maximum size of 100 KB
  • Dimensions: Up to 90x90 pixels, with the width scaled to preserve the aspect ratio.
  • Usage notes: Use this size for sticker previews for low-bandwidth users.

This format is supported for stickers.
gif_transparent
  • Resolution and size: High-quality GIF sticker format; largest file size available
  • Dimensions: Original upload dimensions (no limits)
  • Usage notes: Use this size for sticker shares for high-bandwidth users.

This format is supported for stickers.
tinygif_transparent
  • Resolution and size: Reduced size of the GIF sticker format; maximum size of 500 KB
  • Dimensions: Up to 220x220 pixels, with the height scaled to preserve the aspect ratio.
  • Usage notes: Use this size for sticker previews for high-bandwidth users and shares for low-bandwidth users.

This format is supported for stickers.
nanogif_transparent
  • Resolution and size: Smallest size of the GIF sticker format; maximum size of 100 KB
  • Dimensions: Up to 90x90 pixels, with the width scaled to preserve the aspect ratio.
  • Usage notes: Use this size for sticker previews for low-bandwidth users.

This format is supported for sticker.

Best practices

  • For mobile, use the nano- or tiny-sized files for previews and the tiny-sized files for shares.
  • Set the media_filter parameter to the formats you intend to use. This can reduce the API response size by 70%.

Format sizes

The file size for each content format depends on the dimensions and length of the specific GIF selected. Therefore, consider the means and medians provided in the following table as general guidelines rather than hard values.

File format Mean file size (KB) Median file size (KB)
gif 3,356 956
mediumgif 2,548 574
tinygif 521 101
nanogif 175 56
mp4 207 91
loopedmp4 515 228
tinymp4 84 81
nanomp4 37 28
webm 76 61
tinywebm 57 45
nanowebm 35 25
webp_transparent 530 95
tinywebp_transparent 249 60
nanowebp_transparent 107 25
gif_transparent 643 35
tinygif_transparent 349 20
nanogif_transparent 116 10

Response codes

The following table provides the HTTP status response codes used to indicate a successful request:

HTTP status code
200 or 202 OK or accepted

Errors

Tenor's API returns errors with the HTTP response codes 4xx or 5xx and in the standard Google API error format. For details, see Errors.