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


Check out our Advanced API Documentation Site      [x]

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)
  • imagga_tagsFor Imagga accounts, you can have Imagga generate "smart" tags for your image(optional: 1 time)
  • wait_retry_delayNumber of seconds to wait before retry (only in the event of failure to load "src" image). This is useful when processing images recently uploaded to S3. There is often latency before the image becomes available. In the event of this latency, we will requeue the job upon failure and try again in X seconds, where you specify how long we should wait.(optional: 1 time)
  • retry_postbackBoolean to indicate if Blitline should retry postbacks if your server returns an error. Typical retry times are 1 sec, 15sec, and 10min. These times may not be exact, and can be delayed based on queue usage. Do not DEPEND on them happening at specific intervals because those intervals might change.(optional: defaults to "false", requires "v" = 1.2)
  • extended_metadata(prefer get_exif)Blitline 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. For PDF's it will return data about the PDF.(optional: defaults to "false")
  • get_exifBlitline 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")
  • passthrough_metadataBlitline will return any data you store here in the metadata field. This requires "extended_metadata" to be set to true. ALSO, this data must be in dictionary (hash) form.(optional: 1 time) Must be in form { "foo" : "bar"}, NOT a string.
  • include_iptcBlitline will return all the metadata associated with the IPTC fields embedded in the 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 suppress 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 "screen_shot_url" 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.
    • When set to "burst_pdf" the source will be treated as a large PDF, each page will be turned into it's own job, and the functions copied over to this job, thereby executing the functions on each of the pages. The postback_url will be called when all pages have completed.
    (optional: 1 time)
  • src_dataConfig params for screenshots(optional: 1 time)
    • (For Images) colorspaceForces "src" image to defined colorspace. Options are "rgb" or "cmyk"(optional: 1 time)
    • (For Screenshots) viewportSet the "viewport" (virtual browser size) for screenshot. Uses the format "WIDTHxHEIGHT" (e.g. "300x480")(optional: 1 time)
    • (For Screenshots) delayThe delay (in milliseconds) 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 5000. (Set to 0 for faster screenshots if you don't do asynchronous javascript rendering)(optional: 1 time)
    • (For PDFs) dpiSets the density at which the PDF will be rasterized. If making a printable image, you probably want this to be 200 at least.(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)
  • postback_headersAdds the contained JSON key:value fields as headers on the postback. (This can be useful for validating postbacks from Blitline)
    Example: "postback_headers" : { "Blitline-Postback" : "XYX" }
    (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.20 you will get the following:(optional: 1 time)
    • "content_type_json" (for postback) is automatically true
    • long poll cache results are proper JSON, (not string encoded "results")
    • 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 confusing
    • Color Profiles are automatically preserved (unless "save_profiles" : "false" is specified in "save" field).
    It is RECOMMENDED you set your version to 1.23, Blitline will make a little more sense if you do.
  • pre_processAllows 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)
    • nameName of the function to be performed(required: 1 time)
    • paramsParameter values for the specified function(optional: 1 time)
    • 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)
        • force_typeIf your output key does not contain a file extension(ie. png, jpg, etc), you can force the output file type to be a particular type. (optional: 1 time) Without an extension, default type is JPG.
      • qualityQuality for jpg compression(0-100)(optional: defaults to 75)
      • skipSkip the actual save and push to S3/Azure. The is only useful when doing an operation where you DON'T want an image saved.(optional: defaults to false)
      • save_profilesKeep any color profile associated with image.(optional: defaults to false for 'v' < 1.20)
      • 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)
        NOTE: Can alternatively be set to a number (1-10). 1 = Slowest/best quality, 10 = Fastest/worst quality. Default is 5
      • 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)


Using java? Need to more about Content-Type? click here...



What JSON do I get back?

A hash with "results" as a key, and the following as the value hash
  • 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)


  • 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
Read More About Postbacks...



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
  • All color profiles are DELETED by default. Only if you set  "save_profiles":true or   "save_metadata":true or   "v":1.20 will your embedded color information be preserved.



Development Libraries

 Blitline Maintained

 Community Maintained