API Documentation

For easy integration with your projects, we supply two libraries for Ruby/Rails:

API Endpoint URL

All API Requests should be directed to the main API URL : http://www.phocoder.com/

API Request/Response Formats

API requests can be submitted in one of two formats. JSON and XML. The format of the response will be dependent on the format of the request.

Please note: At this time the JSON format API is well tested and is being used in production on a number of sites. The XML API may still be a bit rough around the edges, but we are looking for testers. If you are interested in using the XML API please let us know so that we can work with you if needed to make sure that things go as smoothly as possible.

Common API Request Parameters

For all API requests, you must include an api_key parameter.

JSON
{
  api_key : "XXXXXXXXX"
}
XML
 
   
    XXXXXXXXXXX

Creating Jobs

All jobs share the same basic creating process.

  1. Assemble your job parameters in either JSON or XML format.
  2. POST your job parameters to http://www.phocoder.com/jobs
  3. Use the job response to create/update records for the outputs that are to be created.
  4. Listen for notifications in order to know when your output is ready.

Common Job Creation Request Parameters

For all job creation requests, you must include a type parameter and you may optionaly include a queue_name parameter.

JSON
{
  api_key : "XXXXXXXXX",
  type : "ThumbnailJob",
  queue_name : "user_5"
}
XML
 
   
    XXXXXXXXXXX  
    ThumbnailJob
    user_5

Creating a Thumbnail Job

A thumbnail job will take one image file as an input and produce one or more 'thumbnail' versions of the image. 'Thumbnail' is a loose term since the images produced may be several mega pixels in size depending on your job settings.

Thumbnail Job Parameters

If you wanted to produce a 'medium' version of an image that would fit inside of a 400x400 square, while maintaining the original aspect ratio, and also produce a 'small' 100x100 cropped thumbnail you would use a request something like this.

JSON
{
  api_key : "XXXXXXXXX",
  input : "http://development.photoapi.webapeel.com.s3.amazonaws.com/test/dsc_8399.jpg",
  thumbnails : [
    {
      width : 400,
      height : 400,
      aspect_mode : 'preserve',
      label : 'medium'
    },
    {
      width : 100,
      height : 100,
      aspect_mode : 'crop',
      label : 'small'
    }
  ]
}
XML
 
   
    XXXXXXXXXXX
    http://development.photoapi.webapeel.com.s3.amazonaws.com/test/dsc_8399.jpg</input>
    
      
        400
        400
        preserve
        
      
      
        100
        100
        crop

Here's an example of a request with just one thumbnail, but it includes a frame, an annotation and a notification.

JSON
{
  api_key : "XXXXXXXXX",
  input : "http://development.photoapi.webapeel.com.s3.amazonaws.com/test/dsc_8399.jpg",
  thumbnails : [
    {
      width : 800,
      height : 800,
      aspect_mode : 'preserve',
      label : 'large',
      frame : { width : 25, color : '000000' },
      annotations : [{ text : "(c) 2011", gravity : "North", pointsize : 15, y : 5, fill_color : 'ffffff' }],
      notifications : [{ url : "http://some-made-up-test-domain.com/notification_callback_url" }]
    }
  ]
}

Thumbnail Job Response

Once a thumbnail job has been accepted for processing Phocoder will return an immediate response with details about each thumbnail that will be produced as part of that job.

A sample thumbnail job resonse:

JSON
{
  job : {
    id : 1234,
    inputs : [{ id : 1234 }],
    thumbnails : [
      {
        id : 1234,
        label : "medium",
        filename : "my-file.jpg"
      }
    ]
  }
}

Creating an HDR Job

An HDR job will take one or more images as inputs and merge them to a single HDR file. The inputs can optionaly be auto-aligned if they were not captured on a tripod.

HDR Job Parameters

Most of these parameters are passed to pfshdrcalibrate. Explanation of the parameters from from the pfstools documentation.

Optimize Gauss

The gauss setting is the primary way to control the number of saturated pixels in the output HDR. In order to optimize your HDR file around the gauss setting it is recommended that you pass in a 'starting_gauss' of 0.5 and 'true' for 'optimize_gauss'. Then we'll generate an HDR file with gauss 0.5 and examine the number of saturated pixels in the output. If the number of saturated pixels is greater than 1% we will try a slightly lower gauss and repeat the process. Once the number of saturated pixels in the output is less than 1% we will consider the HDR file to be optimized. Passing in a value lower than 0.5 for 'starting_gauss' may speed up the optimization process, particularly if there are a small number of input images, or if they are all especially dark or light.

If you have two images that you want to auto-align and merge to one 'gauss optimized' HDR image called 'my-image.hdr' you would use a request like this:

