cURL
PHP
Java
Node.JS
C#

General Notes

  • To use the Qencode API, you must first Create an Account.
  • Use api.qencode.com for all API methods, unless explicitly stated otherwise.
  • All API methods accept POST params as application/x-www-form-urlencoded and return JSON.

Getting Session Token

/v1/access_token

To get started, first access the Qencode API by acquiring a session token. You will pass this token as a param when you use the create_task method described below.

ARGUMENTS

api_key

required

An API access key assigned to each Project in your Qencode Account.

RETURNS

Session token.

IMPORTANT: To build a secure solution we strongly recommend that you do NOT to call this method directly from any client application as you will expose your api key publicly. We recommend you first obtain a session token from your server and then pass to the client app.

Request Example

curl https://api.qencode.com/v1/access_token \
   -d api_key=5a2a846a26ace

Replace the value below with your API key. An API key can be found for each Project in your account on qencode.com.

$apiKey = 'abcdefgh';
$q = new QencodeApiClient($apiKey);

Replace the value below with your API key. An API key can be found for each Project in your account on qencode.com.

const apiKey = "abcdefgh";
const qencodeApiClient = new QencodeApiClient(apiKey);

Replace the value below with your API key. An API key can be found for each Project in your account on qencode.com.

String apiKey = "your_api_key";
QencodeApiClient client = new QencodeApiClient(apiKey);

Replace the value below with your API key. An API key can be found for each Project in your account on qencode.com.

var apiKey = "your_api_key";
var q = new QencodeApiClient(apiKey);

Response example

{
  “token” : “1357924680”,
  “expire” : “2017-12-31 23:59:59”
}

Creating a Task

/v1/create_task

Creates a transcoding job and returns it's token, which is needed to start transcoding jobs.

ARGUMENTS

token

required

Session token returned with /v1/access_token method

RETURNS

task_token

The transcoding task token (Job ID).

upload_url

An endpoint to uploading a file directly to Qencode servers using the tus.io protocol.

Request example

curl https://api.qencode.com/v1/create_task \
        -d token=76682314a86ed377730873394f8172f2
$task = $q->createTask();
let task = qencodeApiClient.CreateTask();
TranscodingTask task = client.CreateTask();
var task = q.CreateTask();

Response example

{
    "error": 0, 
    "upload_url": "https://storage.qencode.com/v1/upload_file", 
    "task_token": "471272a512d76c22665db9dcee893409"
}

Starting a Preset Job

/v1/start_encode

Starts a transcoding job based on your selected presets. This method can use an external URL or an uploaded file for the input.

Preset settings are managed in a Transcoding Profile UI in your account at Qencode portal. You also need to provide a Transcoding Profile ID as an input for this method - it is displayed in a Transcoding Profile UI:

Transcoding Profile ID

ARGUMENTS

task_token

required

The session token created for this task.
See /v1/create_task method)

uri | stitch

required

Depending on the job, you must specify uri or stitch param.

The uri is used to define URI for a single video, for both video URLs and IDs returned using the upload_file method.

The stitch param used to stich multiple input videos to create a single output. This should be a json-list of URLs or video-objects. When using the object form, you can specify the start_time and duration attributes for each input video to clip needed segments for stiching.

Example

[
 "https://your-server.com/video1.mp4", 
 "https://your-server.com/video2.mkv",
 {
    "url":"https://your-server.com/video3.mp4", 
    "start_time":"100.0", 
    "duration":"60.0"
 }
]
The same video URL can be specified several times in the stitch array, meaning you can stitch several different clips from the same video. To save your bandwidth, we will download the original video only once.

profiles

required

Comma-separated list of Transcoding Profile IDs.

To receive multiple outputs based on your presets, you may specify multiple Transcoding Profiles.

transfer_method

optional

Transfer Method ID.
Specify a preset Transfer Method as the destination for transcoded output. Your Transfer Methods can be managed in the UI under Projects.

If you don't specify a Transfer Method, we will store your videos on our servers for up to 24 hours.

payload

optional

Any string with length of 1000 characters (max).
It might become handy if you need to pass your website's ID or any JSON object.

start_time

optional

Specifies the time (in seconds) from where to begin transcoding your input file. Used for video clips.

duration

optional

Specifies how much of the video to transcode (in seconds) after start_time. Used for video clips.

output_path_variables

optional

JSON-encoded string containing a dictionary (key-value pairs) of params for video or image output path/directory.
This refers to the Output Path values specified in the transcoding profile for output video or thumbnail output settings. It may contain placeholders defined in curly braces, e.g. {myfilename} or {video_id}. When generating an Output Path, placeholders will be substituted with the actual values provided in output_path_variables dictionary.

