Introduction

Ready to bring the engaging power of GIFs to your app through GIPHY?

By integrating with GIPHY, the first and largest GIF search engine, you gain free access to our ever-growing content library of GIFs and Stickers — featuring the latest in entertainment, sports, and breaking news from GIPHY's official content partners.

All of our content is searchable in over thirty languages and is available in various sizes so you get the highest quality images at the lowest file sizes. Plus, there's all the classic reaction GIFs you'll ever need.


API Quickstart Guide

Welcome to GIPHY API, where you can seamlessly integrate your app with the largest GIF and Sticker library in the world.

GIPHY API is simple and fast to use, but if you're looking for something with automatic updates and access to exclusive features, our SDK might be an even better fit for you — check out GIPHY SDK!

Quickstart

Before you get started with GIPHY API, you first have to obtain an API Key by creating an app. Don't worry: it's free, and you can change your app's name and description at any time. Please note: if you're planning a large-scale deployment you must request a production API Key from your user dashboard.

Create an App

Once you’ve created an app and obtained an API key, simply follow these two easy steps to get up-and-running with GIPHY API.

1. Implement Search

GIPHY Search returns the most relevant GIFs and Stickers based on a user’s search query or category specification. Users can even find GIFs and Stickers using emoji!

To add Search to your app, head to the Search Endpoint.

To see what it should look like, you can take a look at our example code here.

2. Incorporate Analytics

GIPHY uses GIPHY Analytics to improve search results for your users. By calling our Action Register Endpoint each time a user views, clicks, or sends a GIF or Sticker, we will be able to customize our responses to your user's behavior. We highly recommend calling this endpoint on every user action in your app.

To add analytics to your app, head to our Action Register Endpoint.

Attribution

We require all apps that use GIPHY API to conspicuously display "Powered By GIPHY" attribution marks where the API is utilized (see SDK attribution guide here). You can find approved official logo marks here.

Before getting started with GIPHY API, please take a look at our API Terms of Service.. If you currently are using GIPHY API, then the API Terms of Service apply.


Endpoints

If you want to see these endpoints in action before getting started, you can use our API Explorer to input sample queries and view the live responses!


Search Endpoint

GIPHY Search gives you instant access to our library of millions of GIFs and Stickers by entering a word or phrase. With our unparalleled search algorithm, users can easily express themselves and animate their conversations.

Gif URLSticker URL
api.giphy.com/v1/gifs/searchapi.giphy.com/v1/stickers/search
Request Parameters:Example:Description:
api_key: string(required)YOUR_API_KEYGIPHY API Key.
q: string(required)cheeseburgersSearch query term or phrase.
limit: integer (int32)20The maximum number of objects to return. (Default: “25”)
offset: integer (int32)5Specifies the starting position of the results. Defaults to 0.
rating: stringgFilters results by specified rating. If you do not specify a rating, you will receive results from all possible ratings.
lang: stringenSpecify default language for regional content; use a 2-letter ISO 639-1 language code.
random_id: stringe826c9fc5c929e0d6c6d423841a282aaAn ID/proxy for a specific user.
Successful Response (200 OK)

Trending Endpoint

GIPHY Trending returns a list of the most relevant and engaging content each and every day. Our feed of trending content is continuously updated, so you always have the latest and greatest at your fingertips.

Gif URLSticker URL
api.giphy.com/v1/gifs/trendingapi.giphy.com/v1/stickers/trending
Request Parameters:Example:Description:
api_key: string(required)YOUR_API_KEYGIPHY API Key.
limit: integer (int32)20The maximum number of objects to return. (Default: “25”)
offset: integer (int32)5Specifies the starting position of the results. Defaults to 0.
rating: stringgFilters results by specified rating. If you do not specify a rating, you will receive results from all possible ratings.
random_id: stringe826c9fc5c929e0d6c6d423841a282aaAn ID/proxy for a specific user.
Successful Response (200 OK)

Translate Endpoint

GIPHY Translate converts words and phrases to the perfect GIF or Sticker using GIPHY's special sauce algorithm. This feature is best exhibited in GIPHY's Slack integration.

Gif URLSticker URL
api.giphy.com/v1/gifs/translateapi.giphy.com/v1/stickers/translate
Request Parameters:Example:Description:
api_key: string(required)YOUR_API_KEYGIPHY API Key.
s: string(required)ryan goslingSearch term.
weirdness: int10Value from 0-10 which makes results weirder as you go up the scale.
random_id: stringe826c9fc5c929e0d6c6d423841a282aaAn ID/proxy for a specific user.
Successful Response (200 OK)

