openapi: 3.1.0
info:
title: GIPHY API
description: |
The GIPHY API provides programmatic access to the world's largest library of
GIFs, stickers, animated emoji and Clips (GIFs with sound). Search, trending,
translate, random, and category endpoints all return rich media objects with
multiple image renditions optimized for any surface.
Authentication is via API key. New developers receive a rate-limited Beta key;
a Production key is granted after application review.
version: '1.0'
contact:
name: GIPHY Developers
url: https://developers.giphy.com/
email: [email protected]
termsOfService: https://developers.giphy.com/terms/
license:
name: GIPHY API Terms of Service
url: https://developers.giphy.com/terms/
servers:
- url: https://api.giphy.com
description: Production API
- url: https://upload.giphy.com
description: Upload API
security:
- ApiKeyAuth: []
tags:
- name: GIFs
description: Search, trending, translate, random, and lookup endpoints for animated GIFs.
- name: Stickers
description: The same surface as GIFs but scoped to transparent-background stickers.
- name: Emoji
description: GIPHY's animated emoji library and per-emoji variations.
- name: Clips
description: GIFs with sound. Access is gated; contact [email protected].
- name: Animate
description: Programmatic creation of animated text/word GIFs.
- name: Channels
description: Channel discovery and metadata.
- name: Categories
description: Top-level categories and subcategories used to organize GIFs.
- name: Search Discovery
description: Tag autocompletion, related search terms, and trending search queries.
- name: Analytics
description: Pingback and action register endpoints for measuring user engagement.
- name: Upload
description: Programmatic upload of GIFs and video assets.
- name: Utilities
description: Identifier generation and other helpers.
paths:
/v1/gifs/search:
get:
tags: [GIFs]
operationId: searchGifs
summary: Search GIFs
description: Search GIPHY's library of millions of GIFs by keyword.
parameters:
- $ref: '#/components/parameters/ApiKey'
- name: q
in: query
required: true
description: Search query term or phrase, URL-encoded, max 50 characters.
schema: { type: string, maxLength: 50 }
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
- $ref: '#/components/parameters/Rating'
- $ref: '#/components/parameters/Lang'
- $ref: '#/components/parameters/Bundle'
- $ref: '#/components/parameters/RandomId'
- $ref: '#/components/parameters/CountryCode'
responses:
'200': { $ref: '#/components/responses/GifListResponse' }
'400': { $ref: '#/components/responses/BadRequest' }
'401': { $ref: '#/components/responses/Unauthorized' }
'429': { $ref: '#/components/responses/RateLimited' }
/v1/gifs/trending:
get:
tags: [GIFs]
operationId: getTrendingGifs
summary: Get Trending GIFs
description: Return the most relevant and engaging GIFs each day.
parameters:
- $ref: '#/components/parameters/ApiKey'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
- $ref: '#/components/parameters/Rating'
- $ref: '#/components/parameters/Bundle'
- $ref: '#/components/parameters/RandomId'
- $ref: '#/components/parameters/CountryCode'
responses:
'200': { $ref: '#/components/responses/GifListResponse' }
'401': { $ref: '#/components/responses/Unauthorized' }
'429': { $ref: '#/components/responses/RateLimited' }
/v1/gifs/translate:
get:
tags: [GIFs]
operationId: translateGif
summary: Translate Term to GIF
description: Convert words and phrases to a single, contextually relevant GIF.
parameters:
- $ref: '#/components/parameters/ApiKey'
- name: s
in: query
required: true
description: Search term to translate to a GIF.
schema: { type: string }
- $ref: '#/components/parameters/Weirdness'
- $ref: '#/components/parameters/Rating'
- $ref: '#/components/parameters/RandomId'
responses:
'200': { $ref: '#/components/responses/SingleGifResponse' }
'400': { $ref: '#/components/responses/BadRequest' }
'401': { $ref: '#/components/responses/Unauthorized' }
/v1/gifs/random:
get:
tags: [GIFs]
operationId: getRandomGif
summary: Get Random GIF
description: Return a single random GIF, optionally filtered by tag.
parameters:
- $ref: '#/components/parameters/ApiKey'
- name: tag
in: query
required: false
description: Filter results by tag.
schema: { type: string }
- $ref: '#/components/parameters/Rating'
- $ref: '#/components/parameters/RandomId'
responses:
'200': { $ref: '#/components/responses/SingleGifResponse' }
'401': { $ref: '#/components/responses/Unauthorized' }
/v1/gifs/{gif_id}:
get:
tags: [GIFs]
operationId: getGifById
summary: Get GIF by ID
description: Retrieve metadata for a single GIF.
parameters:
- $ref: '#/components/parameters/ApiKey'
- name: gif_id
in: path
required: true
description: GIPHY ID of the GIF.
schema: { type: string }
responses:
'200': { $ref: '#/components/responses/SingleGifResponse' }
'404': { $ref: '#/components/responses/NotFound' }
/v1/gifs/categories:
get:
tags: [Categories]
operationId: listGifCategories
summary: List GIF Categories
description: Return the list of GIF categories.
parameters:
- $ref: '#/components/parameters/ApiKey'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
responses:
'200':
description: A paginated list of categories.
content:
application/json:
schema:
type: object
properties:
data: { type: array, items: { $ref: '#/components/schemas/Category' } }
pagination: { $ref: '#/components/schemas/Pagination' }
meta: { $ref: '#/components/schemas/Meta' }
/v1/gifs/search/tags:
get:
tags: [Search Discovery]
operationId: autocompleteSearchTags
summary: Autocomplete Search Tags
description: Return tag suggestions for a partial search term.
parameters:
- $ref: '#/components/parameters/ApiKey'
- name: q
in: query
required: true
description: Partial search term.
schema: { type: string }
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
responses:
'200':
description: Tag autocomplete results.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
name: { type: string }
analytics_response_payload: { type: string }
/v1/tags/related/{term}:
get:
tags: [Search Discovery]
operationId: getRelatedSearchTerms
summary: Get Related Search Terms
description: Return related search terms for a given query.
parameters:
- $ref: '#/components/parameters/ApiKey'
- name: term
in: path
required: true
schema: { type: string }
responses:
'200':
description: Related search terms.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
name: { type: string }
analytics_response_payload: { type: string }
/v1/trending/searches:
get:
tags: [Search Discovery]
operationId: getTrendingSearches
summary: Get Trending Search Terms
description: Return the most popular search terms across GIPHY.
parameters:
- $ref: '#/components/parameters/ApiKey'
responses:
'200':
description: Trending search terms.
content:
application/json:
schema:
type: object
properties:
data: { type: array, items: { type: string } }
meta: { $ref: '#/components/schemas/Meta' }
/v1/stickers/search:
get:
tags: [Stickers]
operationId: searchStickers
summary: Search Stickers
description: Search GIPHY's library of stickers (transparent-background animations).
parameters:
- $ref: '#/components/parameters/ApiKey'
- name: q
in: query
required: true
schema: { type: string, maxLength: 50 }
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
- $ref: '#/components/parameters/Rating'
- $ref: '#/components/parameters/Lang'
responses:
'200': { $ref: '#/components/responses/GifListResponse' }
/v1/stickers/trending:
get:
tags: [Stickers]
operationId: getTrendingStickers
summary: Get Trending Stickers
description: Return the most relevant and engaging stickers each day.
parameters:
- $ref: '#/components/parameters/ApiKey'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
- $ref: '#/components/parameters/Rating'
responses:
'200': { $ref: '#/components/responses/GifListResponse' }
/v1/stickers/translate:
get:
tags: [Stickers]
operationId: translateSticker
summary: Translate Term to Sticker
description: Convert words and phrases to a single contextually relevant sticker.
parameters:
- $ref: '#/components/parameters/ApiKey'
- name: s
in: query
required: true
schema: { type: string }
- $ref: '#/components/parameters/Weirdness'
- $ref: '#/components/parameters/Rating'
responses:
'200': { $ref: '#/components/responses/SingleGifResponse' }
/v1/stickers/random:
get:
tags: [Stickers]
operationId: getRandomSticker
summary: Get Random Sticker
description: Return a single random sticker, optionally filtered by tag.
parameters:
- $ref: '#/components/parameters/ApiKey'
- name: tag
in: query
required: false
schema: { type: string }
- $ref: '#/components/parameters/Rating'
responses:
'200': { $ref: '#/components/responses/SingleGifResponse' }
/v2/emoji:
get:
tags: [Emoji]
operationId: listEmoji
summary: List Animated Emoji
description: Return GIPHY's animated emoji library.
parameters:
- $ref: '#/components/parameters/ApiKey'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
responses:
'200': { $ref: '#/components/responses/GifListResponse' }
/v2/emoji/{gif_id}/variations:
get:
tags: [Emoji]
operationId: getEmojiVariations
summary: Get Emoji Variations
description: Return all variations of a single animated emoji.
parameters:
- $ref: '#/components/parameters/ApiKey'
- name: gif_id
in: path
required: true
schema: { type: string }
responses:
'200': { $ref: '#/components/responses/GifListResponse' }
/v1/clips/search:
get:
tags: [Clips]
operationId: searchClips
summary: Search Clips
description: Search the GIPHY Clips library (GIFs with sound).
parameters:
- $ref: '#/components/parameters/ApiKey'
- name: q
in: query
required: true
schema: { type: string }
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
- $ref: '#/components/parameters/Rating'
- $ref: '#/components/parameters/Lang'
- $ref: '#/components/parameters/CountryCode'
responses:
'200': { $ref: '#/components/responses/ClipListResponse' }
'403': { $ref: '#/components/responses/Forbidden' }
/v1/clips/trending:
get:
tags: [Clips]
operationId: getTrendingClips
summary: Get Trending Clips
description: Return the most popular Clips of the day.
parameters:
- $ref: '#/components/parameters/ApiKey'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
- $ref: '#/components/parameters/Rating'
- $ref: '#/components/parameters/CountryCode'
responses:
'200': { $ref: '#/components/responses/ClipListResponse' }
'403': { $ref: '#/components/responses/Forbidden' }
/v1/animate:
get:
tags: [Animate]
operationId: animateText
summary: Animate Text
description: Programmatically generate an animated text GIF from a phrase.
parameters:
- $ref: '#/components/parameters/ApiKey'
- name: m
in: query
required: true
description: Text or phrase to animate.
schema: { type: string }
- name: style
in: query
required: false
description: Optional animation style identifier.
schema: { type: string }
responses:
'200': { $ref: '#/components/responses/SingleGifResponse' }
/v1/channels/search:
get:
tags: [Channels]
operationId: searchChannels
summary: Search Channels
description: Find GIPHY channels matching the supplied query.
parameters:
- $ref: '#/components/parameters/ApiKey'
- name: q
in: query
required: true
schema: { type: string }
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
responses:
'200':
description: Paginated list of channels.
content:
application/json:
schema:
type: object
properties:
data: { type: array, items: { $ref: '#/components/schemas/Channel' } }
pagination: { $ref: '#/components/schemas/Pagination' }
meta: { $ref: '#/components/schemas/Meta' }
/v1/randomid:
get:
tags: [Utilities]
operationId: createRandomId
summary: Create Random ID
description: Generate a unique, privacy-preserving identifier for tracking users in a session.
parameters:
- $ref: '#/components/parameters/ApiKey'
responses:
'200':
description: A new random ID.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
random_id: { type: string }
meta: { $ref: '#/components/schemas/Meta' }
/v1/gifs/search/actions:
post:
tags: [Analytics]
operationId: registerSearchAction
summary: Register Search Action
description: |
Register an action (view, click, share) on a GIF using the analytics pingback URLs
included in search responses. Endpoint is fire-and-forget; HTTP 200 indicates the
event was accepted.
parameters:
- $ref: '#/components/parameters/ApiKey'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
action_type:
type: string
enum: [SEEN, CLICK, SENT]
analytics_response_payload: { type: string }
random_id: { type: string }
ts: { type: integer, description: 'Epoch timestamp in milliseconds.' }
responses:
'200':
description: Event accepted.
/v1/gifs:
get:
tags: [GIFs]
operationId: getGifsById
summary: Get GIFs by ID
description: Fetch metadata for up to 100 GIFs at once, by comma-separated IDs.
parameters:
- $ref: '#/components/parameters/ApiKey'
- name: ids
in: query
required: true
description: Comma-separated list of GIF IDs (max 100).
schema: { type: string }
responses:
'200': { $ref: '#/components/responses/GifListResponse' }
'400': { $ref: '#/components/responses/BadRequest' }
post:
tags: [Upload]
operationId: uploadGif
summary: Upload GIF
description: |
Upload a GIF or video file to GIPHY at `upload.giphy.com/v1/gifs`. Maximum file
size is 100 MB. This operation runs against the `upload.giphy.com` host (overrides
the default server).
servers:
- url: https://upload.giphy.com
parameters:
- $ref: '#/components/parameters/ApiKey'
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required: [api_key]
properties:
api_key: { type: string }
file: { type: string, format: binary, description: 'Image or video file (≤100 MB).' }
source_image_url: { type: string, format: uri, description: 'Optionally provide a URL instead of uploading bytes.' }
username: { type: string }
tags: { type: string, description: 'Comma-separated tag list.' }
source_post_url: { type: string, format: uri }
is_hidden: { type: boolean }
responses:
'200':
description: Upload accepted, returns the new GIF identifier.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id: { type: string }
meta: { $ref: '#/components/schemas/Meta' }
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: query
name: api_key
description: API key issued via the GIPHY developer dashboard.
parameters:
ApiKey:
name: api_key
in: query
required: true
description: GIPHY API key (Beta or Production).
schema: { type: string }
Limit:
name: limit
in: query
required: false
description: Maximum number of items to return per page.
schema: { type: integer, default: 25, maximum: 50 }
Offset:
name: offset
in: query
required: false
description: Position in the result set for pagination.
schema: { type: integer, default: 0 }
Rating:
name: rating
in: query
required: false
description: Filter results by MPAA-style rating.
schema:
type: string
enum: [g, pg, pg-13, r, y]
Lang:
name: lang
in: query
required: false
description: Default language (ISO 639-1) for regional content.
schema: { type: string }
Bundle:
name: bundle
in: query
required: false
description: Reduce response payload by requesting only the rendition bundle you need.
schema:
type: string
enum: [low_bandwidth, messaging_non_clips, sticker_layering, clips_grid_picker]
RandomId:
name: random_id
in: query
required: false
description: Privacy-preserving user identifier produced by /v1/randomid.
schema: { type: string }
CountryCode:
name: country_code
in: query
required: false
description: ISO 3166-1 alpha-2 country code used to localize results.
schema: { type: string }
Weirdness:
name: weirdness
in: query
required: false
description: Translate weirdness (0 conservative ... 10 most weird).
schema: { type: integer, minimum: 0, maximum: 10 }
responses:
GifListResponse:
description: A paginated list of GIF or Sticker objects.
content:
application/json:
schema:
type: object
properties:
data: { type: array, items: { $ref: '#/components/schemas/Gif' } }
pagination: { $ref: '#/components/schemas/Pagination' }
meta: { $ref: '#/components/schemas/Meta' }
SingleGifResponse:
description: A single GIF or Sticker object.
content:
application/json:
schema:
type: object
properties:
data: { $ref: '#/components/schemas/Gif' }
meta: { $ref: '#/components/schemas/Meta' }
ClipListResponse:
description: A paginated list of Clip objects (GIFs with sound).
content:
application/json:
schema:
type: object
properties:
data: { type: array, items: { $ref: '#/components/schemas/Clip' } }
pagination: { $ref: '#/components/schemas/Pagination' }
meta: { $ref: '#/components/schemas/Meta' }
BadRequest:
description: Malformed request.
content:
application/json:
schema: { $ref: '#/components/schemas/Error' }
Unauthorized:
description: Missing or invalid API key.
content:
application/json:
schema: { $ref: '#/components/schemas/Error' }
Forbidden:
description: Access is restricted; for Clips endpoints, request access via [email protected].
content:
application/json:
schema: { $ref: '#/components/schemas/Error' }
NotFound:
description: Resource not found.
content:
application/json:
schema: { $ref: '#/components/schemas/Error' }
RateLimited:
description: API rate limit exceeded.
content:
application/json:
schema: { $ref: '#/components/schemas/Error' }
schemas:
Gif:
type: object
description: Standard GIPHY GIF object returned by most endpoints.
properties:
type: { type: string, enum: [gif, sticker, emoji], description: 'Type of media object.' }
id: { type: string, description: 'GIPHY ID for the object.' }
slug: { type: string, description: 'URL slug used in giphy.com URLs.' }
url: { type: string, format: uri, description: 'Canonical GIPHY URL.' }
bitly_gif_url: { type: string, format: uri }
bitly_url: { type: string, format: uri }
embed_url: { type: string, format: uri }
username: { type: string }
source: { type: string }
rating: { type: string, enum: [g, pg, pg-13, r, y] }
content_url: { type: string }
user: { $ref: '#/components/schemas/User' }
source_tld: { type: string }
source_post_url: { type: string, format: uri }
update_datetime: { type: string, format: date-time }
create_datetime: { type: string, format: date-time }
import_datetime: { type: string, format: date-time }
trending_datetime: { type: string, format: date-time }
images: { $ref: '#/components/schemas/Images' }
title: { type: string }
alt_text: { type: string }
is_low_contrast: { type: boolean }
analytics_response_payload: { type: string }
analytics: { $ref: '#/components/schemas/Analytics' }
Clip:
allOf:
- $ref: '#/components/schemas/Gif'
- type: object
properties:
video:
type: object
description: Video metadata for Clip objects (GIFs with sound).
properties:
duration: { type: number }
dimensions:
type: object
properties:
width: { type: integer }
height: { type: integer }
assets:
type: object
additionalProperties:
type: object
properties:
url: { type: string, format: uri }
width: { type: integer }
height: { type: integer }
captions:
type: array
items:
type: object
properties:
lang: { type: string }
srt: { type: string, format: uri }
vtt: { type: string, format: uri }
User:
type: object
description: GIPHY user / channel associated with content.
properties:
avatar_url: { type: string, format: uri }
banner_image: { type: string, format: uri }
banner_url: { type: string, format: uri }
profile_url: { type: string, format: uri }
username: { type: string }
display_name: { type: string }
description: { type: string }
instagram_url: { type: string, format: uri }
website_url: { type: string, format: uri }
is_verified: { type: boolean }
Channel:
type: object
description: GIPHY content channel.
properties:
id: { type: integer }
slug: { type: string }
url: { type: string }
display_name: { type: string }
short_display_name: { type: string }
description: { type: string }
type:
type: string
enum: [community, editorial]
content_type:
type: string
enum: [gif, sticker, mixed]
banner_image: { type: string, format: uri }
is_private: { type: boolean }
user: { $ref: '#/components/schemas/User' }
featured_gif: { $ref: '#/components/schemas/Gif' }
ancestors:
type: array
items: { $ref: '#/components/schemas/Channel' }
tags:
type: array
items:
type: object
properties:
channel: { type: integer }
rank: { type: integer }
tag: { type: string }
Category:
type: object
description: A GIF category.
properties:
name: { type: string }
name_encoded: { type: string }
subcategories:
type: array
items:
type: object
properties:
name: { type: string }
name_encoded: { type: string }
gif: { $ref: '#/components/schemas/Gif' }
Images:
type: object
description: Map of rendition keys to rendition metadata. Available renditions include fixed_height, fixed_height_still, fixed_height_downsampled, fixed_height_small, fixed_height_small_still, fixed_width, fixed_width_still, fixed_width_downsampled, fixed_width_small, fixed_width_small_still, downsized, downsized_still, downsized_large, downsized_medium, downsized_small, original, original_still, looping, preview, preview_gif.
additionalProperties:
$ref: '#/components/schemas/Rendition'
Rendition:
type: object
properties:
url: { type: string, format: uri }
width: { type: string, description: 'Width in pixels (string in API).' }
height: { type: string, description: 'Height in pixels (string in API).' }
size: { type: string, description: 'File size in bytes (string in API).' }
mp4: { type: string, format: uri }
mp4_size: { type: string }
webp: { type: string, format: uri }
webp_size: { type: string }
frames: { type: string }
hash: { type: string }
Pagination:
type: object
properties:
offset: { type: integer }
total_count: { type: integer }
count: { type: integer }
Meta:
type: object
properties:
msg: { type: string }
status: { type: integer }
response_id: { type: string }
Analytics:
type: object
description: Pingback URLs returned alongside each GIF for measuring user engagement.
properties:
onload:
type: object
properties:
url: { type: string, format: uri }
onclick:
type: object
properties:
url: { type: string, format: uri }
onsent:
type: object
properties:
url: { type: string, format: uri }
Error:
type: object
properties:
meta: { $ref: '#/components/schemas/Meta' }