API#

API Instance#

class redgifs.API(session=None, *, proxy=None, proxy_auth=None)#

The API Instance to get information from the RedGifs API.

Note

If you are using this library in an asynchronous code, you should refer the Async API section.

Parameters:

  • session (Optional[requests.Session]) – A session object that can be provided to do the requests. If not provided, a new session object is created.

  • proxy (Optional[str]) – A valid proxy URL.

  • proxy_auth (Optional[ProxyAuth]) – The proxy auth to provide if the proxy requires it.

login()#

A method to login to RedGifs with a temporary token. You must use this method after initialising the API class for this library to function properly.

Return type:

API - The properly initialised API class.

get_tags()#

Get all available RedGifs Tags.

Return type:

List[Dict[str, Union[str, int]]]

get_gif(id)#

Get details of a single GIF using its ID.

If the URL is https://redgifs.com/watch/abcxyz then the ID is abcxyz.

Parameters:

id (str) – The ID of the GIF.

Return type:

GIF - The GIF’s info.

Get the top 10 trending GIFs on RedGifs.

Return type:

List[GIF]

Get the top 10 trending images on RedGifs.

Return type:

List[Image]

Get the trending searches on RedGifs.

Returns:

A list of dicts containing the tag name and count:

[
    {
        "name": "r/CaughtPublic",
        "count": 2034
    },
    {
        "name": "Vintage",
        "count": 19051
    },
    ...
]

Return type:

List[Dict[str, Union[str, int]]]

get_top_this_week(count=30, page=1, type=MediaType.GIF)#

Get media from “Top This Week” section.

Parameters:

  • count (int) – The number of items to return.

  • page (int) – The items to return from given page number.

  • type (MediaType) – The type of media to return.

Return type:

SearchResult - Top this week results.

fetch_tag_suggestions(query)#

Get tag suggestions from RedGifs.

Note

It’s advised to use Tags.search() to prevent multiple API calls to redgifs.com.

Parameters:

query (str) – The tag name to look for.

Return type:

List[TagSuggestion] - A list of TagSuggestion with tag name and count.

search(search_text, *, order=Order.TRENDING, count=40, page=1)#

Search for GIFs.

Parameters:

  • search_text (Union[str, List[str]]) – The type of GIFs to search for. Can be a string or a list of strings.

  • order (Optional[Order]) – The order of the GIFs to return.

  • count (Optional[int]) – The amount of GIFs to return.

  • page (Optional[int]) – The page number of the GIFs to return.

Return type:

SearchResult - The search result.

search_gif(search_text, *, order=Order.TRENDING, count=40, page=1)#

Search for GIFs.

Parameters:

  • search_text (Union[str, List[str]]) – The type of GIFs to search for. Can be a string or a list of strings.

  • order (Optional[Order]) – The order of the GIFs to return.

  • count (Optional[int]) – The amount of GIFs to return.

  • page (Optional[int]) – The page number of the GIFs to return.

Return type:

SearchResult - The search result.

search_creators(*, page=1, order=Order.LATEST, verified=False, tags=None)#

Search for some RedGifs Creators.

Parameters:

  • page (Optional[int]) – The result in page number to return.

  • order (Optional[Order]) – The order of the creators to return.

  • verified (Optional[bool]) – Wheather to only return verified creators.

  • tags (Optional[List[str]]) – A list of tags to look for. Narrows down the results to creators that have contents with the given tags.

Return type:

CreatorsResult - The search result.

search_creator(username, *, page=1, count=80, order=Order.LATEST, type=MediaType.GIF)#

Search for a single RedGifs creator/user by username.

Parameters:

  • username (str) – The username of the creator/user.

  • page (int) – The current page number of the creator/user’s profile.

  • count (int) – The total amount of GIFs to return.

  • order (Order) – The order to return creator/user’s GIFs.

  • type (MediaType) – Whether to return image or GIF results. By default returns GIFs.

Return type:

CreatorResult - The creator/user searched for.

search_user(username, *, page=1, count=80, order=Order.LATEST, type=MediaType.GIF)#

