End Points (Points of interaction with Blitline)
Submitting a Job
POST http://api.blitline.com/job
A job is a collection of 1 or more functions to be performed on an image. Data submitted to the job api must have a key of "json" and a value that is a string. The string must contain properly formatted JSON.
Polling for a job (development)
GET http://cache.blitline.com/listen/JOB_ID
The JOB_ID is the id returned when you post a job to Blitline. See new docs about polling
What JSON do I submit?
Show Advanced Functionality...
- application_idYour secret key which allows us to know who is submitting the data(required: 1 time)
- hashCauses the metadata about the original to return with a hash. The possible values are "md5", "crc32", or "sha256"(optional: 1 time)
- extended_metadataBlitline will return all the metadata associated with an image, including EXIF on the original, and info such as filesize, density, depth, and quality on each saved image.(optional: defaults to "false")
- suppress_auto_orientBlitline automatically tries to auto-orient a picture that has metadata that indicates that it is rotated. There are rare cases where you may wish to supress the auto-orientation. Set this to true in the rare case where you want you image to stay sideways or upside-down.(optional: defaults to "false")
- src_type
- When doing screenshots, set this to "screenshot" and the "src" url will be read as a website url.
- When set to "multipage" the source will be treated as a multiple page document. Each function will be performed individually on each page and output with a _[page index] after it.
- src_data (currently only used for screenshots)Config params for screenshots(optional: 1 time)
- viewportSet the "viewport" (virtual browser size) for screenshot. Uses the format "WIDTHxHEIGHT" (e.g. "300x480")(optional: 1 time)
- delayThe delay (in seconds) after the page loads to wait before the screenshot is taken. This allows javascript that wasn't "onLoad" to finish rendering. By default this is 5. (Set to 0 for faster screenshots if you don't do asynchronous javascript rendering)(optional: 1 time)
- srcThe location of the photo you wish to process(required: 1 time)
- postback_urlTriggers postback to given url once image has completed processing(optional: 1 time)
- wait_for_s3When set to "true" will poll S3 to make sure the image is available before issuing the postback to your postback_url. Note: It will only wait a maximum of 10 seconds before it will issue the postback regardless of whether the image is available or not.(optional: 1 time)
- content_type_json (for 'v'ersion below 1.18)As an oversight in our V1 API, the content_type for the postback is not "application/json". You can force this content type on the postback by setting this value to "true"(optional: 1 time)
- vAllows you to specify a specific version of the API. Default is 1.0, but if you set it to 1.18 you will get the following:(optional: 1 time)
- "content_type_json" is automatically true
- Image results on errors are a true Hash with "error", and "failed_image_identifiers" as keys. In earlier versions they were mistakenly set as individual entities in an array, which was weird and unintuative
It is RECOMMENDED you set your version to 1.18, Blitline will make a little more sense if you do. - pre_process (beta)Allows actions/jobs to be processed prior to running current job. View pre_process options here(optional: 1 time)
- long_runningIf you know your job is going to need a large resource machine (either high CPU or high MEM), you can designate it as long running. If you are getting errors back from your jobs indicating failures, it may be due to resource starvation on the standard cloud servers.(optional: 1 time)
- functionsOne or more operations you want performed on the source image (list of functions)(required: 1 or more times)
- saveContainer for the image you want saved(required: 1 time)
- image_identifierA string representing this image that will be returned with the image during a poll/callback (this is so that you can tell which image this is during a poll or callback)(required: 1 time)
- s3_destinationAn optional container to identify where you would like us to push the image to (if you have an Amazon S3 account which you have given Blitline permission to write to)(optional: 1 time)
- bucketYour S3 bucket to push to (required: 1 time) * Bucket in a different region?
- keyThe S3 key for the image that you wish Blitline to write to (you will need to name it, this key includes the filename)(required: 1 time)
- headersOptional array of headers to set on the object we push to S3(optional: 1 time)
- qualityQuality for jpg compression(0-100)(optional: defaults to 75)
- interlaceSets the interlace value(optional: defaults to none)
- png_quantizeUse a special optimization application to reduce 32 bit PNGs to 8 bit PNGs. Dramatically reduces the size of PNGs with a minimal loss in quality.(optional: defaults to false, only valid on .png outputs)
- extensionForces the file to a particular file type on output(optional: defaults to ".jpg" or ".png" depending on functions)
- save_metadataThis causes all metadata stored in the original image to be saved in the outputted image.(optional: defaults to false, so all metadata is removed by default)
- functionsOne or more operations you want performed on the
image results of the parent function (list of functions or watch a function tutorial )(optional: 1 or more times)
- saveContainer for the image you want saved(required: 1 time)
Using java? Need to more about Content-Type? click here...
What JSON do I get back?
- imagesAn array of image results (required: 1 time)
- image_identifierThe image identifier given by you for this image (required: 1 time)
- s3_urlThe 'eventual' location of this image once processed (required: 1 time)
- job_idThe ID to identify this job later (ie. if you are polling for this job, also the postback will contain this job_id) (required: 1 time)
OR
- errorA string message indicating the error (will only exist if there is an error) (optional: 1 time)
What do I do after I get my response?
Important: The fact that you got a response from Blitline DOES NOT MEAN THE JOB HAS FINISHED, only that we have 'accepted' your request and it has been put on a queue to be finished 'shortly'. There are 3 possible options for you now:
- If you had a postback_url in your JSON, your server will be contacted shortly, once the job has finished. Read more...
- You can poll to see if the job has complete (please prefer postbacks over polling).
- You can assume it will be done successfully and move on
Gotchas... What should I know about Blitline processed images?
There are some things you should know that happen by default on images output by Blitline. You can override these options, but they will happen automatically, so watch out for these "Gotchas"
- Files with a rotation flag set will automatically be rotated into the proper orientation. (You can change this by setting the "suppress_auto_orient" to true. See above.)
- Files output by Blitline are optimized for size, so default images have a .jpg quality of .75 (You can change this with the "quality" setting. See above.)
- Files output by Blitline are optimized for size, so they will have all metadata (EXIF, Color Profiles, etc.) stripped from them. (You can override this by setting "save_metadata" to true. See above.)
- Jobs with a postback will NOT be put into the polling cache, so you can have one or the other, but not both.
- Files uploaded to S3 will be default have their permissions set to publicly viewable. You can change this by setting the headers in the "s3_destination" field