Implementation Options

There are two possible approaches to integrating a GIPHY experience into your app: the GIPHY API and the GIPHY SDK.

The GIPHY API is a set of endpoints for fetching and displaying GIFs, Stickers, and other GIPHY content in your app. The GIPHY SDK contains all the base functionality of the GIPHY API but also includes GIPHY-developed and platform-specific wrappers, UI templates, and other helper methods for an even easier and more seamless integration into your app.

The 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 the GIPHY SDK!

Note: All API Keys start as beta keys, which are rate limited (100 searches/API calls per hour.) If you need more than 100 API calls per hour you will need to upgrade your API Key to production status via your dashboard.

Content Types

At GIPHY, we believe everything should move and it’s part of our mission to help make everyday conversations more animated. With our growing list of content types, expressing yourself with GIPHY has never been easier.

Please note that the Clips, Emoji, Text, and GIPHY Text content types are only available through the SDK.

GIFs

GIFs are short, looping, moving images. Need we say more?

Stickers

Stickers are GIFs with transparent backgrounds. They’re great for layering animated content on top of all kinds of use cases: messaging apps, stories (e.g., IG, Snap, FB etc.), or games. Basically, any time a square frame just won't do.

Clips

GIPHY Clips (GIFs with Sound) is our newest format and sits at the intersection of GIFs and Video. Our Clips Library is built with all of the unforgettable quotes, cultural moments, reactions and characters that we need to express how we are feeling, what we think and who we are.

We are making short form expression discoverable via GIPHY Clips Search, with Clips from official content partners and GIPHY Studios. Every day you will find new Clips from the biggest names in Entertainment, Sports, News, and Pop Culture; all trimmed to their most essential moment.

Emoji

GIPHY Emojis are fully animated emoji stickers. No longer are these familiar, emotive faces frozen in place, as GIPHY emoji brings life and motion to some all time favorites with inclusive representation, as well as some new (and uniquely GIPHY) emojis.

Text

GIPHY Text features animated text-based stickers, making it easy to add that perfect amount of sarcasm, enthusiasm, or whatever emotion is needed to the conversation.

GIPHY Text

GIPHY Text is dynamically generated using the user’s search term and our pre-populated set of styles. This content type can be leveraged when you know exactly what you’d like to say and would like to animate your words.

GIPHY Alt Text

Alt text on GIPHY is now available for our most popular pieces of content based on top search terms, with plans to gradually roll out alt text to more of our library. This means that alt text will automatically be read aloud via screen reader devices. For GIPHY integration partners, alt text can be leveraged via the API. If interested, please reach out to bd.team@giphy.com.

Design Guidelines

Sketch UI Kit

Ready to design your GIPHY experience? Download our Sketch UI Kit to drag and drop elements into your app and experiment with layouts, fonts, colors, and content that work best for you.

Brand Guidelines

While we have included a branded button for SDK users, you may need our logo for other purposes. Check out the links below to download GIPHY-approved logos and icons, along with our brand guidelines.

For general best practices related to the GIPHY brand, see our Brand Guidelines and be sure to check out our SDK License Agreement. By using GIPHY SDK, you are agreeing to the SDK License Agreement.

Supported Platforms

GIPHY supports the following platforms:

• iOS
• Android
• Web (JS/React)
• React Native
• Flutter

GIPHY SDK for iOS

Get started with our iOS docs here.

Github Example Repo

Give the iOS SDK example app a spin to see what it's all about.

We also use Github for documentation, release notes, issue tracking, and more.

• View the docs.
• View releases
• Open issues or feature requests

GIPHY SDK for Android

Get started with the Android docs here

Github Example Repo

Give the Android SDK example app a spin to see what it's all about.

We also use Github for documentation, release notes, issue tracking, and more.

• Run the example app to see the GIPHY SDK in action with all of its configurations.
• View the docs.
• Open issues or feature requests
• View releases

