Upload video via API to VOD storage

​

How is Gcore video hosting organized?

• Copy from external storage
• Upload from a local device
• Batch upload to migrate a vast number of videos from other services

​

Video upload and processing statuses

​

Priority of processing

• Global priority – Managed automatically by the system on global scale. You cannot influence on it. It depends on converter availability in the processing cluster. This ensures that even without a dedicated region (this an option for enterprises), your videos usually start processing without significant delay.
• Account priority – Applied within your account. You can control it explicitly using the priority attribute.

• Type: integer
• Range: -10 … 10
  • -10 = lowest priority (processed after others)
  • 0 = default priority
  • 10 = highest priority (processed first)

​

Copy from external storage

​

Overview

• HTTP/HTTPS public access from external video hosting services, such as Vimeo or Mux
• HTTP/HTTPS public access from S3-like storages, such as AWS or Azure
• SFTP protocol

• Good link : https://demo-files.gvideo.io/gcore.mp4 (13,8MB from S3 storage)
• Good SFTP template : sftp://login:password@domain.com/path/file.mp4
• Bad link (because of chunked HLS format): https://demo-files.gvideo.io/hls/master.m3u8

​

Example of API request

curl -L 'https://api.gcore.com/streaming/videos/' \ 
-H 'Content-Type: application/json' \ 
-H 'Authorization: APIKey 1234$0d16599c' \ 
-d '{ 
  "video": { 
    "name": "Gcore Demo", 
    "description": "Video copied from an external S3 Storage", 
    "origin_url": "https://demo-files.gvideo.io/gcore.mp4"
  } 
}

{ 
  "id": 2496039, 
  "name": "Gcore Demo", 
  "description": "Video copied from an external S3 Storage", 
  ... 
}

​

How it works

​

Upload from a local device

​

Step 1. Create a video entity and get a video identifier

curl -L 'https://api.gcore.com/streaming/videos/' \ 
-H 'Content-Type: application/json' \ 
-H 'Authorization: APIKey 1234$0d16599c' \ 
-d '{ 
  "video": { 
    "name": "Gcore Demo", 
    "description": "Uploaded via TUS session" 
  } 
}'

{ 
  "id": 2501637, 
  "name": "Gcore Demo", 
  "description": "Uploaded via TUS session", 
  "duration": null, 
  "slug": "70NbFUCZyXU2s3tY", 
  "status": "empty", 
  ... 
}  

​

Step 2. Get TUS session parameters

curl -L 'https://api.gcore.com/streaming/videos/2501637/upload' \ 
-H 'Authorization: APIKey 1234$0d16599c' 

{ 
  "servers": [ 
   { 
      "id": 561, 
      "role": "upload", 
      "hostname": "vod-uploader-ed-2.gvideo.co", 
      "active": true, 
      "ssl": true 
    }, 
    ... 
  ], 
  "token": "eyJhbGciOiJIUzI3O6kc3Og...", 
  "video": { 
    "id": 2501637, 
    "name": "Gcore Demo", 
    "description": "Uploaded via TUS session", 
    "duration": null, 
    "slug": "70NbFUCZyXU2s3tY", 
    "status": "empty", 
    ... 
   } 
}  

• servers: A list of available servers to upload the file; you can use any of them.
• token: A secret token for starting the TUS session, valid for 4 hours which is long enough because as soon as the session starts, the token is no longer needed.
• video: A copy of the main data pertaining to your video entity.

​

Step 3. Upload file via TUS chunked protocol

endpoint = "https://{hostname}/upload/" 
chunksize = 10000000 
filename = "{filename}" 
filetype = "{file_mime_type}" 
token = "{tus_token}" 
video_id = {video_id} 
client_id = {client_id} 

• The larger the size of a chunk, the faster each chunk will be uploaded using the maximum bandwidth. But in the case of failure to upload, TUS will only start uploading from the last successful chunk, which may have been some time ago. So with large sizes, the speed will be faster, but if it fails, the additional reupload time will be significant.
• With small sizes, the risk of uploading errors decreases. However, due to the features of HTTP (handshakes, etc.) for each chunk’s request, the upload speed will significantly reduce. So small chunk sizes mean a slow but reliable upload speed.

DEBUG=1 tusc -H "https://vod-uploader-ed-2.gvideo.co" -f "file_to_upload.mp4" -b "/upload/" -- -H "'Upload-Metadata: client_id $(echo <client_id> | base64 -w0),filename $(echo <filename> | base64 -w0),token $(echo <token> | base64 -w0),video_id $(echo <video_id> | base64 -w0)'"

const options = { 
  endpoint,   
  chunkSize, 
  retryDelays: [0, 1000, 3000], 
  metadata: { 
    filename: file.name, 
    filetype: file.type, 
    // must provide these 3 fields too 
    token: token, 
    video_id: videoid, 
    client_id: clientid 
  }, 
  onError(error) { 
    ... 
  }, 
  onProgress(bytesUploaded, bytesTotal) { 
    ... 
  }, 
  onShouldRetry: function (err, retryAttempt, options) { 
    // tus-js-client should retry 
    return true 
  }, 
  onSuccess() { 
    ... 
  } 
} 
 
upload = new tus.Upload(file, options) 
upload.findPreviousUploads().then((previousUploads) => { 
  askToResumeUpload(previousUploads, upload) 
 
  upload.start() 
  uploadIsRunning = true 
})  

• JS: We support 2.x version of tus-js-client, for details check out GitHub
• Android: Gcore’s open-source Kotlin demo app
• iOS: Gcore’s open-source Swift demo app
• Other implementation options can be found on the official TUS website

• HTTP 405 Method Not Allowed. Unexpected response while creating upload session; check parameters of the request.
• HTTP 429 Too Many Requests. Try to send a request later.
• HTTP 500 Internal Server Error :
  • Error: token invalid (null) – check the format of parameters, encoding in base64, separation of parameters and key-value pairs.
  • Error: token invalid (eyJhbGciOi…) – the same as above.
  • Error: token video (12345) does not match this video (23456)
  • Error: token client (123) does not match this client (234)

​

AI extra processing

​

Batch upload to migrate a vast number of videos from other services

• Google Drive
• Amazon S3 (step 1: Setting permissions for website access, step 2: Get the list of objects)
• Vimeo
• Mux
• Dropbox
• General SFTP or S3 storage with HTTP file access