API base-url
HTTP/1.1 HTTP2 https://vidup.io/api

POST and PUT parameters can be sent as either a json or text input. The appropriate content-type must be provided (e.g application/json).


Authentication

Tokens are used to authorize a request on behalf of an account. Tokens can be generated from your control panel under "Application Tokens".
Permissions are set by users, so if you are an application developer, you need to inform your users about which routes you require available for your app.

Tokens should be passed as an api_token parameter.


Status Code

Status codes follow the W3 HTTP/1.1 Status Code Definitions standards.

  • 200: Success
  • 400: Bad Request (e.g. wrong params
  • 401: Unauthorized Request, refer to Authentication
  • 50x: Internal Server Error. This should not occur, however if you see 50x errors please get in touch


Upload

Get upload instance(s)

Get a list of all the upload instances. An optional code can be passed to retrieve an upload instance.

An upload instance is removed automatically once the file upload completes.

Request

GET /api/upload/video/:code?

Parameters

Name Required Type Description Example
api_token true String User API Token example12345
code no String code is used to lookup an active upload instance 54n83nqx0q3w

Response

      
200 (OK)
Content-Type: application/json
{
  "uploads": [{
    "info": {
      "title": "Big Buck Bunny.mp4",
      "size": 135148333
    },
    "code": "54n83nqx0q3w",
    "created": "2018-05-12T00:00:00Z",
    "error": null|"an error has occured during upload",
    "url": "https://u1234.vev.io/upload/video/54n83nqx0q3w"
  },
  ...
  ],
}
    

Create an upload instance

Initialize a new upload by creating an upload instance. An upload instance is a reference you have created to store video chunks.
A successful response will include an attribute called url, refer to the "Upload to upstream" section for more details.

Request

POST /api/upload/video

Parameters

Name Required Type Description Example
api_token true String User API Token example12345
size yes Integer total size of the video file in bytes 1024
title no String title of the new video Big buck bunny
description no String description of the new video Sample video uploaded through API
folder_id no Integer a valid folder ID associated to the authorized account 144
lite no Integer video will be a lite video False
public no Boolean video will be publicly accessible True

Response

      
200 (OK)
Content-Type: application/json
{
  "upload": {
    "info": {
      "title": "Big Buck Bunny.mp4",
      "size": 135148333
    },
    "code": "54n83nqx0q3w",
    "url": "https://u1234.vev.io/upload/video/54n83nqx0q3w"
  }
}
    

Update an upload instance

Update an upload instance using an upload instance code. This entry is available until the completed call occurs.
For more information please refer to "Upload to upstream" section.

Request

PUT /api/upload/video/:code

Parameters

Name Required Type Description Example
api_token true String User API Token example12345
title no String title of the new video. Big buck bunny
description no String description of the new video Sample video uploaded through API
folder_id no Integer a valid folder ID associated to the authorized account 144
lite no Integer video will be a lite video false
public no Boolean video will be publicly accessible true

Response

      
200 (OK)
Content-Type: application/json
{
  "upload": {
    "info": {
      "title": "Big Buck Bunny.mp4",
      "size": 135148333
    },
    "code": "54n83nqx0q3w",
    "created": "2018-05-12T00:00:00Z",
    "error": null|"an error has occured during upload",
    "url": "https://u1234.vev.io/upload/video/54n83nqx0q3w"
  }
}
    

Upload to upstream

After creating a new upload instance, an upload url is provided (e.g https://u1234.vev.io/upload/video/54n83nqx0q3w). This URL is your upload endpoint.

Uploading a file requires chunking. We do not recommend using a large chunk size as it will defeat the purpose of chunking the video and may result in a reduced upload speed. An individual chunk may not exceed 200mb, this is subject to change and therefore the recommended chunk size is 10mb. A chunk must be uploaded using a POST multipart/form-data strategy.
Once all the chunk parts have uploaded successfully, a completed request must to be sent to the endpoint URL with /completed appended to the URL.

We follow FineUploader's chunking implementation, it may be helpful with further reading.

Request

POST <url>/api/upload/video/:code[/completed]

Parameters

Name Required Type Description Example
qqpartindex no Integer chunk index id 54n83nqx0q3w
qqtotalparts no String total number of chunk 54n83nqx0q3w
qqtotalfilesize no String code is used to lookup an active upload instance 54n83nqx0q3w

Response

      
200 (OK)
Content-Type: application/json
{
  "success": boolean - whether or not the chunk/request was accepted,
  "error": string - error message describing failure reason,
  "preventRetry": false|true - if set and true the upload server will reject any further attempts, a failure occurred,
  "video": object - on completion, if successful, the video object will be returned. [video.code] corresponds to the newly created video code
}
    

Pair

Pairing Access

Pairing allows for your users to stream videos from this site. Your visitors must pair their device by visiting https://vidup.io/pair to authorize their network.

To gain access to a streaming link, please follow the documentation below.

Request

GET /api/pair/:code

Parameters

Name Required Type Description Example
code yes String video code 54n83nqx0q3w

Response

      
200 (OK)
Content-Type: application/json
{
  "poster": "<poster_url>",
  "qualities": {
      "<video_quality>": "<stream_url>",
  },
  "spritesheet": "<spritesheet_url>",
  "vtt": "<vtt_url>",
  "subtitles": []
}
    

Unauthorized Response

      
400 (Bad Request)
Content-Type: application/json
{
  "code": 400,
  "message": String
}