-
Notifications
You must be signed in to change notification settings - Fork 3
Requesting media links
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:
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.
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.
$ 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'
$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
}
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);
}
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:
See this page to get your access tokens.
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.