Search for a single RedGifs creator/user by username.

Parameters:

  • username (str) – The username of the creator/user.

  • page (int) – The current page number of the creator/user’s profile.

  • count (int) – The total amount of GIFs to return.

  • order (Order) – The order to return creator/user’s GIFs.

  • type (MediaType) – Whether to return image or GIF results. By default returns GIFs.

Return type:

CreatorResult - The creator/user searched for.

get_user(username)#

Get details of a user on RedGifs.

Parameters:

username (str) – The username of the user.

Return type:

User - The user’s details

search_image(search_text, *, order=Order.TRENDING, count=40, page=1)#

Search for images.

Parameters:

  • search_text (str) – The images to search for. Can be a string or an instance of Tags.

  • order (Optional[Order]) – The order of the images to return.

  • count (Optional[int]) – The amount of images to return.

  • page (Optional[int]) – The page number of the images to return.

Return type:

SearchResult - The search result.

download(url, fp)#

A friendly method to download a RedGifs media.

Example:

api = redgifs.API()
api.login()
hd_url = api.search("query").gifs[0].urls.hd
api.download(hd_url, "video.mp4")

Note

You should use this method to download any media from RedGifs because RedGifs does validation on User-Agents and other params. If you try to download it by using any other means, it will return 403 error.

Parameters:

  • url (str) – A valid RedGifs URL.

  • fp (Union[io.BufferedIOBase, os.PathLike]) – The file-like object to save this asset to or the filename to use. If a filename is passed then a file is created with that filename and used instead.

search_niches(query, *, order=NicheOrder.BEST_MATCH, count=40, page=1)#

Search for niches.

Parameters:

  • query (str) – The niches to search for.

  • order (Optional[NicheOrder]) – The order of the niches to return.

  • count (Optional[int]) – The amount of images to return.

  • page (Optional[int]) – The page number of the images to return.

Return type:

NicheResult - The search result.

get_niche(niche_id, *, order=NicheGifOrder.TRENDING, count=40, page=1)#

Search for a single niche’s GIFs

Parameters:

  • niche_id (str) – The ID of the niche. If the URL is https://redgifs.com/niches/abcxyz then the ID is abcxyz.

  • order (Optional[NicheGifOrder]) – The order of the GIFs to return.

  • count (Optional[int]) – The amount of GIFs to return.

  • page (Optional[int]) – The page number of the GIFs to return.

Return type:

SearchResult - The search result.

close()#

Closes the API session.

Async API#

Same as API but for usage in async context.

class redgifs.aio.API(session=None, *, proxy=None, proxy_auth=None)#

The API Instance to get information from the RedGifs API.

Parameters:

  • session (Optional[aiohttp.ClientSession]) – An aiohttp.ClientSession object that can be provided to do the requests. If not provided, a new session object is created.

  • proxy (Optional[str]) – A valid proxy URL.

  • proxy_auth (Optional[ProxyAuth]) – The proxy auth to provide if the proxy requires it.

async login()#

A method to login to RedGifs with a temporary token. You must use this method after initialising the API class for this library to function properly.

Return type:

API - The properly initialised API class.

async get_tags()#

Get all available RedGifs Tags.

Return type:

List[Dict[str, Union[str, int]]]

async get_gif(id)#

Get details of a single GIF using its ID.

If the URL is https://redgifs.com/watch/abcxyz then the ID is abcxyz.

Parameters:

id (str) – The ID of the GIF.

Return type:

GIF - The GIF’s info.

Get the top 10 trending GIFs on RedGifs.

Return type:

List[Image]

Get the top 10 trending images on RedGifs.

Return type:

List[Image]

Get the trending searches on RedGifs.

Returns:

A list of dicts containing the tag name and count:

[
    {
        "name": "r/CaughtPublic",
        "count": 2034
    },
    {
        "name": "Vintage",
        "count": 19051
    },
    ...
]

Return type:

List[Dict[str, Union[str, int]]]

async get_top_this_week(count=30, page=1, type=MediaType.GIF)#