JSON
{
  api_key : "XXXXXXXXX",
  inputs : [
    {url : "http://development.photoapi.webapeel.com.s3.amazonaws.com/test/dsc_8399.jpg"},
    {url : "http://development.photoapi.webapeel.com.s3.amazonaws.com/test/dsc_8400.jpg"}
  ],
  hdr : {
      filename : 'my-image.hdr',
      optimize_gauss : true,
      starting_gauss : 0.5,
      align : true
  }
}
XML
 
   
    XXXXXXXXXXX
    
      http://development.photoapi.webapeel.com.s3.amazonaws.com/test/dsc_8399.jpg</input>
      http://development.photoapi.webapeel.com.s3.amazonaws.com/test/dsc_8400.jpg</input>
    
    
      my-image.hdr
      true
      0.5
      true

HDR Job Response

Once an hdr job has been accepted for processing Phocoder will return an immediate response with details about the output file that will be produced as part of that job.

A sample thumbnail job resonse:

JSON
{
  job : {
    id : 1234,
    inputs : [{ id : 1234 },{ id : 1235 }],
    hdr : {
      id : 1234,
      label : "hdr",
      filename : "my-image.hdr"
    }
  }
}

Creating a Tonemapping Job

A tonemapping job will take one image file as an input and produce a tonemapped version of it based on the parameters passed in. Optionally one or more thumbnails may be created as a part of the job.

Many of the options for tonemapping jobs come from the operators in the pfstools collection. The descrtion of those parameters comes from the pfstools documentation.

Tonemapping Job Parameters

Here's a sample tonemapping job request.

JSON
{
  api_key : "XXXXXXXXX",
  type : "ToneMappingJob",
  input : "http://development.photoapi.webapeel.com.s3.amazonaws.com/test/dsc_8399.jpg",
  tonemapping : {
    operator : "mantiuk06"
  },
  thumbnails : [
    {
      width : 400,
      height : 400,
      aspect_mode : 'preserve',
      label : 'medium'
    },
    {
      width : 100,
      height : 100,
      aspect_mode : 'crop',
      label : 'small'
    }
  ]
}
XML
 
   
    XXXXXXXXXXX
    http://development.photoapi.webapeel.com.s3.amazonaws.com/test/dsc_8399.jpg</input>
    
      mantiuk06
    
    
      
        400
        400
        preserve
        
      
      
        100
        100
        crop

Tonemapping Job Response

Once a tonemapping job has been accepted for processing Phocoder will return an immediate response with details about the output files that will be produced as part of that job.

A sample tonemapping job resonse:

JSON
{
  job : {
    id : 1234,
    inputs : [{ id : 1234 }],
    tonemapping : {
      id : 1234,
      label : "tm",
      filename : "my-tone-mapping.jpg"
    },
    thumbnails : [
      {
        id : 1234,
        label : "medium",
        filename : "my-tone-mapping-medium.jpg"
      }
    ]
  }
}

Creating a Composite Job

A composite job will take multiple input images and create a virtual stack of image layers. Each layer has a blending mode and an opacity. The final composite is the result of flattening all of the layers.

Composite Job Parameters

A sample composite job might look like this:

JSON
{
  api_key : "XXXXXXXXX",
  type : "CompositeJob",
  composite : {
  },
  composite : {
    auto_normalize : true,
    layers : [
      {
        input : "http://development.photoapi.webapeel.com.s3.amazonaws.com/test/dsc_8399.jpg",
        opacity : 50,
        blending_mode : "OverCompositeOp"
      },
      {
        input : "http://development.photoapi.webapeel.com.s3.amazonaws.com/test/dsc_8400.jpg",
        opacity : 100,
        blending_mode : "NormalCompositeOp"
      }
    ]
  },
  thumbnails : [
    {
      width : 400,
      height : 400,
      aspect_mode : 'preserve',
      label : 'medium'
    },
    {
      width : 100,
      height : 100,
      aspect_mode : 'crop',
      label : 'small'
    }
  ]
}
XML
 
   
    XXXXXXXXXXX
    
      true
      
        
          http://development.photoapi.webapeel.com.s3.amazonaws.com/test/dsc_8399.jpg</input>
          50
          OverCompositeOp
        
        
          http://development.photoapi.webapeel.com.s3.amazonaws.com/test/dsc_8400.jpg</input>
          100
          NormalCompositeOp
        
      
    
    
      
        400
        400
        preserve
        
      
      
        100
        100
        crop

Composite Job Response

Once a composite job has been accepted for processing Phocoder will return an immediate response with details about each output that will be produced as part of that job.

A sample composite job resonse:

JSON
{
  job : {
    id : 1234,
    composite : [
      {
        id : 1234,
        label : "composite",
        filename : "my-file.jpg"
      }
    ]
  }
}
© 2011 Jeremy Green - All rights reserved.
Stop acting