Skip to content

Uploading files

Justin Forest edited this page Mar 23, 2022 · 6 revisions

To upload a file to RedGIFs servers, you need to follow this procedure:

  1. Request an upload ticket.
  2. Find the upload URL in the response, upload your file to that URL.
  3. Wait until the ticket is ready: the file is received and analyzed.
  4. Use the ticket id to create gifs or galleries.

Example session

(1) Request an upload ticket

This does not require any parameters, but if you provide us an MD5 hash of the file contents, we can look up if the file was uploaded before, and save you some time and traffic. (This is handy, for example, if there was an error processing your previous request, and you need to retry, but don't want to upload the file again.)

NB: this requires an OAuth token.

POST /v2/upload
Host: api.redgifs.com
Authorization: Bearer my_secret_oauth_token

md5=387ca7bca898bb33afbac190a4227464

Response if the file was not found:

HTTP/1.1 200 OK
Content-Type: text/javascript
Cache-Control: no-cache

{
 "id": "17fb67b0f3e-0970-476c-062e-8a1db3f7fda9",
 "method": "PUT",
 "url": "https://redgifs-filedrop.s3.amazonaws.com/17fb69668eb-4b9f-6cae-9193-96690489d235?some-signed-args"
}

Alternative response, meaning that the file was uploaded before and you don't need to upload it again:

HTTP/1.1 200 OK
Content-Type: text/javascript
Cache-Control: no-cache

{
 "id": "17fb67b0f3e-0970-476c-062e-8a1db3f7fda9",
 "method": null,
 "url": null
}

(2) Upload the file

Use the URL from the upload ticket to PUT the file:

PUT /17fb69668eb-4b9f-6cae-9193-96690489d235?some-signed-args
Host: redgifs-filedrop.s3.amazonaws.com
Content-Type: video/mp4

The response normally has no contents, just make sure that the status code is 200. If not, try again.

HTTP/1.1 200 OK

(3) Check ticket status

After receiving the file, we need to analyze its contents, extract metadata etc. This might take a few moments. Check ticket status this way:

GET /v2/upload/17fb69668eb-4b9f-6cae-9193-96690489d235/status
Host: api.redgifs.com

Response when the ticket is ready:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache

{
 "status": "ready"
}

Response when the file is still processing:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache

{
 "status": "processing"
}

If we failed to process the file for some reason, the status would be "failed":

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache

{
 "status": "failed",
 "error": "something went wrong"
}

So, you basically upload the file, then keep checking for its status, until it's "ready" or "failed". Please have at least 1 second delay between requests.

(4) Use the ticket

When you have an id of a ticket that is ready, you can use it to create a gif or a gallery.