Example

Output path for video setting:
output/mp4/{scene_id}/1080/video.mp4

output_path_variables:
{
    "scene_id": "12345"
}

Resulting video path:
/output/mp4/12345/1080/video.mp4
Please note, that {uuid} and {index} values are generated by transcoding system though if specified in output_path_variables it will override the system's values.

RETURNS

status_url

A URL used to get the status of a transcoding task.
After task is launched, the https://api.qencode.com/v1/status endpoint is always available, however it returns a limited attributes. To get additional status attributes (like percent of completion) please refer to the /v1/status method.

Request Examples

Transcoding a single video specified by a url using settings from two transcoding profiles:

curl https://api.qencode.com/v1/start_encode \
        -d task_token=63adfb01d408081b10440682f3a64 \
        -d uri="https://your-server.com/test_mini.mp4" \
        -d start_time=10 \
        -d duration=20 \
        -d profiles=5a2a846a26e88,5a2a846a28604 \
        -d transfer_method=5aa2875489681 \
        -d payload="12345" \
        -d output_path_variables='{"category":"test_videos","video_name":"12345"}'

Transcoding a video previously uploaded with TUS protocol:

curl https://api.qencode.com/v1/start_encode \
        -d task_token=63adfb01d408081b10440682f3a64 \
        -d uri="tus:d408081b10440682f3a64b01d4" \
        -d profiles=5a2a846a26e88

Launching a stitch job:

curl https://api.qencode.com/v1/start_encode \
        -d task_token=63adfb01d408081b10440682f3a64 \
        -d stitch='["https://your-server.com/video1.mp4", "https://your-server.com/video2.mkv"]' \
        -d profiles=5a2a846a26e88

Transcoding a single video specified by a url using settings from two transcoding profiles:

$video_url = 'https://your-server.com/test_mini.mp4';
//replace with your profile IDs 
$transcodingProfiles = array('5a2a846a26e88', '5a2a846a28604'); 
//replace with your transfer method ID
$transferMethodId = '5aa2875489681';
$payload = '12345';
$task->start_time = 10.0;
$task->duration = 20.0;
$task->start($transcodingProfiles, $video_url, $transferMethodId, $payload);

Transcoding a single video specified by a url using settings from two transcoding profiles:

const videoUrl = "https://your-server.com/test_mini.mp4";
//replace with your profile IDs 
const transcodingProfiles = ["5a2a846a26e88", "5a2a846a28604"]; 
//replace with your transfer method ID
const transferMethod = "5aa2875489681";
const payload = "12345";
const outputPathVariables = null;
task.StartTime = 10.0;
task.Duration = 20.0;
task.Start(transcodingProfiles, videoUrl, transferMethod, payload, outputPathVariables);

Transcoding a single video specified by a url using settings from two transcoding profiles:

String videoUrl = "https://your-server.com/test_mini.mp4";
//replace with your profile IDs 
String[] transcodingProfiles = new String[] { "5a2a846a26e88", "5a2a846a28604" };
//replace with your transfer method ID
String transferMethod = "5aa2875489681";
String payload = "12345";
HashMap vars = new HashMap();
vars.put("filename", "mytestfilename.mp4");

TranscodingTask task = client.CreateTask();
task.setUri(videoUrl);
task.setTranscodingProfiles(String.join(",", transcodingProfiles);
task.setStartTime(10.0);
task.setDuration(20.0);
task.setOutputPathVariables(vars);
task.setPayload(payload);
task.Start();

Transcoding a single video specified by a url using settings from two transcoding profiles:

var videoUrl = "https://your-server.com/test_mini.mp4";
//replace with your profile IDs 
var transcodingProfiles = new string[] { "5a2a846a26e88", "5a2a846a28604" };
//replace with your transfer method ID
var transferMethod = "5aa2875489681";
var payload = "12345";
task.StartTime = 10.0;
task.Duration = 20.0;
var started = task.Start(transcodingProfiles, videoUrl, transferMethod, payload);
Console.WriteLine("Status URL: " + started.status_url);

Response Example

{
 "error": 0, 
 "status_url": "https://api.qencode.com/v1/status" 
}

Starting a Custom Job

/v1/start_encode2

Starts a transcoding job with fully customizable settings. This method can use a URL or an uploaded file for the input.

ARGUMENTS

task_token

required

The session token created for this task.
See /v1/create_task method)

query

required

JSON object containing instructions for the transcoding job. Description and examples of query properties below.

payload

optional

Any string with length of 1000 characters (max).
It might become handy if you need to pass your website's ID or any JSON object.

