Getting Started with the GIPHY API

Congratulations, you've made the first step toward supercharging your project or app with the power of GIPHY!

GIPHY's GIF library is the largest in the world and includes millions of original GIFs directly from the world's best content partners, original GIF artists, as well as the best GIFs from across the entire internet.

GIPHY's APIs make it dead simple for developers to incorporate this vast library right inside of their apps to deliver highly interactive content that is proven to increase daily engagement across all types of apps; messaging, chat, dating, creation, community, and more.

GIPHY Labs is a great place to see various implementations of the GIPHY API. Learn more about the rest in the documentation below.

The GIPHY API implements a REST-like interface. Connections can be made with any HTTP or HTTPS enabled programming language. The GIPHY API also implements CORS, allowing you to connect to GIPHY from JavaScript / Web browsers on your own domain. The GIPHY API provides multiple file sizes, dimensions, and formats of every GIF to meet every clients potential needs. You can view a guide to the rendition offering here.

Optimized renditions for mobile to deliver GIFs that load fast and consume less bandwidth - see rendition guide here.

MP4s and Webps of every GIF!

MPAA rating filters supported across most endpoints

Access and API Keys

Get an API Key

To use the GIPHY API, you'll need to obtain an API Key by creating an app. You'll need a GIPHY account to create an app (don't worry, it's free!) Each application you create will have its own API Key. Don't worry if you're not sure what you want to use the GIPHY API for yet, all that's needed to create an app is a name and a basic description, which can be changed at any time.

Please use this key while you develop your application and experiment with your integrations. Note: your API Key is subject to rate limit constraints and we do not encourage live production deployments to use this key. If you're planning on a large-scale deployment, read on for information about obtaining a Production Key.

Request a Production Key

Once you're ready to use the GIPHY API in production, please visit your dashboard to request a production API key for your application. In your submission, please be prepared to provide the following:

Your app name with brief description, web / app store links, etc.

The 'live date' of the app and feature that integrates with the API. Briefly describe how the GIPHY API integrates with your app and provide screenshots of the implementation.

As per our section 5 A of our terms of service, we require all apps that use the GIPHY API to conspicuously display "Powered By GIPHY" attribution marks where the API is utilized. You can find approved official logo marks here. Please provide screenshots of your attribution placement.

If you have any questions please feel free to contact us at api@giphy.com. Please submit API corrections via GitHub issues. Please see our terms of service for any restrictions on using the service. We also recommend using the JSONview plugin for Firefox or Chrome to view the API responses in your browser.

API Highlights

The GIPHY Search Endpoint is the granddaddy of them all, allowing your project or app to leverage the powerful GIF search found on giphy.com to your liking. GIPHY Search enables your users to instantly find the exact GIF they're looking for and discover new favorites. They'll never want to leave.

GIPHY's Trending Endpoint provides a collection of up-to-the-minute memes, tropes, and touchstones of pop culture, editorialized by real humans. Your users will have instant access to all of it.

The data returned mirrors the GIFs showcased on the GIPHY homepage. Returns 25 results by default.

Text and Emojis, step back! The GIPHY Translate Endpoint draws on search, but uses the GIPHY "special sauce" to handle translating from one vocabulary to another. In this case, words and phrases to GIFs. Example implementations of translate can be found in the GIPHY Slack, Hipchat, Wire, or Dasher integrations. Use a plus or url encode for phrases.

Need a random GIF on the fly? Say no more. The Random Endpoint returns a random GIF, limited by tag. Tell us what kind of GIF you're looking for by keyword, and we'll spin the wheel to deliver you something special and new every time. You never know what you're going to get, but we know you you're going to like it.

GIPHY Sticker API

The GIPHY Sticker API is an API that provides only animated stickers (aka animated GIFs with transparent backgrounds) in the responses. Stickers are great for messaging apps, games, and other times where a background or a square frame just won't do.

Also available are are Sticker Packs: collections of Stickers for use in your app, including the Trending and Reactions Sticker Packs, hand-curated by the GIPHY Editorial team! The endpoints relating to Sticker Packs are:

Like the primary GIPHY API, the Sticker API is open to the public. All you need is an API Key, which you can get for free by creating an app.