Get media from “Top This Week” section.

Parameters:

  • count (int) – The number of items to return.

  • page (int) – The items to return from given page number.

  • type (MediaType) – The type of media to return.

Return type:

SearchResult - Top this week results.

async fetch_tag_suggestions(query)#

Get tag suggestions from RedGifs.

Note

It’s advised to use Tags.search() to prevent multiple API calls to redgifs.com.

Parameters:

query (str) – The tag name to look for.

Return type:

List[TagSuggestion] - A list of TagSuggestion with tag name and count.

async search(search_text, *, order=Order.TRENDING, count=40, page=1)#

Search for GIFs.

Parameters:

  • search_text (Union[str, List[str]]) – The type of GIFs to search for. Can be a string or a list of strings.

  • order (Optional[Order]) – The order of the GIFs to return.

  • count (Optional[int]) – The amount of GIFs to return.

  • page (Optional[int]) – The page number of the GIFs to return.

Return type:

SearchResult - The search result.

async search_gif(search_text, *, order=Order.TRENDING, count=40, page=1)#

Search for GIFs.

Parameters:

  • search_text (Union[str, List[str]]) – The type of GIFs to search for. Can be a string or a list of strings.

  • order (Optional[Order]) – The order of the GIFs to return.

  • count (Optional[int]) – The amount of GIFs to return.

  • page (Optional[int]) – The page number of the GIFs to return.

Return type:

SearchResult - The search result.

async search_creators(*, page=1, order=Order.LATEST, verified=False, tags=None)#

Search for some RedGifs Creators.

Parameters:

  • page (Optional[int]) – The result in page number to return.

  • order (Optional[Order]) – The order of the creators to return.

  • verified (Optional[bool]) – Wheather to only return verified creators.

  • tags (Optional[List[str]]) – A list of tags to look for. Narrows down the results to creators that have contents with the given tags.

Return type:

CreatorsResult - The search result.

async search_creator(username, *, page=1, count=80, order=Order.LATEST, type=MediaType.GIF)#

Search for a single RedGifs creator/user by username.

Parameters:

  • username (str) – The username of the creator/user.

  • page (int) – The current page number of the creator/user’s profile.

  • count (int) – The total amount of GIFs to return.

  • order (Order) – The order to return creator/user’s GIFs.

  • type (MediaType) – Whether to return image or GIF results. By default returns GIFs.

Return type:

CreatorResult - The creator/user searched for.

async search_user(username, *, page=1, count=80, order=Order.LATEST, type=MediaType.GIF)#

Search for a single RedGifs creator/user by username.

Parameters:

  • username (str) – The username of the creator/user.

  • page (int) – The current page number of the creator/user’s profile.

  • count (int) – The total amount of GIFs to return.

  • order (Order) – The order to return creator/user’s GIFs.

  • type (MediaType) – Whether to return image or GIF results. By default returns GIFs.

Return type:

CreatorResult - The creator/user searched for.

async get_user(username)#

Get details of a user on RedGifs.

Parameters:

username (str) – The username of the user.

Return type:

User - The user’s details

async search_image(search_text, *, order=Order.TRENDING, count=40, page=1)#

Search for images.

Parameters:

  • search_text (str) – The images to search for. Can be a string or an instance of Tags.

  • order (Optional[Order]) – The order of the images to return.

  • count (Optional[int]) – The amount of images to return.

  • page (Optional[int]) – The page number of the images to return.

Return type:

SearchResult - The search result.

async download(url, fp)#

A friendly method to download a RedGifs media.

Example:

from redgifs.aio import API

api = API()
await api.login()
hd_url = await api.search("query").gifs[0].urls.hd
await api.download(hd_url, "video.mp4")

Note

You should use this method to download any media from RedGifs because RedGifs does validation on User-Agents and other params. If you try to download it by using any other means, it will return a 403 error.

Parameters:

  • url (str) – A valid RedGifs URL.

  • fp (Union[io.BufferedIOBase, os.PathLike]) – The file-like object to save this asset to or the filename to use. If a filename is passed then a file is created with that filename and used instead.