RETURNS

status_url

URL to get transcoding task status.
Right after task is launched it's always https://api.qencode.com/v1/status. This endpoint is always available yet returns a limited set of task status attributes. To get extended status attributes, like percent of completion, please refer to /v1/status method


Query object description

ATTRIBUTES

source | stitch

required

Either uri or stitch param should be specified.
The uri is responsible for defining a single video's URI, whether it's a video URL or ID returned with upload_file method.
Use the stitch param in order to combine several input videos into a single one. Stitch should be a json-list of URLs or video-objects. When using object form you can specify start_time and duration attributes.

Example

[
  "https://your-server.com/video1.mp4", 
  "https://your-server.com/video2.mkv",
  {
     "url":"https://your-server.com/video3.mp4", 
     "start_time":"100.0", 
     "duration":"60.0"
  }
 ]
Same video URL can be specified several times in stitch array (e.g. to stitch different clips from the same video). In this case service is smart to download original video only once.

format

required

A list of objects, each describing params for a single output video stream (MP4, WEBM, HLS or MPEG-DASH). See format object attributes description below.

callback_url

optional

URL of an endpoint on your server to handle task callbacks.
See Receiving Callbacks.


Format object description

ATTRIBUTES

output

required

Output video format. Currently supported values are mp4, webm, advanced_hls, advanced_dash.
The thumbnail & thumbnails values are used for creation of thumbnail images. See the Create thumbnails section for more details.

destination

optional

Describes an endpoint output video and output path.
See destination object attributes description below.
If you don't specify destination, your video will be available to download from our servers during 24 hours.

file_extension

optional

Output video file extension (only for MP4 or WEBM format, defaults to '.mp4').

size

optional

Output video frame size in pixels ("width"x"height"). Defaults to original frame size.

rotate

optional

Rotate video through specified degrees value. Possible values are 90, 180, 270.

framerate

optional

Output video frame rate. Defaults to original frame rate.
If you don't specify framerate for a stitch job, output framerate will be equal to framerate of the first video in a batch.

bitrate

optional

Output video stream bitrate in kylobytes.
Don't specify bitrate unless you want constant bitrate for the video. To create variable bitrate use quality param.

quality

optional

Output video stream quality (also known as "Constant rate factor").
Use this param to produce optimized videos with variable bitrate. For H.264 the range is 0-51: where 0 is lossless and 51 is worst possible. A lower value is a higher quality and a subjectively sane range is 18-28. Consider 18 to be visually lossless or nearly so: it should look the same or nearly the same as the input but it isn't technically lossless.

pix_format

optional

Output video pixel format. Possible values are yuv420p, yuv422p, yuvj420p, yuvj422p. Defaults to yuv420p.

profile

optional

x264 video codec settings profile. Possible values are high, main, baseline. Defaults to main.

video_codec

optional

Output stream video codec. Defaults to libx264. Possible values are: libx264, libx265, libvpx, libvpx-vp9.

video_codec_parameters

optional

Output stream video codec parameters.
See video_codec_parameters object attributes description below.

audio_codec

optional

Output file audio codec name. Possible values are: aac, vorbis. Defaults to aac.

audio_bitrate

optional

Output file audio bitrate value in kylobytes. Defaults to 64.

audio_sample_rate

optional

Output file audio sample rate. Defaults to 44100.

audio_channels_number

optional

Output file audio channels number. Default value is 2.

segment_duration

optional

Segment duration to split media (in seconds). Defaults to 8.

keyframe

optional

Keyframe period (in frames). Defaults to 90.

start_time

optional

Specifies the start time (in seconds) in input video to begin transcoding from.

duration

optional

Specifies duration of the video fragment (in seconds) to be transcoded.

two_pass

optional

Use two-pass encoding to achieve exact bitrate value for output. Please note, two-pass encoding is almost twice slower than one-pass coding. The price is also increased twice.

stream

optional

Contains a list of elements each describing a single view stream for adaptive streaming format. Use stream objects for HLS or MPEG-DASH outputs.

width

optional

Thumbnail image width in pixels. Used with output: thumbnail or output: thumbnails.

height

optional

Thumbnail image height in pixels. Used with output: thumbnail or output: thumbnails.

time

optional

Moment in video (% from video duration) to create thumbnail at. Used with output: thumbnail.

interval

optional

Interval in seconds between thumbnail images.
Used with output: thumbnails.

Destination object description

ATTRIBUTES

url

required

Specifies the output video url. E.g. s3://example.com/bucket/video.mp4

key

required

Your access key for S3 bucket or FTP or Aspera username.

secret

required

