Upload and initiate transcoding

Uploads video file and triggers the background video transcoding process post-upload.

POST /v4/upload?postprocess=transcode

Adaptive video streaming over HTTP is key to have videos load fast any where on any device. Filerobot can transcode your videos in multiple target resolutions and generate the playlist (also called manifest) for your DASH or HLS video player to consume. Before leveraging Filerobot's video transcoding capabilities, we recommend getting a basic understand of the technologies involved: adaptive streaming, DASH and HLS.

Video transcoding must be enabled on your Filerobot token, please contact us for activating it.

API Permissions

FILE_UPLOAD

Upload Parameters

Parameter Type Default Description
postprocess string - required Sets the postprocess operation:
transcode The video is transcoded after uploading.
folder string /videos optional Specifies the directory to upload the file into. If it does not exist, it will be created
Example: /path/to/folder

Video Settings

Parameter Type Default Description
video-resolution string auto optional Specifies the resolutions the video needs to be transcoded to:
auto Automatic quality setting based on input file resolution
mobile Optimize for mobile device delivery
tablet Optimize for mobile device delivery with a higher resolution
desktop Optimize for desktop device delivery
hq Optimize for highest quality
video-protocols string hls optional Specifies the streaming protocol setting
hls Sets the protocol to HLS (HTTP Live Streaming)
dash Sets the protocol to MPEG-DASH.
hls,dash Transcodes to support both protocols

How does it work?

Obtaining transcoded chunks and the corresponding playlist file (.mpd for DASH and .m3u8 for HLS) for the video player to consume is achieved in 3 simple steps:

  1. Upload origin video file: high resolution video file is uploaded into Filerobot via API, Asset Hub or Widget
  2. Transcode into lower resolution chunks: Filerobot backend will generate transcoded chunks and store them in your storage container
  3. Playlist generation: Filerobot generates the playlist file, stores it into your storage container and adds link to it to in the meta data of the original video file

Steps 2 and 3 are transparent for you, you just need to call the standard Upload API by adding the below documented parameters to your request JSON.

Supported formats and codecs

formats mp4, avi, mkv, webm
video codecs XviD, H.263, AVC (H.264), HEVC (H.265), MPEG-1, MPEG-2, MPEG-4, WMV2, Theora, VP8, VP9
audio codecs AAC, AC3, MP3, PCM, FLAC, Vorbis, Opus

Try it out

You can upload video files for transcoding using the 2 following methods:

Method 1 - multipart/form-data request

Request

curl --request POST \ 
--url 'https://api.filerobot.com/{token}/v4/upload?folder=/{folder_path}&postprocess=transcode' \ 
--header 'content-type: multipart/form-data' \ 
--header 'X-Filerobot-Key: {filerobot_api_key}' \ 
--form file=@{video_file_path.ext} \ 
--form 'info[file]={"video-resolutions":"auto", "video-protocols":"hls|dash|hls,dash"}'
Parameter Description
filerobot_api_key A Filerobot key (see API Authentification)
video_file_path.ext The path to the local video file

Response

{
  "status": "success", 
  "file": {
    "uuid": "86314cb0-115b-5d3f-a34d-c77b78550000", 
    "name": "11_mp4_h264_mp3.m4v", 
    "size": {
      "bytes": 10740270, 
      "pretty": "10.24 MB"
    }, 
    "type": "video/mp4", 
    "url": {
      "public": "https://fldytuwm.airstore.io/mango/11_mp4_h264_mp3.m4v", 
      "permalink": "https://fldytuwm.api.airstore.io/v4/get/86314cb0-115b-5d3f-a34d-c77b78550000", 
      "cdn": "", 
      "path": "/mango/11_mp4_h264_mp3.m4v"
    }, 
    "hash": {
      "sha1": "95c9ec91a7fa765401a5b4656bb79e0819c5ad96", 
      "blur_hash": null
    }, 
    "created_at": "2021-03-19T11:57:43Z", 
    "modified_at": "2021-03-19T11:57:43Z", 
    "overwrite": false, 
    "folder": {
      "uuid": "b9fd0305-afd2-52be-8a31-c5ddaef8d9c4", 
      "name": "/mango"
    }, 
    "info": {
      "playlists": [
        "https://fldytuwm.filerobot.com/yviDp3wK_11_mp4_h264_mp3/hls/video.m3u8"
      ], 
      "progress": "https://api.filerobot.com/fldytuwm/v4/transcode/MTUyLjIyOC4xNjAuMzY6ODczMQ__4f95351d-33fb-46d8-8d1c-cf105d880410", 
      "transcode_uuid": "4f95351d-33fb-46d8-8d1c-cf105d880410", 
      "video_w": 1920, 
      "video_h": 1080, 
      "video_duration": 20.02, 
      "video_bit_rate": 4121956
    }, 
    "meta": {}
  }, 
  "info": {
    "version": 2.16, 
    "trace": "t9pQ-gpu-test-001", 
    "uniq_id": "a2208ba3e0654aa3a608e0db6fe60766", 
    "project_uuid": "1e007984-ab9a-46f1-8abc-f736e128794d", 
    "company_uuid": "c543bc43-0000-1111-2222-b5293daf15f4", 
    "uploaded_files": 1, 
    "files_count": 1, 
    "init_db": "atom008:45"
  }
}