async search_niches(query, *, order=NicheOrder.BEST_MATCH, count=40, page=1)#

Search for niches.

Parameters:

  • query (str) – The niches to search for.

  • order (Optional[NicheOrder]) – The order of the niches to return.

  • count (Optional[int]) – The amount of images to return.

  • page (Optional[int]) – The page number of the images to return.

Return type:

NicheResult - The search result.

async get_niche(niche_id, *, order=NicheGifOrder.TRENDING, count=40, page=1)#

Search for a single niche’s GIFs

Parameters:

  • niche_id (str) – The ID of the niche. If the URL is https://redgifs.com/niches/abcxyz then the ID is abcxyz.

  • order (Optional[NicheGifOrder]) – The order of the GIFs to return.

  • count (Optional[int]) – The amount of GIFs to return.

  • page (Optional[int]) – The page number of the GIFs to return.

Return type:

SearchResult - The search result.

async close()#

Closes the API session.

Tags#

A utility class for all things related to RedGifs tags.

class redgifs.Tags#
search(tag)#

Search for a specific RedGifs tag.

Note

This method is synchronous, a.k.a “blocking”, when used alone.

Parameters:

tag (str) – The tag name to search.

Return type:

List[str] - A list of tag names that are similar.

random(count=1)#

Search for random RedGifs tags.

Parameters:

count (Optional[int]) – The amount of tags to return. Defaults to 1.

Returns:

A single random tag if count is 1, otherwise a list of random tags.

Return type:

str or List[str]

Proxy Auth#

A utility class to provide proxy authorization.

class redgifs.ProxyAuth(username, password)#
username: str

The username.

password: str

The password.

Models#

Models are classes that are received from Redgifs and are not meant to be created by the user of the library.

class redgifs.models.URL#

The different types of URLs.

Warning

sd, hd, poster, thumbnail, and vthumbnail leaks your IP address in the URL. If you want to display the URLs to the end user consider using web_url or embed_url instead.

sd#

The sd URL of the media.

Type:

Optional[str]

hd#

The hd URL of the media.

Type:

Optional[str]

poster#

The poster URL of the media.

Type:

Optional[str]

thumbnail#

The thumbnail URL of the media.

Type:

Optional[str]

vthumbnail#

The vthumbnail URL of the media.

Type:

Optional[str]

web_url#

The website URL of the media.

Type:

str

file_url#

The file URL of the media.

Type:

Optional[str]

embed_url#

The embed URL of the media. This can be used to load the media without any restrictions.

Type:

Optional[str]

class redgifs.models.GIF#

The GIF returned from RedGifs.

id#

The GIF’s ID.

Type:

str

create_date#

The date when the GIF is published.

Type:

Optional[datetime.datetime]

has_audio#

Wheather the GIF has sound.

Type:

bool

width#

The GIF’s width.

Type:

int

height#

The GIF’s height.

Type:

int

likes#

The amount of likes for the GIF.

Type:

int

tags#

A list of tags for the GIF.

Type:

List[str]

verified#

Wheather the publisher of the GIF is a verified creator.

Type:

bool

views#

The amount of views for the GIF.

Type:

Optional[int]

duration#

The GIF’s duration in seconds.

Type:

float

published#

Wheather the GIF is published.

Type:

bool

urls#

The different types of URLs for the GIF.

Type:

URL

username#

The username of the publisher.

Type:

str

type#
Type:

int

avg_color#
Type:

str

class redgifs.models.TagSuggestion#

The tag suggestion results.

name#

The tag name.

Type:

str

count#

The number of GIFs with this tag.

Type:

int

class redgifs.models.Image#

The image returned from RedGifs.

id#

The image ID.

Type:

str

create_date#

The date when the image is published.

Type:

Optional[datetime.datetime]

width#

The image width.

Type:

int

height#

The image height.

Type:

int

likes#

The amount of likes the image has.

Type:

int

tags#

A list of tags for the GIF.

Type:

List[str]

verified#