GIPHY SDK for Web

The React SDK consists of Gif, Grid, and Carousel components. It uses the Fetch API to fetch data. All React SDK components also support Server Side Rendition(SSR). Here's a codesandbox for an example of SSR with next.js

Not using React? We have vanilla JavaScript components as well: Gif, Grid, and Carousel.

Installation

Install using npm or yarn:

yarn add @giphy/react-components @giphy/js-fetch-api

Checkout the github repo here.

Getting started

Here is a basic example of how to render a Grid of gifs using the Grid component and the Fetch API. You'll need an API key to fetch data that will be used to populate your components. You can apply for an API key here.

import { Grid } from '@giphy/react-components'
import { GiphyFetch } from '@giphy/js-fetch-api'
const gf = new GiphyFetch('your api key')
const fetchGifs = (offset: number) => gf.trending({ offset, limit: 10 })
ReactDOM.render(<Grid width={800} columns={3} fetchGifs={fetchGifs} />, target)

See the SDK in action

Live edit our SDK components here and try it out for yourself!

Learn more

• Fetch API - Wraps fetches to the GIPHY API and returns typed response. Fetch trending, search, related, emoji and more.
• React SDK - UI Component library using React.
• JavaScript SDK - UI Components you can append to the DOM.

GIPHY SDK for React Native

Get started with our React Native docs here.

Installation

yarn add @giphy/react-native-sdk
npm install @giphy/react-native-sdk --save
pod install

Useful links

• View the docs.
• Give the React Native SDK example app a spin to see what it's all about.
• View releases
• Open issues or feature requests

GIPHY SDK for Flutter

Get started with our Flutter docs here.

Github Example Repo

Give the Flutter SDK example app a spin to see what it's all about.

We also use Github for documentation, release notes, issue tracking, and more.

• View the docs.
• View releases
• Open issues or feature requests

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

The following guide will walk you through the minimum viable GIPHY API integration for a seamless GIPHY experience in your app. If you have any questions, email us at developers@giphy.com.

Apply for an API Key(s)

1. Create a GIPHY API Key by clicking “Create an API Key” on the Developer Dashboard (you need to create an account first).
   Note: All API Keys start as beta keys, which are rate limited (100 searches/API calls per hour.) If you need more than 100 API calls per hour you will need to upgrade your API Key to production status via your dashboard.
   The Company may adjust rate limits or key statuses for older (legacy) API Keys as needed, to comply with regulatory or operational requirements.
2. Create separate keys for each platform (iOS, Android, Web) and section. If you’re using a GIPHY integration in different sections of your app, GIPHY requires that each use of our service be delineated by a different key for each section per platform.

Implement Necessary API Endpoints

The GIPHY experience is brought to life with two essential endpoints: Trending and Search.

The Trending endpoint automatically populates the most relevant and engaging content each and every day, while the Search endpoint lets users search our library of millions of GIFs and Stickers by entering a word or phrase.

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.

Upgrade API Key(s) to Production Level

1. Once your app is QA complete and close to going live, it’s time to upgrade your API key(s) to Production Level.
2. In the Developer Dashboard, click the “Upgrade to Production” button for eachAPI key used in your app and complete the instructions that follow.

Attribution

We require all apps that use the 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.

Best Practices

Best Practices for Renditions

1. For the vast majority of GIPHY integrations, we recommend using MP4 for gifs and WEBP for stickers, which provides high image quality for relatively small file sizes, and is supported on all major platforms and web browsers. For more information, see our Rendition Guide.
2. Every GIF returned by the Trending and Search endpoints contains an images object with Media URLs (url field). The images object returns multiple renditions.
3. We provide various renditions of each GIF in the images object to give your users the best experience possible. Generally, it’s best to use the smaller fixed_height or fixed_width renditions on your preview grid.
4. Once a user has selected a GIF, present a higher resolution rendition.
5. If you have bandwidth limitations consider using downsized_small(max 200kB), downsized (max 2MB), downsized_medium(max 5MB) renditions.
6. Refer to our Rendition Guide for more information on what rendition is best suited for each use-case.