Random Endpoint

GIPHY Random lets you add some weirdness to the conversation by returning a single random GIF or Sticker related to the word or phrase entered. If no tag is specified, the GIF or Sticker returned is completely random.

Gif URLSticker URL
api.giphy.com/v1/gifs/randomapi.giphy.com/v1/stickers/random
Request Parameters:Example:Description:
api_key: string(required)YOUR_API_KEYGIPHY API Key.
tag: stringburritoFilters results by specified tag..
rating: stringgFilters results by specified rating. If you do not specify a rating, you will receive results from all possible ratings.
random_id: stringe826c9fc5c929e0d6c6d423841a282aaAn ID/proxy for a specific user.
Successful Response (200 OK)

Action Register Endpoint

GIPHY’s Action Register registers each time a user views, clicks, or sends a GIF or Sticker and plays an important role in helping GIPHY improve your user’s search results.

INSTRUCTIONS

On almost all of our endpoints we return an Analytics Object for each of the GIF in the response for most endpoints.

To register an action when user views/clicks/sends a GIF, you should make a request by hitting the corresponding URL in the Analytics Object as such, and append the required params in the URL.

ImpressionClickSend
GET analytics->onload->urlGET analytics->onclick->urlGET analytics->onsent->url

BEST PRACTICE

We recommend getting a Random ID for each user by using the Random ID Endpoint. This will allow GIPHY’S API to adjust responses to your users without the use of personally identifiable information.

Request Parameters:Example:Description:
random_id: string(required)e826c9fc5c929e0d6c6d423841a282aaAn ID/proxy for a specific user.
ts: integer (int)(required)1527703430507A UNIX timestamp in milliseconds corresponding to when the action occurred.
Successful Response (200 OK)

Random ID Endpoint

GIPHY Random ID Endpoint allows GIPHY to generate a unique ID you can assign to each new user in your app.

To get the most out of Random ID, we recommend sending the random_id param with all compatible endpoints. This lets us adjust the API response to your users’ preferences and improve their GIF experience while maintaining their privacy.

URL
api.giphy.com/v1/randomid
Request Parameters:Example:Description:
api_key: string(required)YOUR_API_KEYGIPHY API Key.
Successful Response (200 OK)

Get GIF by ID Endpoint

Get GIF by ID returns a GIF’s metadata based on the GIF ID specified.

URL
api.giphy.com/v1/gifs/{gif_id}
Request Parameters:Example:Description:
api_key: string(required)YOUR_API_KEYGIPHY API Key.
gif_id: string(required)xT4uQulxzV39haRFjGThe ID of the GIF you want details for.
random_id: stringe826c9fc5c929e0d6c6d423841a282aaAn ID/proxy for a specific user.
Successful Response (200 OK)

Get GIFs by ID Endpoint

Get GIFs by ID returns metadata of multiple GIFs based on the GIF IDs specified.

URL
api.giphy.com/v1/gifs
Request Parameters:Example:Description:
api_key: string(required)YOUR_API_KEYGIPHY API Key.
ids: string(required)xT4uQulxzV39haRFjG, 3og0IPxMM0erATueVWFilters results by specified GIF IDs, separated by commas.
random_id: stringe826c9fc5c929e0d6c6d423841a282aaAn ID/proxy for a specific user.
Successful Response (200 OK)

Upload Endpoint

GIPHY Upload allows you to upload your content programmatically on GIPHY.com. We accept animated GIFs or video files up to 100MB.

Note: If you're using a rate-limited key assigned by the developer portal, you will not be able to specify a GIPHY channel username to your request and you will be limited to 10 uploads per day. To have these limits removed, you can apply for a production key from your dashboard. Only approved apps will be able to include a GIPHY channel username. You can use this endpoint to upload your content, attach tags, and other meta tag in a single HTTP or HTTPS POST request.

URL
upload.giphy.com/v1/gifs
Request Parameters:Example:Description:
api_key: string(required)YOUR_API_KEYGIPHY API Key.
username: stringJoeCool3000Your assigned username (required for approved apps only).
file: string(binary)The animated GIF or video file you'd like to upload. (Local file resource, required if no source_image_url supplied).
source_image_url: stringhttp://www.mysite.com/myfile.mp4The URL for the image or video you wish to upload (required if no file parameter specified).
tags: stringpets, cat, meowA comma delimited list of tags to be applied to the upload.
source_post_url: stringhttp://www.mysite.com/my-post/The URL of the source of the asset.
Successful Response (200 OK)

GIPHY Custom APIs

