POST /jobs/

Description

Create a new job to process a video file.

Authentication

• Required: Yes
• Method: Bearer token

Headers

• Authorization: Bearer [AUTH_TOKEN]
• Content-Type: application/json

Parameters

Query Parameters

• format: string (Optional)
  Values: json, xml
  Overrides the Request Accept header.
• human: boolean (Optional)
  Values: true, false
  If set to true, the response will be in a structured, more human-readable form. Useful when calling the API through curl or a browser.
• show_null: boolean (Optional)
  Values: true, false
  If set to true, the response will contain also keys that are not set to a value.
• expand_all: boolean (Optional)
  Values: true, false
  Recursively look up referenced objects (e.g. preset id) and embed the respective JSON as a nested object directly into the response.

Request Body

• pipeline_id: string (Required)
  References the pipeline on which to perform the job. This specifies the input and output locations for the job's input and output files as well as the notification scheme that applies to the job.
• input:input_name: string (Required)
  The URI/Filename of the input video file to convert. If given as a relative path, it is treated relative to the base input URI set in the referenced pipeline.
• input:start_time: float (Optional)
  Sets the start time (in seconds) from which to begin transcoding. All audio/video in the input before this start time is being skipped over.
• input:force_container: string (Optional)
  Force the transcoder to treat the input file as having the given container format instead of auto-detect.
• input:force_aspect_ratio: string (Optional)
  Force the transcoder to treat the input file as having the given aspect ratio instead of auto-detect.
• input:framerate: string (Optional)
  Force the transcoder to treat the input file as having the given framerate instead of auto-detect.
• input:interlaced: boolean (Optional)
  Values: true, false
  Force the transcoder to treat the input file as having the interlaced property as given instead of auto-detect.
• user_data: string (Optional)
  User-provided string that will be stored with the job and returned again in further GET requests or upon ping callbacks.
• output_prefix: string (Optional)
  Prefix to prepend globally to all files created by this job. Can be also folder names if the prefix strings contains "/". Can contain {job_id} placeholder, which will be replaced with the ID of the job.
• playlists:playlist_format: string (Optional)
  If set, a master playlist file including all (compatible) outputs will be created in the format specified. Current acceptable values: "HLS" or "M3U8".
• playlists:playlist_name: string (Optional)
  Sets the name of the playlist file to be created (file ending is automatically appended!). If not specified, the playlist file is named like its parent folder (according to output_prefix) or, if also no output_prefix is set, the default name is "master".
• autograph:watermark_strength: string (Optional)
  Determines the AutoGraph watermark embedding strength. Possible values are "stronger", "strong", "light", "verylight", and "ultralight", whereas "stronger" is the most robust embedding strength and "ultralight" the least visibly perceptible one. Default is: "light".
• autograph:autograph_prefix: string (Optional)
  Specifies the prefix to prepend to all AutoGraph copies created by making a call to the autographs subresource. The prefix must be made unique per Autograph by including the {tag} placeholder anywhere in the dir name - otherwise new autographed copies may overwrite older ones.
• outputs:preset_id: string (Required)
  Preset ID to be used for the job. It can be either a system or a custom-defined preset.
• outputs:output_name: string (Required)
  Filename to give to the converted output video file. No file ending should be specified because the file ending is added automatically based on the chosen container format. Can contain {job_id} placeholder, which will be replaced with the ID of the job.
• outputs:thumbnails:thumbnail_names: string (Optional)
  Thumbnail naming pattern. If not specified, no thumbnails will be created. The naming pattern can include the '{resolution}' and/or '{count}' variables which will be replaced with the thumbnail's resolution or sequence count.
• outputs:thumbnails:thumbnail_preset: string (Optional)
  Thumbnail preset to use.
• outputs:logos:logo_image: string (Optional)
  URL of the logo image to overlay onto the output video.
• outputs:logos:logo_preset: string (Optional)
  Logo preset to use.
• outputs:settings:video:height: string (Optional)
  The height of the output video. Can be an absolute value in pixels or relative in percentage.
• outputs:settings:video:width: string (Optional)
  The width of the output video. Can be an absolute value in pixels or relative in percentage.
• outputs:settings:video:framerate: string (Optional)
  The framerate of the output video. Must be an absolute value and be one of the allowed choices according to general validation rules.
• outputs:settings:video:bitrate: string (Optional)
  The bitrate of the video track in the converted output video. Can be a percentage value or an absolute value in kbps.
• outputs:settings:video:aspect_ratio: string (Optional)
  The aspect ratio to set on the output video. Must be one of the allowed choices under the general validation rules.
• outputs:settings:audio:bitrate: string (Optional)
  The bitrate of the audio track in the converted output video. Can be a percentage value or an absolute value in kbps.
• outputs:settings:audio:samplingrate: string (Optional)
  The sampling rate of the audio tracks in the converted output video. Must be an absolute value and allowed under the General Validation rules.
• outputs:settings:max_duration: int (Optional)
  Max number of seconds limiting the length of the output video.
• outputs:settings:http_streaming:playlist_format: string (Optional)
  If specified, a playlist file in the desired format named also according to 'output_name' is created and also segmented MP4 segments (.m4s files) for streaming are created for the output and placed under a 'm4s' sub-folder. Current possible values are: "HLS" and "M3U8".

Example Request

curl -X POST "https://api.xvid.com/v1/jobs/?human=true&show_null=true" \
  -H "Authorization: Bearer AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "job": {
      "pipeline": { "id": "5475dc68e4b00d2b0f7a6100" },
      "input": { "input_name": "uploads/ljDzFtXkNhBpYJ3K_RWL155oj7FWyriK/video02.mp4" },
      "autograph": { "watermark_strength": "light" },
      "user_data": "My Personal Marker",
      "output_prefix": "{job_id}/",
      "playlists": [ { "playlist_name": "mymaster", "playlist_format": "HLS" } ], 
      "outputs": [
        {
          "output_name": "REAL6_A_",
          "thumbnails": [
            {
              "thumbnail_names": "thumb_{resolution}_{count}",
              "thumbnail_preset": "thumbnails_small"
            }
          ],
          "logos": [
            {
              "logo_image": "https://s3-us-east-1.amazonaws.com/my_logo_pngs/logo30.png",
              "logo_preset": "logo_30_bottom_right"
            }
          ],
          "settings": {
            "video": {
              "height": "100%",
              "width": "100%",
              "bitrate": "90%"
            },
            "http_streaming" : { 
              "playlist_format" : "HLS"
            }
          },
          "preset": { "id": "5260e39d84aea12008b69bc1" }
        }
      ]
    }
  }'

Response

Success (201 Created)

{
  "job": {
    "id": "job_id",
    "pipeline": {
      "id": "5475dc68e4b00d2b0f7a6100",
      "href": "https://api.xvid.com/v1/pipelines/5475dc68e4b00d2b0f7a6100"
    },
    "input": {
      "input_name": "uploads/ljDzFtXkNhBpYJ3K_RWL155oj7FWyriK/video02.mp4"
    },
    "outputs": [
      {
        "output_name": "REAL6_A_",
        "preset": {
          "id": "5260e39d84aea12008b69bc1",
          "href": "https://api.xvid.com/v1/presets/5260e39d84aea12008b69bc1"
        }
      }
    ],
    "created_at": 1417010280925,
    "updated_at": 1417010280925,
    "href": "https://api.xvid.com/v1/jobs/job_id"
  }
}

Error Responses

400 Bad Request

{
  "error": "Invalid request parameters"
}

401 Unauthorized

{
  "error": "Authentication required"
}

500 Internal Server Error

{
  "error": "Internal server error"
}