Please use this key while you develop your application and experiment with your integrations. Note: the key granted to you by this developer portal is subject to rate limit constraints. If you require production-level scale for your application, apply for a production key from your dashboard. If you have more questions about rate-limits and other distinctions between API Keys, please read our FAQ.

GIPHY Upload API

"The GIPHY Upload API allows you to build on top of the world's largest and fastest GIF hosting platform...for free! Upload GIFs up to 100MB or convert videos to GIFs on the fly. Leverage our extensive rendition options to retrieve mp4s, webp, embeds, and all sorts of sizes large and small of your content. Hosted GIPHY URLs are supported and play on every major social network.

Code Examples

Below are code samples in Python, JavaScript, Ruby, PHP and the command line on connecting to the API to make a search query for "ryan gosling". Also note that we provide open-source, language-specific code in the form of our GIPHY SDKs that make connecting to and interacting with our API even simpler in your Javascript, Python, Ruby and PHP projects.

PHP

Sample Responses

Below are some sample responses for some typical calls to the GIPHY API. Most responses return either a GIF Object or a list of GIF Objects.

Sample Search Endpoint Response

This call to http://api.giphy.com/v1/gifs/search?q=funny+cat&api_key=YOUR_API_KEY returns 25 GIF Objects for the search term funny cat. Each GIF Object contains an Images Object containing URLs for various versions of the GIF as described in our Rendition Guide.

Rendition Guide

When rendering GIFs, you can use any of the following designations.

Please Note