If you’d like to customize your app's GIF experience further, we have even more endpoints for you to choose from! To request access to any of the below endpoints, please reach out to us at api@giphy.com.

Additional endpoints include:

Categories API

Allows users to explore and select from available GIF categories and subcategories on GIPHY.

Search Suggestions API

Lets users to discover new and engaging content by providing a list of additional search terms related to the one they originally provided.

Autocomplete API

Speeds up user's search by returning a list of completed search terms given the partial search term already provided.

Trending Search Terms API

Provides users a list of the most popular trending search terms on the GIPHY network.


Schema definitions

The GIF Object

GIF Objects are returned from most of GIPHY API's Endpoints. These objects contain a variety of information, such as the Image Object, which itself includes the URLS for multiple different GIFS formats and sizes.

PropertyExample
type: string(default:"gif")
By default, this is almost always GIF.
"gif"
id: string
This GIF's unique ID
"YsTs5ltWtEhnq"
slug: string
The unique slug used in this GIF's URL
"confused-flying-YsTs5ltWtEhnq"
url: string
The unique URL for this GIF
"http://giphy.com/gifs/confused-flying-YsTs5ltWtEhnq"
bitly_url: string
The unique bit.ly URL for this GIF
"http://gph.is/1gsWDcL"
embed_url: string
A URL used for embedding this GIF
"http://giphy.com/embed/YsTs5ltWtEhnq"
username: string
The username this GIF is attached to, if applicable
"JoeCool4000"
source: string
The page on which this GIF was found
"http://www.reddit.com/r/reactiongifs/comments/1xpyaa/superman_goes_to_hollywood/"
rating: string
The MPAA-style rating for this content. Examples include Y, G, PG, PG-13 and R
"g"
content_url: string
Currently unused
user: User
An object containing data about the user associated with this GIF, if applicable.
source_tld: string
The top level domain of the source URL.
"cheezburger.com"
source_post_url: string
The URL of the webpage on which this GIF was found.
"http://cheezburger.com/5282328320"
update_datetime: string
The date on which this GIF was last updated.
"2013-08-01 12:41:48"
create_datetime: string
The date this GIF was added to the GIPHY database.
"2013-08-01 12:41:48"
import_datetime: string
The creation or upload date from this GIF's source.
"2013-08-01 12:41:48"
trending_datetime: string
The date on which this gif was marked trending, if applicable.
"2013-08-01 12:41:48"
images: Images
An object containing data for various available formats and sizes of this GIF.
title: string
The title that appears on giphy.com for this GIF.
"Happy Dancing GIF"

The Images Object

The Images Object found in the GIF Object contains a series of Rendition Objects. These Rendition Objects includes the URLs and sizes for the many different renditions we offer for each GIF. For more information and best practices on selecting the best image format for your needs, please see our Rendition Guide. (Please note that some GIFs don’t have every property available.)

