uploading videos - Redgifs/api GitHub Wiki (2024)

This page describes how to upload videos and make them publicly available.

1. Get a user token. It lets your app work with the API on behalf of a user.
2. Get a file upload token.
3. Upload the file.
4. Checking file status. Wait until the uploaded file is ready for encoding.
5. Submit that file for encoding. Basic parameters need to be specified, like if you want to keep the sound.
6. Wait until the video is ready.
7. 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/uploadHost: api.redgifs.comAuthorization: Bearer your.user.tokenContent-Type: application/json{"md5": "31b99657f864ffea90f84620b056bac3"}

Example successful response:

HTTP/1.1 200 OKContent-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?signatureHost: redgifs-filedrop.s3.amazonaws.comContent-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/statusHost: api.redgifs.comAuthorization: Bearer your.user.token

In 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 OKContent-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/submitHost: api.redgifs.comAuthorization: Bearer your.user.tokenContent-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 OKContent-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/whimsicalpointlessmussaurusHost: api.redgifs.comAuthorization: Bearer your.user.token

You should specify the gif id assigned in the previous step. The response looks like this:

HTTP/1.1 200 OKContent-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