Riffsy Developers

Request API Key

Become a Riffsy API Partner

Partners Include

Riffsy's API helps partners drive a daily use–case around visual expression in messaging, chat and community apps of all kinds.

Highlights include:

  • Search and browse for relevant GIFs by term, emoji, or entire conversations.
  • Support for 28 languages
  • Optimized for mobile to deliver GIFs that load fast and consume less bandwidth
  • Support for content–rating filters
  • Support for video (including audio)

An extended API is also available for partners with 10M+ Daily Active Users

Tags

Get a list of popular or promoted tags and categories.

https://api.riffsy.com/v1/tags?key=LIVDSRZULELA

Parameters:

Name Type Required Default Value Description
type string no featured specify a category of tags to retrieve. Possible values: "featured", "explore". Multiple types can be specified, each type separated with a comma

Examples:

https://api.riffsy.com/v1/tags?key=LIVDSRZULELA

https://api.riffsy.com/v1/tags?key=LIVDSRZULELA&type=featured,explore

Response:

{
  "tags": [
    {
      "searchterm": "hello", 
      "path": "https://api.riffsy.com/v1/search?tag=hello", 
      "image": "https://media.riffsy.com/images/6088f94e6eb5dd7584dedda0fe1e52e1/raw", 
      "name": "#hello"
    }, 
    {
      "searchterm": "mindblown", 
      "path": "https://api.riffsy.com/v1/search?tag=mindblown", 
      "image": "https://media.riffsy.com/images/5f99e73ac47aaa89758e32b57a26d418/raw", 
      "name": "#mindblown"
    }, 
    {
      "searchterm": "omg", 
      "path": "https://api.riffsy.com/v1/search?tag=omg", 
      "image": "https://media.riffsy.com/images/e7071c31f53d2b2b411346a7f4838cfc/raw", 
      "name": "#omg"
    }, 
    {
      "searchterm": "bye", 
      "path": "https://api.riffsy.com/v1/search?tag=bye", 
      "image": "https://media.riffsy.com/images/6627db4ce5f307a5647b6445d63e542a/raw", 
      "name": "#bye"
    }
  ]
}

Video Clips

Get popular video clips

https://api.riffsy.com/v1/music?key=LIVDSRZULELA

Parameters:

Name Type Required Default Value Description
key string yes n/a client key for privileged API access
limit integer no 20 fetch up to a specified number of results (max: 50).
pos string no n/a get results starting at position "value". Use a non-null "next" value returned by API results to get the next set of results. pos is not an index and may be an integer or float

Examples:

https://api.riffsy.com/v1/music?key=LIVDSRZULELA&limit=10

Response:

GIFs

Get GIFs by their IDs.

https://api.riffsy.com/v1/gifs?ids=<ids>&key=LIVDSRZULELA

Parameters:

Name Type Required Default Value Description
ids string yes n/a a comma separated list of GIF IDs (limit: 10, higher with a partner key)
key string yes n/a client key for privileged API access

Examples:

https://api.riffsy.com/v1/gifs?key=LIVDSRZULELA&ids=5079878,4900007

Response:

Response Objects

Example

{
  "next": "30",
  "results": [
    {
      "id": "3576876",
      "title": "zach galifianakis",
      "url": "http://gif.co/paFI.gif",
      "created": 1417282444.029527,
      "hasaudio": false,
      "tags": [
        "thumbsup",
        "zachgalifianakis"
      ],
      "composite":{
        "video": "https://media.riffsy.com/videos/c9125209120e9d2c263f4a0eedb6bacb/mp4",
        "preview": "https://media.riffsy.com/images/364c6c1c7de3d4a9c01e4fb1d3ad5c06/raw"
      },
      "media": [
        {
          "tinygif": {
            "url": "https://media.riffsy.com/images/a6fff4732f3047440b491cde9ea63409/raw",
            "preview": "https://media.riffsy.com/images/d7f352f4c609ebb30b96d157a850bb9d/raw"
          }
          "gif": {
            "url": "https://media.riffsy.com/images/65b3da99d3626f98e84f014f01d62b31/raw",
            "preview": "https://media.riffsy.com/images/364c6c1c7de3d4a9c01e4fb1d3ad5c06/raw"
          },
          "mp4": {
            "url": "https://media.riffsy.com/videos/c9125209120e9d2c263f4a0eedb6bacb/mp4",
            "preview": "https://media.riffsy.com/images/364c6c1c7de3d4a9c01e4fb1d3ad5c06/raw"
          },
          "webm": {
            "url": "https://media.riffsy.com/videos/e43301b7f50bdbe1fb3c8f43b76264fb/webm",
            "preview": "https://media.riffsy.com/images/364c6c1c7de3d4a9c01e4fb1d3ad5c06/raw"
          }
        }
      ]
    }
    ...
  ]
}

Response

Key Value Type Description
next string a position identifier to use with the next API query to retrieve the next set of results, or null if there are no further results.
results Result[] an array of Result objects, containing GIF and video data

Result

Key Value Type Description
composite {
"video": string,
"preview": string
}
for GIF Stories, a composite video containing all of the individual GIFs in this object in MP4 format, otherwise null.
created timestamp a unix timestamp representing when this post was created.
hasaudio boolean true if this post contains audio (only video formats support audio, the gif image file format can not contain audio information).
id string Riffsy result identifier
media MediaCollection a collection of Media objects
tags string[] an array of tags for the riffpost
title string the title of the riffpost.
url string a short URL to view the riffpost on riffsy.com.

MediaCollection

Key Value Type Description
gif Media a large-format GIF, good for desktop use
mp4 Media a video version of the GIF
tinygif Media a small-format GIF, good for mobile use
webm Media a video version of the GIF

Media

Key Value Type Description
preview string a url to a preview image of the media source
url string a url to the media source

Errors

Key Value Type Description
code number an optional numeric code
error string a string message describing the error

Examples

{
  "code": 1,
  "error": "Localtime is not a valid naive time (%h:%m)."
}
{
  "code": 5,
  "error": "Valid id is required."
}
{
  "error": "no result"
}

Attribution

All content retrieved from the Riffsy API must be properly attributed by including the phrase "Powered by Riffsy" where API results are used. You can use either text or one of our "Powered by Riffsy" logos.

Get Attribution Logos

API Key

Our docs include a restricted, rate limited example key (LIVDSRZULELA) for you to use while evaluating our API. Before deploying your integration to production, please request your own API key (it's free) so that we can deliver an optimized experience for your audience.

Get API Key

Extended API

We also offer a range of advanced API endpoints and drop-in SDKs that provide a full-set of auto-suggestion, advanced search, and personalization features. We are available to work closely with out partners to help achieve their goals around 5/7 DAU, retention, or engagement by providing a visual expression language used daily.

Request Documentation Access