Prohibited Integration Practices

1. Do not strip or modify URLs returned by the API. In particular, do not remove or modify query params in our media URLs while rendering the media assets.
2. Do not cache API responses or media URLs or cache or store copies of GIPHY's media assets.This is vital for ensuring content safety.
3. Do not proxy requests to GIPHY, either API calls or media URL loads. All requests to GIPHY should be made directly from the client side (e.g. your app or web browser).
4. Do not reorder content or filter out our content returned from GIPHY's search of trending API responses.
5. Do not mix GIPHY's content with content from other providers in the same grid.

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!

"analytics": {
  "onload": {
    "url": "https:
                          analytics_response_payload=e%3DZXZlbnRf&action_type=SEEN"
  },
  "onclick": {
    "url": "https:
                          analytics_response_payload=e%3DZXZlbnRf&action_type=CLICK"
  },
  "onsent": {
    "url": "https:
                          analytics_response_payload=e%3DZXZlbnRf&action_type=SENT"
  }
}

1
2const analytics = gifItem.analytics;
3
4
5const baseUrl = new URL(analytics.onload.url);
6
7baseUrl.searchParams.append('ts', Date.now().toString());
8baseUrl.searchParams.append('random_id', randomId);
9
10
11const pingRes = await fetch(baseUrl.toString());
12

Schema definitions

"analytics": {
  "onload": {
    "url": "https:
                          analytics_response_payload=e%3DZXZlbnRf&action_type=SEEN"
  },
  "onclick": {
    "url": "https:
                          analytics_response_payload=e%3DZXZlbnRf&action_type=CLICK"
  },
  "onsent": {
    "url": "https:
                          analytics_response_payload=e%3DZXZlbnRf&action_type=SENT"
  }
}

Synthetic Response

GIPHY API returns a synthetic response when there are issues with GIPHY downstream systems. This API response object has a meta.status=200, meta.response_id="" and the rest of the API object is empty. This should be treated as an error state and handled accordingly in the application.

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.

Rendition Guide

Renditions

All GIPHY content comes in multiple renditions, or sizes and formats, to better suit different use cases. We provide a few ways for developers to customize their UI and provide the best experiences to their users. In general we recommend:

• Using MP4 and WEBP renditions where supported. This will maximize quality and reduce load times.
• For standard GIFs (no transparency): Use MP4 wherever supported, or WEBP as a fallback. Do not use the GIF format.
• For stickers (with transparency): Use WEBP wherever possible. MP4 does not support transparency, and GIF should not be used.
• Use the smaller fixed_height or fixed_width renditions on your preview grid. These smaller sizes are more performant when you want to load many GIF objects at once.
• Use the largest possible rendition for the share or send. Once the user has selected a GIF, give them the best quality possible!

Of course, these configurations are just some of our best practices – GIPHY’s renditions can be configured in lots of different ways.

Rendition Best Practices by Use Case

GIF Grid Picker in a Mobile Application Grid: fixed_height or fixed width MP4 or WEBP. Send: downsized_large, downsized, or downsized_medium MP4 or WEBP.

GIF Scroll Picker in a Mobile Application Scroll: fixed_width_small or fixed_height_small. Send: downsized_large, downsized, or downsized_medium.

Desktop Application Search and Send Grid: fixed_height or fixed width MP4 or WEBP. Send: original WEBP or MP4.

Sticker Layering Grid: fixed_height or fixed_width webp or GIF. Send: original webp or GIF.

Renditions on Demand

Common RoD uses cases and filters

Using RoD bundles for specific renditions If there is a specific rendition you know that you want in a given context, RoD filters allow you to filter out all but that specific rendition.