ObjectPropertyExample
fixed_height: object
Data on versions of this GIF with a fixed height of 200 pixels. Good for mobile use.
url: string
The publicly-accessible direct URL for this GIF for this size of the GIF.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/200.gif"
width: string
The width of this GIF in pixels.
"320"
height: string
The height of this GIF in pixels.
"200"
size: string
The size of this GIF in bytes.
"32381"
mp4: string
The URL for this GIF in .MP4 format.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/200.mp4"
mp4_size: string
The size in bytes of the .MP4 file corresponding to this GIF.
"25123"
webp: string
The URL for this GIF in .webp format.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/200.webp"
webp_size: string
The size in bytes of the .webp file corresponding to this GIF.
"12321"
fixed_height_still: object
Data on a static image of this GIF with a fixed height of 200 pixels.
url: string
The publicly-accessible direct URL for this GIF.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/200_s.gif"
width: string
The width of this GIF in pixels.
"320"
height: string
The height of this GIF in pixels.
"200"
fixed_height_downsampled: object
Data on versions of this GIF with a fixed height of 200 pixels and the number of frames reduced to 6.
url: string
The publicly-accessible direct URL for this GIF.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/200_d.gif"
width: string
The width of this GIF in pixels.
"320"
height: string
The height of this GIF in pixels.
"200"
size: string
The size of this GIF in bytes.
"32381"
webp: string
The URL for this GIF in .webp format.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/200_d.webp"
webp_size: string
The size in bytes of the .webp file corresponding to this GIF.
"12321"
fixed_width: object
Data on versions of this GIF with a fixed width of 200 pixels. Good for mobile use.
url: string
The publicly-accessible direct URL for this GIF.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/200w.gif"
width: string
The width of this GIF in pixels.
"320"
height: string
The height of this GIF in pixels.
"200"
size: string
The size of this GIF in bytes.
"32381"
"32381"
mp4: string
The URL for this GIF in .MP4 format.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/200w.mp4"
mp4_size: string
The size in bytes of the .MP4 file corresponding to this GIF.
"25123"
webp: string
The URL for this GIF in .webp format.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/200w.webp"
webp_size: string
The size in bytes of the .webp file corresponding to this GIF.
"12321"
fixed_width_still: object
Data on a static image of this GIF with a fixed width of 200 pixels.
url: string
The publicly-accessible direct URL for this GIF.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/200w_s.gif"
width: string
The width of this GIF in pixels.
"320"
height: string
The height of this GIF in pixels.
"200"
fixed_width_downsampled: object
Data on versions of this GIF with a fixed width of 200 pixels and the number of frames reduced to 6.
url: string
The publicly-accessible direct URL for this GIF.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/200w_d.gif"
width: string
The width of this GIF in pixels.
"320"
height: string
The height of this GIF in pixels.
"200"
size: string
The size of this GIF in bytes.
"32381"
webp: string
The URL for this GIF in .webp format.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/200w_d.webp"
webp_size: string
The size in bytes of the .webp file corresponding to this GIF.
"12321"
fixed_height_small: object
Data on versions of this GIF with a fixed height of 100 pixels. Good for mobile keyboards.
url: string
The publicly-accessible direct URL for this GIF.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/100.gif"
width: string
The width of this GIF in pixels.
"320"
height: string
The height of this GIF in pixels.
"100"
size: string
The size of this GIF in bytes.
"32381"
mp4: string
The URL for this GIF in .MP4 format.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/100.mp4"
mp4_size: string
The size in bytes of the .MP4 file corresponding to this GIF.
"25123"
webp: string
The URL for this GIF in .webp format.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/100.webp"
webp_size: string
The size in bytes of the .webp file corresponding to this GIF.
"12321"
fixed_height_small_still: object
Data on a static image of this GIF with a fixed height of 100 pixels.
url: string
The publicly-accessible direct URL for this GIF.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/100_s.gif"
width: string
The width of this GIF in pixels.
"320"
height: string
The height of this GIF in pixels.
"100"
fixed_width_small: object
Data on versions of this GIF with a fixed width of 100 pixels. Good for mobile keyboards.
url: string
The publicly-accessible direct URL for this GIF.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/100w.gif"
width: string
The width of this GIF in pixels.
"100"
height: string
The height of this GIF in pixels.
"200"
size: string
The size of this GIF in bytes.
"32381"
mp4: string
The URL for this GIF in .MP4 format.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/100w.mp4"
mp4_size: string
The size in bytes of the .MP4 file corresponding to this GIF.
"25123"
webp: string
The URL for this GIF in .webp format.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/100w.webp"
webp_size: string
The size in bytes of the .webp file corresponding to this GIF.
"12321"
fixed_width_small_still: object
Data on a static image of this GIF with a fixed width of 100 pixels.
url: string
The publicly-accessible direct URL for this GIF.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/100w_s.gif"
width: string
The width of this GIF in pixels.
"100"
height: string
The height of this GIF in pixels.
"200"
downsized: object
Data on a version of this GIF downsized to be under 2mb.
url: string
The publicly-accessible direct URL for this GIF.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/giphy-downsized.gif"
width: string
The width of this GIF in pixels.
"320"
height: string
The height of this GIF in pixels.
"200"
size: string
The size of this GIF in bytes.
"12381"
downsized_still: object
Data on a static preview image of the downsized version of this GIF.
url: string
The publicly-accessible direct URL for this GIF.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/giphy-downsized_s.gif"
width: string
The width of this GIF in pixels.
"320"
height: string
The height of this GIF in pixels.
"200"
downsized_large: object
Data on a version of this GIF downsized to be under 8mb.
url: string
The publicly-accessible direct URL for this GIF.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/giphy-downsized-large.gif"
width: string
The width of this GIF in pixels.
"320"
height: string
The height of this GIF in pixels.
"200"
size: string
The size of this GIF in bytes.
"12381"
downsized_medium: object
Data on a version of this GIF downsized to be under 5mb.
url: string
The publicly-accessible direct URL for this GIF.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/giphy-downsized-medium.gif"
width: string
The width of this GIF in pixels.
"320"
height: string
The height of this GIF in pixels.
"200"
size: string
The size of this GIF in bytes.
"12381"
downsized_small: object
Data on a version of this GIF downsized to be under 200kb.
url: string
The publicly-accessible direct URL for this GIF.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/downsized_small.gif"
width: string
The width of this GIF in pixels.
"320"
height: string
The height of this GIF in pixels.
"200"
size: string
The size of this GIF in bytes.
"12381"
original: object
Data on the original version of this GIF. Good for desktop use.
width: string
The width of this GIF in pixels.
"320"
height: string
The height of this GIF in pixels.
"200"
size: string
The size of this GIF in bytes.
"12381"
frames: string
The number of frames in this GIF.
"15"
mp4: string
The URL for this GIF in .MP4 format.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/giphy.mp4"
mp4_size: string
The size in bytes of the .MP4 file corresponding to this GIF.
"25123"
webp: string
The URL for this GIF in .webp format.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/giphy.webp"
webp_size: string
The size in bytes of the .webp file corresponding to this GIF.
"12321"
original_still: object
Data on a static preview image of the original GIF.
url: string
The publicly-accessible direct URL for this GIF.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/giphy_s.gif"
width: string
The width of this GIF in pixels.
"320"
height: string
The height of this GIF in pixels.
"200"
looping: object
Data on the 15 second version of the GIF looping.
mp4: string
The URL for this GIF in .MP4 format.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/looping.mp4"
preview: object
Data on a version of this GIF in .MP4 format limited to 50kb that displays the first 1-2 seconds of the GIF.
mp4: string
he URL for this GIF in .MP4 format.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/giphy-preview.mp4"
mp4_size: string
The size of this file in bytes.
"20241"
width: string
The width of this file in pixels.
"320"
height: string
The height of this file in pixels.
"200"
preview_gif: object
Data on a version of this GIF limited to 50kb that displays the first 1-2 seconds of the GIF.
url: string
The URL for this preview GIF.
"https://media1.giphy.com/media/cZ7rmKfFYOvYI/giphy-preview.gif"
width: string
The width of this GIF in pixels.
"320"
height: string
The height of this GIF in pixels.
"200"

