-
Notifications
You must be signed in to change notification settings - Fork 3
Uploading videos
This page describes how to upload videos and make them publicly available.
- Get a user token. It lets your app work with the API on behalf of a user.
- Get a file upload token.
- Upload the file.
- Checking file status. Wait until the uploaded file is ready for encoding.
- Submit that file for encoding. Basic parameters need to be specified, like if you want to keep the sound.
- Wait until the video is ready.
- Share the video as you need.
We use OAuth 2 to authenticate requests. To access the API, you first need your client credentials. When you have a valid client id and secret, you can request user tokens. Then use the received access and refresh tokens like you would with any other API.
You do this by posting to /v2/upload and including the MD5 hash of the file contents. In response you get an URL to which the file needs to be sent, and an upload id which you will use to check the status of the upload. The MD5 hash is optional, but if the file was already uploaded recently, you could skip uploading it again to speed up the process.
Example request:
POST /v2/upload
Host: api.redgifs.com
Authorization: Bearer your.user.token
Content-Type: application/json
{"md5": "31b99657f864ffea90f84620b056bac3"}Example successful response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "187b426647c-3fcb-5a02-0000-50163f48047a",
"status": "waiting",
"method": "PUT",
"url": "https://redgifs-filedrop.s3.amazonaws.com/a36e4926abc3a53ad713156c3295988fbe00a98fc879f7a45c8df196c85e71c6?signature"
}If status is "ready", then we have this file already, and you don't need to upload, skip to the encoding step. Otherwise, you need to wait until the file is ready, which is described in the next step.
This step is very simple. You just send your file to the URL you received in the previous step using the specified method. Currently we only use PUT as the method. You don't need to authenticate this request.
Example request:
PUT /a36e4926abc3a53ad713156c3295988fbe00a98fc879f7a45c8df196c85e71c6?signature
Host: redgifs-filedrop.s3.amazonaws.com
Content-Type: video/mp4
...binary contents...Example using curl:
$ curl 'https://redgifs-filedrop.s3.amazonaws.com/a36e4926abc3a53ad713156c3295988fbe00a98fc879f7a45c8df196c85e71c6?signature' --upload-file source.mp4
A successful response would be a 200 with an empty body. Then you can continue checking the upload status.
After we received the file, we need to make sure that it can be processed. We need to check if it's a video or an image, if the codec is supported, etc. This usually takes a second or two, but sometimes can take more. So the app needs to wait until the file is ready. It can do this by sending a request like this:
GET /v2/upload/187b426647c-3fcb-5a02-0000-50163f48047a/status
Host: api.redgifs.com
Authorization: Bearer your.user.tokenIn this request, "187b426647c-3fcb-5a02-0000-50163f48047a" is the upload id received in the previous step. It's not the file name from the upload URL, even if it's the same.
Successful response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "187b426647c-3fcb-5a02-0000-50163f48047a",
"status": "ready"
}There can be some extra props, but what you need is status. If it contains "error", then you should tell the user to try to upload again. If it's "ready", then you're done and can continue submitting the file for encoding. If it's "waiting" or any other value, you should wait a second and ask for the status again.
Once the file is uploaded and ready for encoding, you can initiate the encoding process. This is a separate step, because sometimes apps need to submit more than one file, like when creating an image gallery, which will be documented later. So, to start the encoding process, a request like this should be sent:
POST /v2/gifs/submit
Host: api.redgifs.com
Authorization: Bearer your.user.token
Content-Type: application/json
{
"ticket": "187b426647c-3fcb-5a02-0000-50163f48047a",
"sexuality": "straight",
"keepAudio": true,
"tags": [
"Cute",
"Teen",
"Outdoor"
]
}The ticket prop is the upload id from the previous steps. You need to specify at least 3 and at most 10 valid tags from our dictionary, which is available at /v1/tags. The gif will not be publicly accessible if less than 3 tags are added. (You can add more later.)
Example successful response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "whimsicalpointlessmussaurus",
"duration": 18
}The id here (whimsicalpointlessmussaurus) is the unique gif id that should be used to check the encoding status, and to later access the encoded gif. Duration is the expected encoding time in second. With this data, the app can start waiting for the encoding to finish.
After the gif was submitted, we need to process the source file to create SD and HD versions of the video, and extract thumbnail images. This takes some time, usually under 30 seconds. The only way to know when it's done, is to poll for gif status with requests like this.
GET /v1/gifs/fetch/status/whimsicalpointlessmussaurus
Host: api.redgifs.com
Authorization: Bearer your.user.tokenYou should specify the gif id assigned in the previous step. The response looks like this:
HTTP/1.1 200 OK
Content-Type: application/json
{
"task": "encoding"
}There can be more props, for historical reasons, but the only one needed by the app is task, which can be "encoding", "error" or "complete". On error, the user needs to be told to retry. On "ready", the gif is ready to be shared. On "encoding", the app needs to wait a second and ask for status again.
Once the gif finished encoding, you can share it. The link to the gif page looks like this:
https://www.redgifs.com/watch/whimsicalpointlessmussaurus
The page also contains some schema.org metadata that can be used to create previews. If you need an embedded HTML player, the iframe URL would be:
https://www.redgifs.com/ifr/whimsicalpointlessmussaurus