Wheather the publisher of the image is a verified creator.

Type:

bool

views#

The amount of views the image has.

Type:

Optional[int]

published#

Wheather the image is published.

Type:

bool

urls#

The different types of URLs for the image.

Type:

URL

username#

The username of the publisher.

Type:

str

type#
Type:

int

avg_color#
Type:

str

class redgifs.models.User#

The user’s information returned from RedGifs.

creation_time#

The user’s account creation time.

Type:

Optional[datetime.datetime]

description#

The user’s description on their profile.

Type:

Optional[str]

followers#

The user’s amount of followers.

Type:

int

following#

The user’s amount of following users.

Type:

int

gifs#

The user’s total amount of GIFs published.

Type:

int

name#

The user’s name.

Type:

Optional[str]

profile_image_url#

The user’s profile image URL.

Type:

Optional[str]

profile_url#

The user’s “profile URL”. It is a URL that is seen on the profile set by the user. This is NOT the user’s URL on redgifs.com, see User.url for that.

Type:

Optional[str]

published_collections#

The user’s amount of published collections.

Type:

Optional[int]

published_gifs#

The user’s amount of published GIFs.

Type:

int

status#

The user’s status.

Type:

Optional[str]

subscription#
Type:

int

url#

The user’s URL on redgifs.com.

Type:

str

username#

The user’s username.

Type:

str

verified#

Wheather the user is a verified creator.

Type:

bool

views#

The user’s total amount of views of all the GIFs published.

Type:

int

poster#

The user’s poster URL.

Type:

Optional[str]

preview#

The user’s preview URL.

Type:

Optional[str]

thumbnail#

The user’s thumbnail URL.

Type:

Optional[str]

The linked websites on the user’s profile.

Type:

Optional[List[Dict[str, str]]]

class redgifs.models.SearchResult#

The result you have searched. This is returned in search().

searched_for#

The result of what you have searched for. This may differ from what you have provided for query in search().

Type:

str

page#

The current page number.

Type:

int

pages#

The total number of pages for the query.

Type:

int

total#

The total number of GIFs for the query.

Type:

int

gifs#

The GIFs which was searched for.

Type:

Optional[List[GIF]]

images#

The images which was searched for.

Type:

Optional[List[Image]]

users#
Type:

List[User]

tags#

The tags related to the GIFs and search query.

Type:

List[str]

class redgifs.models.CreatorsResult#

The creator results searched for.

items#

The list of creators.

Type:

List[User]

page#

The current page number.

Type:

int

pages#

The total number of pages available.

Type:

int

total#
Type:

int

class redgifs.models.CreatorResult#

The creator result searched for.

creator#

The creator/user details.

Type:

User

page#

The current page number.

Type:

int

pages#

The total number of pages available.

Type:

int

total#

The total number of GIFs this creator/user has created.

Type:

int

gifs#

The GIFs uploaded by this creator.

Type:

List[GIF]

images#

The images uploaded by this creator.

Type:

List[Image]

Enums#

class redgifs.Order(value)#

An enum representing the order of the results.

BEST = 'trending'#
LATEST = 'latest'#
NEW = 'latest'#
RECENT = 'latest'#
SCORE = 'score'#
TOP = 'top'#
TOP28 = 'top28'#
TOP7 = 'top7'#
TRENDING = 'trending'#
class redgifs.MediaType(value)#

An enum representing the media type of the results.

GIF = 'g'#
IMAGE = 'i'#

Exceptions#

exception redgifs.RedGifsError#

Base class for all redgifs errors.

exception redgifs.InvalidTag(tag)#

Exception raised when no match was found for a tag.

tag#

The tag that was searched for.

Type:

str

exception redgifs.HTTPException(response, json)#

Exception raised when an HTTP Exception occurs.

response#

The response of the failed HTTP request. It may be either requests.Response or aiohttp.ClientResponse.

Type:

Union[requests.Response, aiohttp.ClientResponse]

status#

The status code of the HTTP request.

Type:

int

error#

The original error message from RedGifs.

Type:

str