Job Requests

Jobs are sent to Flix Cloud using POST requests. Requests must be sent in XML format. The XML markup elements of a request are defined below.

If you want an XML schema of our job request, you can download it in Relax NG (RNG) format.

Job Authorization Failure

If your account cannot be found by the api-key passed, you will receive a 401 Unauthorized response.

Sample Job Request

Following is an example Flix Cloud job request, including all optional elements. Details for each element follow the example.

You may also download the XML job request schema in Relax NG (RNG) format.

<?xml version="1.0" encoding="UTF-8"?>
<api-request>
  <api-key>2j1l:kd3add:0:ivzf:2e1y</api-key>
  <recipe-id>14</recipe-id>
  <notification-url>http://mysite.com/notify</notification-url>
  <pass-through>
    Here is a handy message passed through from the job 
    creation request to the job completion notification!
  <pass-through>
  <cue-points>
    <event>
      <cue-point>
        <name>cuept3</name>
        <time>3.4</time>
        <parameter>
          <key>First</key>
          <value>Value1</value>
        </parameter>
        <parameter>
          <key>Second</key>
          <value>Value2</value>
        </parameter>
      </cue-point>
      <cue-point>
        <time>1.4</time>
        <name>cuept4</name>
      </cue-point>
    </event>
    <navigation>
      <cue-point>
        <name>cuept1</name>
        <time>3.4</time>
        <parameter>
          <key>First</key>
          <value>Value1</value>
        </parameter>
        <parameter>
          <key>Second</key>
          <value>Value2</value>
        </parameter>
      </cue-point>
      <cue-point>
        <name>cuept2</name>
        <time>1.4</time>
        <parameter>
          <key>First</key>
          <value>value1</value>
        </parameter>
        <parameter>
          <key>Second</key>
          <value>Value2</value>
        </parameter>
      </cue-point>
    </navigation>
  </cue-points>
  <file-locations>
    <input>
      <url>ftp://ftp.files.com/vids/input.mov</url>
      <parameters>
        <user>joe</user>
        <password>Flu44fy</password>
      </parameters>
    </input>
    <output>
      <url>s3://mybucket/output.flv</url>
    </output>
    <watermark>
      <url>http://i.files.com/assets/watermark.png</url>
    </watermark>
    <thumbnails>
      <url>s3://mybucket/thumbs/</url>
      <prefix>thumb_</prefix>
    </thumbnails> 
  </file-locations>
  <recipe-settings>
    <width>360</width>
    <keyframe_frequency>120</keyframe_frequency>
  </recipe-settings>
</api-request>

Job Recipe Settings

Each Job Request must include either a recipe-id or recipe-name, which associates one of the recipes you have configured in the Flix Cloud dashboard with your job. It's possible, however, to override some or all of a recipe's encoding settings at job-creation time, using the optional recipe-settings element of your api-request.

Be aware that recipes created via the Flix Cloud dashboard are validated, meaning that the dashboard won't allow you to choose incompatible settings (for example, WMV recipes don't support PNG thumbnail exporting, so the feature isn't offered as a choice). When you override recipe settings in your job request, validation cannot be performed in advance. Any errors or parameter mismatches will be immediately returned in a Job Request Error response.

Most Flix Cloud users will find that the main job request parameters and a pre-configured recipe give them all the control they need over Flix Cloud jobs.

Why Would I Need to Deviate From a Recipe?

Some Flix Cloud users build their REST job requests with programs or scripts. These users may wish to slightly adjust a recipe for a particular job, because of a special case detected at runtime. For example:

• The deinterlacing filter might be selectively enabled for a certain input video;
• A thumbnailing interval that works well for most input videos might need adjustment for very short videos;
• The width:height dimensions of an input video might necessitate an adjustment to the output dimensions.

Usually, though, simply switching to an alternate recipe for special cases is much easier, and we suggest you avoid job-level recipe settings unless you have a specific need for them.

Sample recipe-settings Element

The optional recipe-settings element is a first child of api-request:

<?xml version="1.0" encoding="UTF-8"?>
<api-request>

  ...
  
  <recipe-settings>
    <width>360</width>
    <keyframe_frequency>120</keyframe_frequency>
  </recipe-settings>
  
  ...
  
</api-request>

What Can I Change With recipe-settings?

The recipe-id (or recipe-name) you choose will control the basic aspects of the encode: the container format, video codec and audio codec. recipe-settings cannot change these, but can change almost every other aspect of the recipe.

Job Recipe Settings XML Elements

All are optional, as is the recipe-settings element itself.

Video Options

Resolution Parameters

Audio Options