Your access secret for S3 bucket or FTP or Aspera password.

permissions

optional

S3 only. Specifies object access permissions. For AWS possible values are: private, public-read, authenticated-read, bucket-owner-read and others described in Access Control List Overview.
Default value is "private".
Specify "public-read" value in order to make output video publicly accessible.

storage_class

optional

AWS S3 only. Specifies storage class for the output.
You can specify REDUCED_REDUNDANCY value in order to lower your storage costs for noncritical, reproducible data.
See Reduced redundancy storage description.

is_passive

optional

FTP only. Possible values are true or false.

use_tls

optional

FTP only. Possible values are true or false.

tcp_port

optional

Aspera only. TCP port for Aspera.

udp_port

optional

Aspera only. UDP port for Aspera.

video_codec_parameters object description

ATTRIBUTES

vprofile

optional

x264 video codec settings profile. Possible values are high, main, baseline. Defaults to main.

level

optional

Set of constraints that indicate a degree of required decoder performance for a profile. Consists from two digits. Possible values are: 30, 31, 40, 41, 42.

coder

optional

Context-Adaptive Binary Arithmetic Coding (CABAC) is the default entropy encoder used by x264. Possible values are 1 and 0. Defaults to 1.

flags2

optional

Allows B-frames to be kept as references. Possible values are +bpyramid, +wpred, +mixed_refs, +dct8×8, -fastpskip/+fastpskip, +aud. Defaults to None.

partitions

optional

One of x264's most useful features is the ability to choose among many combinations of inter and intra partitions. Possible values are +partp8x8, +partp4x4, +partb8x8, +parti8x8, +parti4x4. Defaults to None.

directpred

optional

Defines motion detection type: 0 -- none, 1 -- spatial, 2 -- temporal, 3 -- auto. Defaults to 1.

me_method

optional

Motion Estimation method used in encoding. Possible values are epzs, hex, umh, full. Defaults to None.

subq

optional

Sets sub pel motion estimation quality.

trellis

optional

Sets rate-distortion optimal quantization.

refs

optional

Number of reference frames each P-frame can use. The range is from 0-16.

cmp

optional

Sets full pel me compare function.

me_range

optional

Sets limit motion vectors range (1023 for DivX player).

sc_threshold

optional

Sets scene change threshold.

i_qfactor

optional

Sets QP factor between P and I frames.

b_strategy

optional

Sets strategy to choose between I/P/B-frames.

qcomp

optional

Sets video quantizer scale compression (VBR). It is used as a constant in the ratecontrol equation. Recommended range for default rc_eq: 0.0-1.0.

qmin

optional

Sets min video quantizer scale (VBR). Must be included between -1 and 69, default value is 2.

qmax

optional

Sets max video quantizer scale (VBR). Must be included between -1 and 1024, default value is 31.

qdiff

optional

Sets max difference between the quantizer scale (VBR).

max_rate

optional

Sets max bitrate tolerance (in bits/s). Requires bufsize to be set.

min_rate

optional

Sets min bitrate tolerance (in bits/s). Most useful in setting up a CBR encode. It is of little use elsewise.

sws_flags

optional

Sets the scaler flags. This is also used to set the scaling algorithm. Only a single algorithm should be selected. Default value is ‘bicubic’.

preset

optional

Specifies the preset for matching stream(s).

flags

optional

Set generic flags. (Possible values: ‘mv4’, ‘qpel’, ‘loop’, ‘qscale’, ‘pass1’, ‘pass2’, ‘gray’, ‘emu_edge’, ‘psnr’, ‘truncated’, ‘ildct’, ‘low_delay’, ‘global_header’, ‘bitexact’, ‘aic’, ‘cbp’, ‘qprd’, ‘ilme’, ‘cgop’).

rc_lookahead

optional

Sets number of frames to look ahead for frametype and ratecontrol.

Request Examples

Transcoding a single video specified by a url into mp4 single output and storing it to AWS S3 bucket:

curl https://api.qencode.com/v1/start_encode2 \
     -d task_token=b49e034d198262f1d5d15ed9f3cb8 \
     -d payload="12345" \
     -d query='{"query": {
     "source": "https://your-server.com/test_mini.mp4",
     "format": [
       {
         "output": "mp4",
         "destination": {
           "url":"s3://s3-us-east-1.amazonaws.com/yourbucket/output.mp4",
           "key":"abcde12345",
           "secret":"abcde12345",
           "permissions": "public-read"
         },
         "framerate": "29.97",
         "keyframe": "25",
         "file_extension": "mp4",
         "size": "360x240",
         "video_codec_parameters": {
           "vprofile": "baseline",
           "level": "31",
           "coder": "0",
           "flags2": "-bpyramid+fastpskip-dct8x8",
           "partitions": "+parti8x8+parti4x4+partp8x8+partb8x8",
           "directpred": "2",
           "me_method": "hex"
         },
         "start_time": "10",
         "duration": "20",
         "audio_bitrate": "64",
         "audio_sample_rate": "44100",
         "audio_channels_number": "2"
       }
     ]
   }
 }'

