Skip to content

Requesting media links

Jump to bottom
Justin Forest edited this page Aug 2, 2022 · 28 revisions

URLs of media files are protected against hotlinking. They are tied to the requestor IP address and user agent. If the link is requested from a different IP address or a different user agent, it will return a 403 instead of the file. This page describes how to request valid links on behalf of a different user.

Table of Contents:

How it works

Since links have a short life time (30 to 60 minutes, can change), you most likely need fresh links every time you display a file. You get them from the /v2/gifs/{id} API endpoint, like this (only the relevant part of the response is shown, the rest is omitted):

$ curl 'https://api.redgifs.com/v2/gifs/extralargedefinitivexenopus'
{
  "urls": {
      "hd": "https://thumbs4.redgifs.com/ExtralargeDefinitiveXenopus.mp4?signature=...",
      "poster": "https://thumbs4.redgifs.com/ExtralargeDefinitiveXenopus-poster.jpg?signature=...",
      "sd": "https://thumbs4.redgifs.com/ExtralargeDefinitiveXenopus-mobile.mp4?signature=...",
      "thumbnail": "https://thumbs4.redgifs.com/ExtralargeDefinitiveXenopus-mobile.jpg?signature=...",
      "vthumbnail": "https://thumbs4.redgifs.com/ExtralargeDefinitiveXenopus-mobile.mp4?signature=..."
  }
}

The links will be only accessible by the same application using the same IP address. You can't share those links with anyone. If you have to do that, like if you're showing videos in your mobile application or website, but the API client runs on a separate server, you need to specify your client's IP address and user agent, like this:

$ curl 'https://api.redgifs.com/v2/gifs/extralargedefinitivexenopus?user-addr=1.2.3.4&user-agent=Apollo/1.0'

In this case, link signatures will be valid for the user.

Examples

HTTP example

GET /v2/gifs/gummymemorableant?user-addr=203.0.113.1&user-agent=wget/1.0
Host: api.redgifs.com
Authorization: Bearer your.access.token

Note that the gif id must be in lower case.

Command line example

$ curl 'https://api.redgifs.com/v2/gifs/gummymemorableant?user-addr=203.0.113.1&user-agent=wget/1.0' -H 'Authorization: Bearer your.access.token'

PHP example

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.redgifs.com/v2/gifs/gummymemorableant', [
  'query' => [
    'user-addr' => '203.0.113.1',
    'user-agent' => 'wget/1.0',
  ],
  'headers' => [
    'Authorization' => 'Bearer your.access.token',
  ],
]);

if ($response->getStatusCode() === 200) {
  $encoded = (string)$response->getBody();
  $body = json_decode($encoded, true, \JSON_THROW_ON_ERROR);
  var_dump($body['gif']['urls']);
} else {
  // Retry on 5xx, contact us on 401/403
}

JavaScript example

const accessToken = 'your.access.token';

const params = new URLSearchParams({
  'user-addr': '203.0.113.1',
  'user-agent': 'wget/1.0',
});

const response = await fetch('https://api.redgifs.com/v2/gifs/gummymemorableant?' + params, {
  headers: {
    'Authorization': 'Bearer ' + accessToken,
  }
});

if (response.status === 200) {
  const data = await response.json();
  console.log(data.gif.urls);
}

Requesting multiple gifs

Often applications need to display a batch of videos, on the home page or in the user's home feed for example. That can include tens or hundreds of gifs. Requesting a hundred of gifs with individual requests would make a bad user experience, also that would hammer the API server with requests.

We have a separate API endpoint that can provide info on up to 100 gifs in one request:

https://api.redgifs.com/v2/gifs
  ?ids=foo,bar,baz
  &user-addr=1.2.3.4
  &user-agent=acme-v2

The ids parameter is a comma separated list of gif ids (nb: ids are lowercase).

The request method must be GET. A complete curl example:

Access tokens

See this page to get your access tokens.

Troubleshooting

I cannot request a token, the API says the secret is bad.

Please see if you have any special characters in your secret. If you do, make sure you url-encode the secret properly when you send it.

I get a 403 when accessing the files.

Make sure you use the same IP address and user agent for requesting the media file that you used when accessing the API to find the links. If you need to request the files from a different IP address or agent, make sure you provide their exact values with the user-addr and user-agent query params when requesting the links. Lazy loading can make the user experience better.

Make sure you don't mix IPv4 and IPv6 by accident. To verify your IP address an user agent, use this API endpoint.

Clone this wiki locally