When changing audio encoding options via recipe-settings, ensure that the values you set for audio_channels, audio_bit_rate and audio_sample_rate are consistent with the following charts, organized by audio codec. A Job Request Error will be returned if you choose a combination of values which do not appear together in one of the rows below.

MP3 Audio

AAC Audio

AAC+ Audio

AMR Narrow-band Audio

VP6 Options

Advanced Options

Deinterlace Parameters

Keyframe Interval Type Parameters

PNG Image Thumbnail Options

Thumbnail Interval Options

Job Request Error Response

If your Job Request fails, Flix Cloud responds with a Request Error notification similar to the following:

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Malformed XML received, please check the syntax of your XML</error>
</errors>

Job Request Success Response

When Flix Cloud accepts a job request, it responds with a notification similar to the following:

<?xml version="1.0" encoding="UTF-8"?>
<job>
  <id type="integer">3254</id>
  <initialized-job-at type="datetime">2009-02-11T01:23:54Z</initialized-job-at>
</job>

Job Notification Response

In order to receive notifications when a job is finished, you must supply an Update Notification URL in your account dashboard under the Settings tab. This is the URL of a script or process that is listening for and can receive the Flix Cloud notification response. Notifications are only supported over HTTP on ports 80, 443, or 5555.

Once a job is finished you should receive a PUT response similar to the example below. initialized-job-at and finished-job-at will be in UTC time using the format YYYY-MM-DDTHH:MM:SSZ.

<?xml version="1.0" encoding="UTF-8"?>
<job>
  <finished-job-at type="datetime">2009-04-10T20:13:02Z</finished-job-at>
  <id type="integer">1322</id>
  <initialized-job-at type="datetime">2009-04-10T20:05:28Z</initialized-job-at>
  <pass-through>
    Here is a handy message passed through from the job creation
    request to the job completion notification!
  </pass-through>
  <recipe-name>Flash_vp6_250</recipe-name>
  <recipe-id type="integer">172</recipe-id>
  <state>successful_job</state>
  <error-message></error-message>
  <input-media-file>
    <url>s3://flixcloud-test/movie.mov</url>
    <width>1280</width>
    <height>720</height>
    <size>9842956</size>
    <duration>10005</duration>
    <cost>1638</cost>
  </input-media-file>
  <output-media-file>
    <url>s3://flixcloud-test/encoded.flv</url>
    <width>320</width>
    <height>176</height>
    <size>3937182</size>
    <duration>10005</duration>
    <cost>844</cost>
  </output-media-file>
  <thumbnail-media-file>
    <cost>238</cost>
    <url>s3://example_bucket/42/thumbs/vid42_</url>
    <number-of-thumbnails>8</number-of-thumbnails>
    <total-size>1136712</total-size>
  </thumbnail-media-file>
  <watermark-file>
    <url>s3://flixcloud-test/watermark.png</url>
    <size>1024</size>
    <cost>1</cost>
  </watermark-file>
</job>

Job Status Request

You can monitor the status of any job in the Job Detail page of your Dashboard, or by querying the API.

To query the API, send a GET request to http://www.flixcloud.com/jobs/<job_id>/status where <job_id> is the numeric identifier of the job whose status you want to query. Set the Accept and Content-Type headers to application/xml in the request.

You must authenticate the GET request using HTTP authentication, with your Flix Cloud API key as the password. The username can be any string.

For example, using cURL at the command line, a status query would look like this:

curl --get -H 'Accept: application/xml' -H 'Content-type: application/xml' \
  --user my_name:icen:rrg8in:0:2d19:7otj https://www.flixcloud.com/jobs/43495/status

Job Status Response

Each Job Status Request will return an XML response similar to the following:

<?xml version="1.0" encoding="UTF-8"?>
<job>
  <id type="integer">43495</id>
  <task-state>transcoding</task-state>
  <input-media-file-task>
    <task_id type="integer">162541</task_id>
    <state>success</state>
    <state type="float">100.0</state>
  </input-media-file-task>
  <transcoding-task>
    <task_id type="integer">162544</task_id>
    <state>processing</state>
    <state type="float">15.0</state>
  </transcoding-task>
  <output-media-file-task>
    <task_id type="integer">162545</task_id>
    <state>initialized</state>
    <state type="float">0.0</state>
  </output-media-file-task>
</job>

Job Status XML Elements

id, input-media-file-task, job, output-media-file-task, state, task-id, task-state

Response Values for state

Cancelling Jobs

To cancel a running job, access the Jobs tab of your dashboard. Click the job number you want to cancel. When the Job Detail page opens, click the Cancel this job link in the lower-right corner of the screen.

Job cancellation can only be done via the dashboard at this time.