Method 2 - URL(s) of remotely hosted file(s)

Request

curl --request POST \ 
--url 'http://api.filerobot.com/{token}/v4/upload?folder={folder_path}&postprocess=transcode)' \ 
--header 'content-type: application/json' \ 
--header 'X-Filerobot-Key: {filerobot_api_key}' \ 
 --data '{
 "files_urls": [
  {"url": "{video_url_path.ext}", "info":{"video-resolutions":"auto", "video-protocols":"hls,dash"}}
 ]
}'
Parameter Description
filerobot_api_key A Filerobot key (see API Authentification)
video_file_path.ext The URL to the video file

Response

{
  "status": "success", 
  "files": [
    {
      "uuid": "26535010-3367-59da-b325-898df8d5002e", 
      "name": "demo.mp4", 
      "size": {
        "bytes": 1035166, 
        "pretty": "1010.9 KB"
      }, 
      "type": "video/mp4", 
      "url": {
        "public": "https://fldytuwm.airstore.io/mango/demo.mp4", 
        "permalink": "https://fldytuwm.api.airstore.io/v4/get/26535010-3367-59da-b325-898df8d5002e", 
        "cdn": "", 
        "path": "/mango/demo.mp4"
      }, 
      "hash": {
        "sha1": "3354b0dff8e02eadaa26d3b5a413de087853c621", 
        "blur_hash": null
      }, 
      "created_at": "2021-03-19T11:48:52Z", 
      "modified_at": "2021-03-19T11:48:52Z", 
      "overwrite": false, 
      "folder": {
        "uuid": "b9fd0305-afd2-52be-8a31-c5ddaef8d9c4", 
        "name": "/mango"
      }, 
      "info": {
        "video-resolutions": "auto", 
        "video-protocols": "hls", 
        "video-name": "dalis", 
        "playlists": [
          "https://fldytuwm.filerobot.com/dalis/hls/video.m3u8"
        ], 
        "progress": "https://api.filerobot.com/fldytuwm/v4/transcode/MTUyLjIyOC4xNjAuMzY6ODczMQ__a928e6a9-75c4-4e01-b316-1d8b8108b618", 
        "transcode_uuid": "a928e6a9-75c4-4e01-b316-1d8b8108b618", 
        "video_w": 1280, 
        "video_h": 720, 
        "video_duration": 42.34, 
        "video_bit_rate": 2940
      }, 
      "meta": {}
    }, 
    {
      "uuid": "d599f852-9a1b-5255-8133-333321a50008", 
      "name": "demo2.mp4", 
      "size": {
        "bytes": 54625140, 
        "pretty": "52.09 MB"
      }, 
      "type": "video/mp4", 
      "url": {
        "public": "https://fldytuwm.airstore.io/mango/demo2.mp4", 
        "permalink": "https://fldytuwm.api.airstore.io/v4/get/d599f852-9a1b-5255-8133-333321a50008", 
        "cdn": "", 
        "path": "/mango/demo2.mp4"
      }, 
      "hash": {
        "sha1": "031b5ff7d26d6de20d1af37b8fc3987348ff2711", 
        "blur_hash": null
      }, 
      "created_at": "2021-03-19T11:48:53Z", 
      "modified_at": "2021-03-19T11:48:53Z", 
      "overwrite": false, 
      "folder": {
        "uuid": "b9fd0305-afd2-52be-8a31-c5ddaef8d9c4", 
        "name": "/mango"
      }, 
      "info": {
        "video-resolutions": "auto", 
        "video-protocols": "hls", 
        "playlists": [
          "https://fldytuwm.filerobot.com/quG1BMo1_demo2/hls/video-sample.m3u8", 
          "https://fldytuwm.filerobot.com/quG1BMo1_demo2/hls/video.m3u8"
        ], 
        "progress": "https://api.filerobot.com/fldytuwm/v4/transcode/MTUyLjIyOC4xNjAuMzY6ODczMQ__ead14798-d4cb-421b-b027-a36c244506ad", 
        "transcode_uuid": "ead14798-d4cb-421b-b027-a36c244506ad", 
        "video_w": 1280, 
        "video_h": 720, 
        "video_duration": 42.34, 
        "video_bit_rate": 10298981
      }, 
      "meta": {}
    }
  ], 
  "info": {
    "version": 2.16, 
    "trace": "3hm-gpu-test-001", 
    "uniq_id": "cfda38f7c6b14808b742bb83752e86d5", 
    "project_uuid": "1e007984-ab9a-46f1-8abc-f736e128794d", 
    "company_uuid": "c543bc43-0000-1111-2222-b5293daf15f4", 
    "uploaded_files": 2, 
    "files_count": 2, 
    "init_db": "atom006:150"
  }
}