The Meta Object

The Meta Object contains basic information regarding the response and its status. You can learn more about the different types of response codes the API might give you in the Response Codes section.

PropertyExample
msg: string
HTTP Response Message.
(required)
"OK"
status: integer (int32)
HTTP Response Code.
(required)
200
response_id: string
A unique ID paired with this response from the API.
"57eea03c72381f86e05c35d2"

The Pagination Object

The Pagination Object contains information relating to the number of total results available as well as the number of results fetched and their relative positions.

PropertyExample
offset: integer (int32)
Position in pagination.
2591
total_count: integer (int32)
Total number of items available (not returned on every endpoint).
250
count: integer (int32)
Total number of items returned.
25

The User Object

The User Object contains information about the user associated with a GIF and URLs to assets such as that user's avatar image, GIPHY profile, and more.

PropertyExample
avatar_url: string
The URL for this user's avatar image.
"https://media1.giphy.com/avatars/election2016/XwYrZi5H87o6.gif"
banner_url: string
The URL for the banner image that appears atop this user's profile page.
"https://media4.giphy.com/avatars/cheezburger/XkuejOhoGLE6.jpg"
profile_url: string
The URL for this user's GIPHY profile.
"https://giphy.com/cheezburger/"
username: string
The username associated with this user.
"joecool4000"
display_name: string
The display name associated with this user (contains formatting the base username might not).
"JoeCool4000"

The Random ID Object

The Random ID Object contains a random hash.

PropertyExample
random_id: string
Random ID hash.
"3640f6095c9a1f0f4e544b764d238b25"

The Analytics Object

Most of our endpoints return an Analytics Object. The Analytics Object provides URLs so you can register actions, such as when a user views, clicks, or sends a GIF. For detailed instructions, refer to the Action Register Endpoint.

PropertyExample
onload: objecturl: string
The URL to register a 'view' action by a user.
"URL"
onclick: objecturl: string
The URL to register a 'click' action by a user.
"URL"
onsent: objecturl: string
The URL to register a 'send' action by a user.
"URL"

Response Codes

The API will return a Meta Object in its response containing one of the following codes to describe the result of your request.

CodeTypeDescription
200OKYour request was successful!
400Bad RequestYour request was formatted incorrectly or missing a required parameter(s).
403ForbiddenYou weren't authorized to make your request; most likely this indicates an issue with your API Key.
404Not FoundThe particular GIF or Sticker you are requesting was not found. This occurs, for example, if you request a GIF by using an id that does not exist.
429Too Many RequestsYour API Key is making too many requests. Read about requesting a Production Key to upgrade your API Key rate limits.