API Documentation

Appearance

POST /jobs ​

Description ​

Create a new job to process a video file.

Authentication ​

  • Required: Yes
  • Method: Bearer token (OAuth 2.0 API access token)

Request 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.

Body Parameters ​

  • 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: object (Required)
    • 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.
    • 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.
    • force_container: string (Optional)
      Force the transcoder to treat the input file as having the given container format instead of auto-detect.
    • force_aspect_ratio: string (Optional)
      Force the transcoder to treat the input file as having the given aspect ratio instead of auto-detect.
    • framerate: string (Optional)
      Force the transcoder to treat the input file as having the given framerate instead of auto-detect.
    • 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: array (Optional)
    An array of master playlist files (and their formats) to be created. By default, the playlists will reference all (compatible) outputs of the job.
    • 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".
    • 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: object (Optional)
    If not null, enables Xvid AutoGraph forensic watermarking for all outputs in this job. Note: The output data internally processed and stored when using the autograph option will be about 2-8 times larger than without autograph due to the additional watermark data that must be precomputed in autograph mode. This will cause higher encoding and storage costs compared to not using 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_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: array
    An array of output files to be created with their respective presets. This enables creating multiple outputs from one input within one job.
    • preset_id: string (Required)
      Preset ID to be used for the job. It can be either a system or a custom-defined preset.
    • 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.
    • thumbnails: array (Optional)
      If present, thumbnails will be created for the output according to the thumbnail_preset selected and named according to the thumbnail_names naming pattern.
      • 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.
      • thumbnail_preset: string (Optional)
        Thumbnail preset to use.
    • logos: array (Optional)
      If present, one or more logos will be overlayed onto the output video using the image URL provided as logo_image and according to the settings specified in the logo_preset selected.
      • logo_image: string (Optional)
        URL of the logo image to overlay onto the output video.
      • logo_preset: string (Optional)
        Logo preset to use.
    • settings: object (Optional)
      • video: object (Optional)
        • height: string (Optional)
          The height of the output video. Can be an absolute value in pixels or relative in percentage.
        • width: string (Optional)
          The width of the output video. Can be an absolute value in pixels or relative in percentage.
        • 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.
        • 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.
        • 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.
      • audio: object (Optional)
        • 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.
        • 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.
      • max_duration: int (Optional)
        Max number of seconds limiting the length of the output video.
      • http_streaming: object (Optional)
        • 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 ​

bash
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"
        }
      }
    ]
  }
}'

Example Response ​

Success (201 Created) ​

json
{
  "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 ​

json
{
  "error": {
    "error_code": "0x0050001",
    "error_message": "Invalid Input"
  }
}

403 Unauthorized ​

json
{
  "error": {
    "error_code": "0x0000003",
    "error_message": "Invalid access token"
  }
}

500 Internal Server Error ​

json
{
  "error": {
    "error_code": "0x0000001",
    "error_message": "Internal Error"
  }
}