GIFs

These routes search the instance's GIF provider. They need a session token. A bot token or OAuth2 bearer token gets 403 ACCESS_DENIED.

Get instance discovery has a gif object that says whether the instance has a GIF provider.

Provider headers

Every response from these routes has these headers when the instance has a GIF provider.

Field	Type	Description
X-Fluxer-GIF-Provider	string	The provider ID, such as klipy
X-Fluxer-GIF-Provider-Display-Name	string	The provider name to show
X-Fluxer-GIF-Provider-Attribution-Required	string	true when you must show the provider's attribution

GIF object

A GIF object is one result from the provider. Save meme from URL saves one to your collection.

Structure

Field	Type	Description
id1	string	The provider's identifier of the GIF
slug1	string	The canonical slug of the GIF
provider	string	The name of the provider (1-32 characters)
title	string	The title of the GIF
url	string	The provider page URL
src2	string	The direct media URL
proxy_src2	string	The Media Proxy URL
width2	integer	The width in pixels
height2	integer	The height in pixels
media	map[string, GIF media format object]	The formats keyed by format name
placeholder?3	?string	The thumbhash placeholder

¹ Both have the same value

² From the webm entry of media when there is one, and from the first entry otherwise

³ Always absent from the GIFs these routes return

Example

{
  "id": "goat-plays-banjo-4",
  "slug": "goat-plays-banjo-4",
  "provider": "klipy",
  "title": "Goat Plays Banjo",
  "url": "https://klipy.com/gifs/goat-plays-banjo-4",
  "src": "https://static.example.com/goat-plays-banjo.webm",
  "proxy_src": "https://media.example.com/external/9f21c0/goat-plays-banjo.webm",
  "width": 220,
  "height": 229,
  "media": {
    "webm": {
      "src": "https://static.example.com/goat-plays-banjo.webm",
      "proxy_src": "https://media.example.com/external/9f21c0/goat-plays-banjo.webm",
      "width": 220,
      "height": 229
    },
    "tinygif": {
      "src": "https://static.example.com/goat-plays-banjo-tiny.gif",
      "proxy_src": "https://media.example.com/external/4ad117/goat-plays-banjo-tiny.gif",
      "width": 137,
      "height": 90
    }
  }
}

GIF category object

A category is a search term with a preview GIF. Send name as the q of Search GIFs to get its GIFs.

Structure

Field	Type	Description
name	string	The search term, translated for the locale
src1	string	The direct media URL of the preview
proxy_src1	string	The Media Proxy URL of the preview
gif	?GIF object	The preview GIF

¹ The empty string when gif is null

Deprecated vendor paths

These paths work like their successors and add Deprecation, Link and Warning headers.

Method	Deprecated path	Successor
GET	/v1/tenor/search	Search GIFs
GET	/v1/tenor/featured	Get featured GIFs
GET	/v1/tenor/trending-gifs	Get trending GIFs
GET	/v1/tenor/suggest	Get GIF search suggestions
POST	/v1/tenor/register-share	Register a GIF share
GET	/v1/klipy/search	Search GIFs
GET	/v1/klipy/featured	Get featured GIFs
GET	/v1/klipy/trending-gifs	Get trending GIFs
GET	/v1/klipy/suggest	Get GIF search suggestions
POST	/v1/klipy/register-share	Register a GIF share

Search GIFs

GET/v1/gifs/search

Returns at most 50 GIF objects matching a search term.

Query parameters

Field	Type	Description
q	string	The search term (1-256 characters)
locale?	string	A supported locale, default en-US

Response

Status	Body	Condition
200	array[GIF object]	The matches
403	error response	FEATURE_TEMPORARILY_DISABLED when the instance has no GIF provider
503	error response	SERVICE_UNAVAILABLE when the provider fails or times out

The rate limit is 40 requests per 10 seconds, on the gif:search bucket.

Get featured GIFs

GET/v1/gifs/featured

Returns a featured GIF and a list of category terms.

Query parameters

Field	Type	Description
locale?	string	A supported locale, default en-US

Response body

Field	Type	Description
gifs	array[GIF object]	The featured GIF (0 or 1 items)
categories	array[GIF category object]	The categories (at most 50)

Response

Status	Body	Condition
200	response body	The featured GIFs and categories
403	error response	FEATURE_TEMPORARILY_DISABLED when the instance has no GIF provider
503	error response	SERVICE_UNAVAILABLE when the provider fails or times out

The rate limit is 40 requests per 10 seconds, on the gif:featured bucket.

Get trending GIFs

GET/v1/gifs/trending

Returns at most 50 trending GIF objects.

Query parameters

Field	Type	Description
locale?	string	A supported locale, default en-US

Response

Status	Body	Condition
200	array[GIF object]	The trending GIFs
403	error response	FEATURE_TEMPORARILY_DISABLED when the instance has no GIF provider
503	error response	SERVICE_UNAVAILABLE when the provider fails or times out

The rate limit is 40 requests per 10 seconds, on the gif:trending bucket.

Get GIF search suggestions

GET/v1/gifs/suggest

Returns search term suggestions for a partial query.

Query parameters

Field	Type	Description
q	string	The partial search term (1-256 characters)
locale?	string	A supported locale, default en-US

Response

Status	Body	Condition
200	array[string]	The suggestions
403	error response	FEATURE_TEMPORARILY_DISABLED when the instance has no GIF provider
503	error response	SERVICE_UNAVAILABLE when the provider fails or times out

The rate limit is 40 requests per 10 seconds, on the gif:suggest bucket.

Register a GIF share

POST/v1/gifs/register-share

Tells the provider that a user sent one of its GIFs. Fluxer stores nothing.

JSON body

Field	Type	Description
id	string	The id of the shared GIF object (1-300 characters)
q?	?string	The search term that found the GIF (0-256 characters)
locale?	string	A supported locale, default en-US

Response

Status	Body	Condition
204	empty	The provider accepted the registration
403	error response	FEATURE_TEMPORARILY_DISABLED when the instance has no GIF provider
503	error response	SERVICE_UNAVAILABLE when the provider fails or times out

The rate limit is 60 requests per 10 seconds, on the gif:register_share bucket.