Transcoding a single video specified by a url into HLS output and storing it to AWS S3 bucket:

// Replace this with your API key
$apiKey = 'abcdefgh';
$video_url = 'https://your-server.com/1.mp4';
$q = new QencodeApiClient($apiKey);
$task = $q->createTask();

$params = new CustomTranscodingParams();
$params->source = $video_url;

$format = new Format();
$format->destination = new Destination();
$format->destination->url = "s3://s3-your-region.amazonaws.com/your-bucket/folder";
$format->destination->key = "your-access-key";
$format->destination->secret = "your-secret-key";
$format->destination->permissions = "public-read";
$format->segment_duration = 4;
$format->output = "advanced_hls";

$stream = new Stream();
$stream->size = "640x480";
$stream->audio_bitrate = 128;
$vcodec_params = new Libx264_VideoCodecParameters();
$vcodec_params->vprofile = "baseline";
$vcodec_params->level = 31;
$vcodec_params->coder = 0;
$vcodec_params->flags2 = "-bpyramid+fastpskip-dct8x8";
$vcodec_params->partitions = "+parti8x8+parti4x4+partp8x8+partb8x8";
$vcodec_params->directpred = 2;

$stream->video_codec_parameters = $vcodec_params;

$format->stream = [$stream];
$params->format = [$format];

$task->startCustom($params);

Transcoding a single video specified by a url into HLS output and storing it to AWS S3 bucket:

// Replace this with your API key
const apiKey = "5abcde84aa29f";
const s3_path = "s3://s3-yourRegion.amazonaws.com/bucketname";
const s3_key = "youS3Key";
const s3_secret = "yourS3secret";
const videoUrl = "https://your-server.com/1.mp4";
const payload = null;

let transcodingParams = {};
transcodingParams.source = videoUrl;

let format = {};
format.destination = {};
format.destination.url = s3_path;
format.destination.key = s3_key;
format.destination.secret = s3_secret;
format.output = "advanced_hls";

let stream = {};
stream.size = "640x480";
stream.audio_bitrate = 128;

let vcodec_params = {};
vcodec_params.vprofile = "baseline";
vcodec_params.level = 31;
vcodec_params.coder = 0;
vcodec_params.flags2 = "-bpyramid+fastpskip-dct8x8";
vcodec_params.partitions = "+parti8x8+parti4x4+partp8x8+partb8x8";
vcodec_params.directpred = 2;

stream.video_codec_parameters = vcodec_params;

format.stream = [];
format.stream.push(stream);

transcodingParams.format = [];
transcodingParams.format.push(format);

const qencodeApiClient = new QencodeApiClient(apiKey);
let task = qencodeApiClient.CreateTask();
task.StartCustom(transcodingParams, payload);

Transcoding a single video specified by a url into HLS output and storing it to AWS S3 bucket:

// Replace this with your API key
String apiKey = "5abcde84aa29f";
String s3Path = "s3://s3-yourRegion.amazonaws.com/bucketname";
String s3Key = "youS3Key";
String s3Secret = "yourS3secret";
String videoUrl = "https://your-server.com/1.mp4";
QencodeApiClient client = new QencodeApiClient(apiKey);
TranscodingTask task = client.CreateTask();

CustomTranscodingParams transcodingParams = new CustomTranscodingParams();
transcodingParams.setSource(videoUrl);
Destination destination = new Destination();
Format format = new Format();
destination.setUrl(s3Path);
destination.setKey(s3Key);
destination.setSecret(s3Secret);
format.setDestination(destination);
format.setOutput("advanced_hls");

Stream stream = new Stream();
stream.setSize("640x480");
stream.setAudioBitrate(128);

Libx264_VideoCodecParameters vcodecParams = new Libx264_VideoCodecParameters();
vcodecParams.setVprofile("baseline");
vcodecParams.setLevel(31);
vcodecParams.setCoder(0);
vcodecParams.setFlags2("-bpyramid+fastpskip-dct8x8");vcodecParams.setPartitions("+parti8x8+parti4x4+partp8x8+partb8x8");
vcodecParams.setDirectpred(2);
stream.setVideoCodecParameters(vcodecParams);
format.getStream().add(stream);