When making requests that return GIF objects, the accept http header can be used to toggle the content type you will receive in return. By including accept: image/* the binary media file will be returned, otherwise some markup embedding the GIF is returned.

You should not rely on size value in the API response being exactly correct. This is because we may choose to replace some pre-built renditions with dynamically generated renditions, and we will therefore not have an exact size value in advance.

fixed_height - Height set to 200px. Good for mobile use.

fixed_height_still - Static preview image for fixed_height

fixed_height_downsampled - Height set to 200px. Reduced to 6 frames to minimize file size to the lowest. Works well for unlimited scroll on mobile and as animated previews. See GIPHY.com on mobile web as an example.

fixed_width - Width set to 200px. Good for mobile use.

fixed_width_still - Static preview image for fixed_width

fixed_width_downsampled - Width set to 200px. Reduced to 6 frames. Works well for unlimited scroll on mobile and as animated previews.

GIPHY SDKs

GIPHY also offers several open-source platform-specific SDKs that make integrating the GIPHY API even easier. Available for iOS, Android and various other programming languages, the code can be found in the following Github repositories under the Mozilla Public License, v. 2.0. Where applicable, binaries are published to public repositories.

With the GIPHY SDKs, there's no need to re-invent the wheel: if you use GIPHY in your application, the SDK provides you with a library that will have you implementing features faster. The SDKs are all open-source, so if you think a feature is missing or have an idea for an improvement, feel free to make a pull request and send it our way!

Sharing and Promoting your GIPHY API Project

Have you built something awesome with the GIPHY API? Get in touch so your project can join the hallowed ranks of GIPHY Labs, our testing ground and showcase for all things GIPHY!

Technical Documentation / Specifications

Here you'll find the nitty gritty of the GIPHY API's various endpoints, including required parameters and explanations of the responses you'll receive.

Description

Sticker Packs: Individual Sticker Pack Endpoint

Host

api.giphy.com

Path

GET /v1/stickers/packs/{pack_id}

Description

Returns the metadata for any Sticker pack. Note that convenience URLs for GIPHY's curated Trending and Reactions Sticker Packs exist at /v1/stickers/packs/trending and /v1/stickers/packs/reactions, respectively.

Sticker Packs: Children Pack Listing Endpoint

Host

api.giphy.com

Path

GET /v1/stickers/packs/{pack_id}/children

Description

A Sticker pack is a recursive data structure and so packs may contain other packs. For example, the 'Reactions' pack would have an 'OMG' child pack. This endpoint lists all children packs of a given Sticker pack. Note that convenience URLs for GIPHY's curated Trending and Reactions Sticker Packs exist at /v1/stickers/packs/trending/children and /v1/stickers/packs/reactions/children, respectively.

Upload API: Upload Endpoint

Host

api.giphy.com

Path

POST upload.giphy.com/v1/gifs

Description

The GIPHY Upload Endpoint allows you to upload and host your content programmatically to 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. Apply for a production key from your dashboard to have these limits lifted. Only approved apps will need to include a GIPHY channel username. You can use the endpoint to upload your content, attach tags and other meta tag in a single HTTP or HTTPS POST request.

Example

api_key: string

GIPHY API Key.

YOUR_API_KEY

username: string

Your assigned username (required for approved apps only).

JoeCool3000

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

The URL for the image or video you wish to upload (required if no file parameter specified)

Data surrounding the original version of this GIF. Good for desktop use.

url:string

The publicly-accessible direct URL for this GIF.

"https://media1.giphy.com/media/cZ7rmKfFYOvYI/giphy.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"

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 surrounding 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 surrounding a version of this GIF set to loop for 15 seconds.

mp4:string

The URL for this GIF in .MP4 format.

"https://media1.giphy.com/media/cZ7rmKfFYOvYI/looping.mp4"

preview:object

Data surrounding a version of this GIF in .MP4 format limited to 50kb that displays the first 1-2 seconds of the GIF.

mp4:string

The 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 surrounding 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"

size:string

The size of this file in bytes.

"10291"

The Meta Object

The Meta Object contains basic information regarding the request, whether it was successful, and the response given by the API. Click here to see a description of types of response codes the API might give you under different circumstances.

Property

Example

msg:string

HTTP Response Message

"OK"

status:integer(int32)

HTTP Response Code

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.

Property

Example

offset:integer(int32)

Position in pagination.

2591

total_count:integer(int32)

Total number of items available.

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, profile, and more.

Property

Example

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

twitter:string

The Twitter username associated with this user, if applicable.

"@joecool4000"

The Child Pack Object

A Sticker Pack is a collection of Stickers. Both the Sticker Pack Metadata Object and Child Pack Objects are recursive data structures that contains metadata about a Sticker Pack itself, the stickers contained therein, and potentially sub-packs. (Sticker packs may be nested arbitrarily and are navigated like any recursive data structure.) The Child Pack Object is a condensed collection of information about a Sticker Pack that appears in listings of Sticker Packs.

Property

Example

id:integer(int32)

This Sticker Pack's unique numeric ID.

3151

parent:integer(int32)

Numeric identifier for the parent Sticker Pack.

3150

type:string

Will return "community" or "editorial". This describes whether this Sticker Pack is curated by GIPHY or by the community.

"community"

content_type:string

Will always return "sticker" in this case.

"sticker"

slug:string

URL-friendly name for this Sticker Pack.

"love"

display_name:string

Human-readable name for this Sticker Pack. (May contain formatting the other names don't).

"Love"

short_display_name:string

A more concise version of this Sticker Pack's display name.

"Love"

description:string

Long form description of this Sticker Pack.

"The most lovely stickers on the interweb!"

banner_image:string

Will return a banner image for this Sticker Pack (either JPG, PNG, or GIF) with 1040x160 dimensions.

The GIF that will appear in a thumbnail, header image or other visual representation when referencing this Sticker Pack.

The Sticker Pack Metadata Object

A Sticker Pack is a collection of Stickers. Both the Sticker Pack Metadata Object and Child Pack Objects are recursive data structures that contains metadata about a Sticker Pack itself, the stickers contained therein, and potentially sub-packs. (Sticker packs may be nested arbitrarily and are navigated like any recursive data structure.) The Sticker Pack Metadata Object is an expanded collection of information about a Sticker Pack.

Property

Example

id:integer(int32)

This Sticker Pack's unique numeric ID.

3151

display_name:string

Human-readable name for this Sticker Pack. (May contain formatting the other names don't).

"Trending"

slug:string

URL-friendly slug for this Sticker Pack.

"trending"

content_type:string

Will always return "sticker" in this case.

"sticker"

short_display_name:string

A more concise version of this Sticker Pack's display name.

"Love"

description:string

Long form description of this Sticker Pack.

"The most lovely stickers on the interweb!"

banner_image:string

Will return a banner image for this Sticker Pack (either JPG, PNG, or GIF) with 1040x160 dimensions.