Example : only return stickers for a video editing app
'https://api.giphy.com/v1/stickers/search?api_key={YOUR API KEY}&q=hello&bundle=sticker_layering'

Rendition glossary

Fields On Demand

In addition to Renditions on Demand, the GIPHY API allows you to request only the data you need, significantly reducing the response payload size.

Language Support

GIPHY supports the following language codes for the lang parameter in your API requests. Including this parameter helps GIPHY improve so we can deliver better, more relevant results for non-english searches.

Content Rating

GIFs are for everyone, and GIPHY is committed to making sure that its GIF search is a positive experience for everyone. We take content safety extremely seriously. Our GIF and Sticker library is thoroughly moderated and organized by rating in order to give GIPHY users the safest possible search experience. We do not hesitate to remove content that falls outside of our Community Guidelines.

Content Rating Levels

Please contact support@giphy.com if you see any content that you feel is incorrectly rated or in violation of GIPHY’s Community Guidelines. Also, feel free to reach out if you have any general questions about content safety at GIPHY as well.

Safe Search Terms

GIPHY maintains a list of keywords that will not return any results. These keywords are associated with content that is forbidden per our Community Guidelines. The list is regularly reviewed and updated to ensure that it includes topical, timely, and relevant entries.

API & SDK Partners can report inappropriate search queries by contacting support@giphy.com. Keywords can be added to the banned search query list when appropriate.

GIF Blocking Tool

Developers using GIPHY are able to customize their user experience by implementing a maximum Content Rating for their integration. In addition to this we also provide a GIF Blocking tool to remove content that falls within the selected Content Rating range, if desired. As a result, your moderation teams have more control over the integration too.

The GIF Blocking Tool can be accessed from the API key details page and accepts GIF IDs. Once added via this tool these GIFs will not be returned via the GIPHY API. Change your mind? You can also remove GIF IDs using the tool. Please allow up to 24 hours for changes to apply.

Code Example

Below are code samples for using the Search Endpoint in Python, JavaScript, Ruby, PHP and the command line on connecting to the API to make a search query for "Ryan Gosling."

1
2import json
3from urllib import parse, request
4
5url = "http://api.giphy.com/v1/gifs/search"
6
7params = parse.urlencode({
8  "q": "ryan gosling",
9  "api_key": "YOUR_API_KEY",
10  "limit": "5"
11})
12
13with request.urlopen("".join((url, "?", params))) as response:
14  data = json.loads(response.read())
15
16print(json.dumps(data, sort_keys=True, indent=4))

Below are code samples for using the Upload Endpoint to upload a remote file.

1
2import json
3from urllib import request
4
5url = "http://upload.giphy.com/v1/gifs"
6
7values = {
8  "api_key": "YOUR_API_KEY",
9  "username": "JoeCool3000",
10  "source_image_url": "http://www.mysite.com/myfile.mp4"
11}
12
13headers = {
14  "Content-Type": "application/json",
15  "Accept": "application/json",
16}
17
18data = json.dumps(values).encode("utf-8")
19
20req = request.Request(url, data, headers)
21with request.urlopen(req) as res:
22  print(res.read().decode())

Below are code samples for using the Upload Endpoint to upload a local file.

1import requests
2url = "https://upload.giphy.com/v1/gifs"
3file_path = "C:\test.gif"
4api_key = "YourApiKey"
5
6with open(file_path, 'rb') as file:
7  data = { 'api_key': api_key }
8  files = { 'file': file }
9  response = requests.post(url, data=data, files=files)
10  print(response.text)

Support

If you have questions or need help getting set-up with GIPHY SDK or API, you can take a look at our FAQ.

If you don’t see your question listed, feel free to submit a request through our Help Center and we’ll get back to you! If you think you’ve found a bug with the SDK or API or their documentation, please file an issue via GitHub Issues. Thanks!

API Explorer

The API Explorer is a nifty tool that lets you take the API for a spin by inputting some sample queries and viewing the live responses!