transcodingParams.getFormat().add(format);
task.startCustom(transcodingParams);

Transcoding a single video specified by a url into HLS output and storing it to AWS S3 bucket:

// Replace this with your API key
var apiKey = "5abcde84aa29f";
var videoUrl = "https://your-server.com/1.mp4";
var s3_path = "s3://s3-yourRegion.amazonaws.com/bucketname";
var s3_key = "youS3Key";
var s3_secret = "yourS3secret";

var transcodingParams = new CustomTranscodingParams();
transcodingParams.source = videoUrl;
var format = new Format();
format.destination = new Destination();
format.destination.url = s3_path;
format.destination.key = s3_key;
format.destination.secret = s3_secret;
format.output = "advanced_hls";

var stream = new Stream();
stream.size = "640x480";
stream.audio_bitrate = 128;

var vcodec_params = new Libx264_VideoCodecParameters();
vcodec_params.vprofile = "baseline";
vcodec_params.level = 31;
vcodec_params.coder = 0;
vcodec_params.flags2 = "-bpyramid+fastpskip-dct8x8";
vcodec_params.partitions = "+parti8x8+parti4x4+partp8x8+partb8x8";
vcodec_params.directpred = 2;
stream.video_codec_parameters = vcodec_params;
format.stream.Add(stream);

transcodingParams.format.Add(format);
var q = new QencodeApiClient(apiKey);
var task = q.CreateTask();
var started = task.StartCustom(transcodingParams);
Console.WriteLine("Status URL: " + started.status_url);

Response Example

{
 "error": 0, 
 "status_url": "https://api.qencode.com/v1/status" 
}

Getting Task Status

/v1/status

OR

https://<master>/v1/status

Gets status for one or more transcoding jobs.
First endpoint: /v1/status is always available but can return a limited set of status attributes. E.g. completion percentage is not available (it's either 0% or 100% depending on the job is running or completed).
Master node status endpoint https://<master>/v1/status is available when job is being processed and returns most actual and full information on the job status. This endpoint url is returned in status_url attribute of a job status object.

ARGUMENTS

task_tokens

required

A list of task tokens previously obtained from /v1/create_task method

RETURNS

statuses

Dictionary containing status for each requested task token. Keys are task tokens and values contain status information for each job.
See status object attributes description below.

Status object description

ATTRIBUTES

status

Current task status.
See possible status values description below.

status_url

Endpoint to get most actual job status. You should always get job status using the endpoint specified as last value returned in status_url.

percent

Overall completion percent for the job.

error

Equals to 0 if there's no error and 1 in case of any error.

error_description

Contains error message.

images

List of objects, each containing image status information. See image status object attributes description below.

videos

List of objects, each containing video stream status information. See video status object attributes description below.

Image status object description

ATTRIBUTES

tag

System-defined tag value.

profile

Transcoding profile ID (if used to launch the job).

user_tag

User-defined tag value.

url

URL to the image.

Video status object description

ATTRIBUTES

tag

System-defined tag value.

profile

Transcoding profile ID (if used to launch the job).

user_tag

User-defined tag value.

url

URL to the image.

bitrate

Video bitrate.

duration

Video duration in seconds.

meta

Additional video information, e.g. frame dimensions.

POSSIBLE STATUS VALUES

downloading

Video is being downloaded to Qencode server.

queued

Task is waiting for available encoders.

encoding

Video is being transcoded.

saving

Video is being saved to destination location (e.g. Amazon S3 bucket).

completed

Video was saved to destination location. Transcoding job has completed successfully.

Request example

curl https://api.qencode.com/v1/status \
        -d task_tokens=76682314a86ed377730873394f8172
$response = $task->getStatus();
let response = task.GetStatus();
TranscodingTaskStatus response = task.getStatus();
var response = task.GetStatus();
Console.WriteLine(String.Format("{0} - {1}%", response.status, response.percent.ToString("0.00")));

Response example

{
    "error": 0, 
    "statuses": {
        "a2600fc63e4511e8ac870202b56d93e3": {
            "status": "completed", 
            "status_url": "https://master-79109168ae0711e8b00baa831f35b3f7.qencode.com/v1/status",
            "percent": 100, 
            "error": 0, 
            "error_description": null, 
            "images": [
                {
                    "tag": "image-0-0", 
                    "profile": "5a5db6fa5b8ac", 
                    "user_tag": "320x240/5", 
                    "storage": {
                        "bucket": "qencode-test", 
                        "type": "amazon_s3", 
                        "key": "output/320x240/12345_0.png", 
                        "format": null
                    }, 
                    "url": "https://s3.amazonaws.com/qencode-test/output/320x240/12345_0.png"
                }
            ], 
            "videos": [
                {
                    "tag": "video-0-0", 
                    "profile": "5a5db6fa5b8ac", 
                    "user_tag": "480p", 
                    "storage": {
                        "bucket": "qencode-test", 
                        "type": "amazon_s3", 
                        "key": "Outbound/480/12345.mp4", 
                        "format": "mp4"
                    }, 
                    "url": "https://s3.amazonaws.com/qencode-test/output/480/12345.mp4", 
                    "bitrate": 1692, 
                    "meta": "{\"width\": 854, \"resolution\": 480, \"height\": 480}", 
                    "duration": "0.371511"
                }
            ]
        }
    }
}

Direct Video Upload

https://<host>/v1/upload_file/<task_token>

Provides endpoint for direct video file upload using the TUS protocol for resumable uploads. Endpoint URL is returned with /v1/create_task method.

ARGUMENTS

task_token

required

Task token returned with /v1/create_task method.
Should be specified as a part of URL (and NOT a POST param).

RETURNS

file_uuid

TUS file uuid.
You can get file_uuid value from Location header returned on Step 2 of upload process (see "Call sequence example" in the right column).

Call sequence example

Step 1: get options from main upload endpoint

curl -i -X OPTIONS https://storage.qencode.com/v1/upload_file/6c6a9b0a7d23cc9555d460269aa9ed56

Response headers

HTTP/1.0 204 No Content
Server: BaseHTTP/0.3 Python/2.6.6
Date: Sun, 21 Oct 2018 20:55:47 GMT
Content-type: text/html
Content-length: 11
Tus-Version: 1.0.0
Tus-Max-Size: 10737418240
Tus-Checksum-Algorithm: sha1
Tus-Resumable: 1.0.0
Tus-Extension: creation,expiration,termination,checksum,creation-defer-length,concatenation
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: tus-resumable, upload-length, upload-metadata, upload-offset, content-type
Access-Control-Expose-Headers: location, tus-resumable, upload-expires, upload-offset, tus-checksum-algorithm, tus-extension, tus-max-size, tus-version
Access-Control-Allow-Methods: GET, POST, OPTIONS, HEAD, PATCH, DELETE

Step 2: Initiate upload (get endpoint for task)

curl -i -H "Tus-Resumable: 1.0.0" \ 
        -H "Upload-Length: 7444798" \
        -H "Upload-Metadata: filename dGVzdF9taW5pLm1wNA==" \
        -X POST https://storage.qencode.com/v1/upload_file/6c6a9b0a7d23cc9555d460269aa9ed56

Server returned Location header

HTTP/1.0 201 Created
Server: BaseHTTP/0.3 Python/2.6.6
Date: Sun, 21 Oct 2018 21:10:18 GMT
Content-type: text/html
Content-length: 11
Upload-Expires: Sun, 28 Oct 2018 21:10:18 GMT
Tus-Resumable: 1.0.0
Location: https://storage.qencode.com/v1/upload_file/6c6a9b0a7d23cc9555d460269aa9ed56/fa6ca4b8f06f42daa5b0da04cc461dcb
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: tus-resumable, upload-length, upload-metadata, upload-offset, content-type
Access-Control-Expose-Headers: location, tus-resumable, upload-expires, upload-offset, tus-checksum-algorithm, tus-extension, tus-max-size, tus-version
Access-Control-Allow-Methods: GET, POST, OPTIONS, HEAD, PATCH, DELETE

In the example above "fa6ca4b8f06f42daa5b0da04cc461dcb" is file_uuid

Step 3: get options from task upload endpoint

curl -i -X OPTIONS https://storage.qencode.com/v1/upload_file/6c6a9b0a7d23cc9555d460269aa9ed56/fa6ca4b8f06f42daa5b0da04cc461dcb

Response headers

HTTP/1.0 200 OK
Server: BaseHTTP/0.3 Python/2.6.6
Date: Mon, 22 Oct 2018 00:33:52 GMT
Content-type: text/html
Content-length: 2
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: tus-resumable, upload-length, upload-metadata, upload-offset, content-type
Access-Control-Expose-Headers: location, tus-resumable, upload-expires, upload-offset, tus-checksum-algorithm, tus-extension, tus-max-size, tus-version
Access-Control-Allow-Methods: GET, POST, OPTIONS, HEAD, PATCH, DELETElanguage: json

In the example above "fa6ca4b8f06f42daa5b0da04cc461dcb" is file_uuid

Step 4: Send data

Upload file using PATCH http method

curl -i -H "Tus-Resumable: 1.0.0" \ 
        -H "Content-Length: 7444798" \
        -H "Content-Type: application/offset+octet-stream" \
        -H "Upload-Offset: 0" \
        --data-binary "@./Downloads/test_mini.mp4" \
        -X PATCH https://storage.qencode.com/v1/upload_file/6c6a9b0a7d23cc9555d460269aa9ed56/fa6ca4b8f06f42daa5b0da04cc461dcb

Server returned Upload-Offset header

HTTP/1.0 204 No Content
Server: BaseHTTP/0.3 Python/2.6.6
Date: Mon, 22 Oct 2018 00:44:11 GMT
Content-type: text/html
Content-length: 11
Upload-Offset: 7444798
Upload-Expires: Mon, 29 Oct 2018 00:44:11 GMT
Tus-Resumable: 1.0.0
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: tus-resumable, upload-length, upload-metadata, upload-offset, content-type
Access-Control-Expose-Headers: location, tus-resumable, upload-expires, upload-offset, tus-checksum-algorithm, tus-extension, tus-max-size, tus-version
Access-Control-Allow-Methods: GET, POST, OPTIONS, HEAD, PATCH, DELETE

In the example above Upload-Offset response header value is equal to Content-Length which means upload is completed.

Receiving Callbacks

Callbacks are asynchronous notifications about job events. You can provide an endpoint on your server to receive task callbacks. If you use /v1/start_encode method to launch a job, you can update callback URL under your Project on Qencode.com.

Project callback settings

If you use /v1/start_encode2 method to launch a job, you should specify callback URL as a value of callback_url attribute of a query object. See Query object description.

Task callback is fired whenever any of the following events occur:

  • A new video is queued for transcoding. This occurs right after the /v1/start_encode or /v1/start_encode2 method is called.
  • A video transcoding job has completed.
  • An error has occurred during video processing.

CALLBACK REQUEST PARAMS

task_token

Task token.

event

Name of the event, i.e. 'queued', 'saved' or 'error'.

payload

Payload passed by client application to start_encode or start_encode2 method.

error_code

Error code (only for "error" event).

error_message

Error message (only for "error" event).

Setting callback for a custom job:

{
  "query": {
    "callback_url": "http://your-server.com/task_callback.php",
    "source": "...",
    "format": [
        ...
    ]
  }
}
$params = new CustomTranscodingParams();
$params->source = $video_url;
$params->callback_url = 'https://your-server.com/callback.php';
let transcodingParams = {};
transcodingParams.source = videoUrl;
transcodingParams.callback_url = "https://your-server.com/task_callback";
var transcodingParams = new CustomTranscodingParams();
transcodingParams.source = videoUrl;
transcodingParams.callback_url = "https://your-server.com/task_callback";

Callback Request Example:

{
    “task_token” : “1234567890”,
    “event” : “saved”,
    “payload” : “user data”
    "status" : {JSON-encoded string representing task status, see Getting task status}
}

Error Codes

  • If the job is SUCCESSFUL, 'error' param will be set to 0 in the response.
  • If the job has FAILED, response contains 'error' param set to a value from the Error Code table below.
ERROR CODE VALUE DESCRIPTION
ERROR_OK 0 Operation completed successfully
ERROR_SERVER_INTERNAL 1 Internal server error occurred. Please contact support in this case.
ERROR_BAD_API_KEY 2 Your API key does not pass validation.
ERROR_API_KEY_NOT_FOUND 3 We can't find such API key in our database.
ERROR_BAD_TOKEN 4 Token does not pass validation.
ERROR_TOKEN_NOT_FOUND 5 We can't find such token in our database
ERROR_SERVICE_SUSPENDED 6 Service suspended. There can be different reasons for that, e.g. you are using Free plan and 500 minutes limit is reached, or you have an outstanding invoice not paid. In case you are not sure what's the reason please contact support.
ERROR_MASTER_NOT_FOUND 7 Server issue. Please contact support in this case.
ERROR_SYSTEM_BUSY 8 We don't have enough resources to process request at the moment. You should retry it in a number of seconds specified in response.
ERROR_BAD_PAYLOAD 9 Payload value is too long.
ERROR_PROJECT_NOT_FOUND 10 Server issue. Please contact support in this case.
ERROR_BAD_PROFILE 11 Profile field value does not pass validation.
ERROR_PROFILE_NOT_FOUND 12 We can't find specified profile in our database.
ERROR_BAD_TOKENS 13 Task_tokens field value does not pass validation.
ERROR_FIELD_REQUIRED 14 Value for field specified in response is required in request.