Service Endpoint

http://api.sandcage.com/0.2/schedule-tasks


Example Request Payload

{"key":"Your API key.","jobs":[{"url":"http:\/\/cdn.sandcage.com\/p\/a\/img\/logo.jpg","tasks":[{"actions":"save"},{"actions":"resize","filename":"hello_world.jpg","width":200},{"actions":"crop","coords":"10,10,50,50"},{"reference_id":"123456789","actions":"rotate","degrees":90},{"actions":"cover","width":60,"height":60,"cover":"middle,center"}]},{"url":"http:\/\/cdn.sandcage.com\/p\/a\/img\/header_404.png","tasks":[{"actions":"resize","height":30}]}],"callback_url":"http:\/\/www.example.com\/callback_url"}

Example Success Response

{"request_id":"req_BIwZxRLaZnucI_J4z0KbUJ_4GJFQqYq","status":"success","tasks":[{"src_url":"http:\/\/cdn.sandcage.com\/p\/a\/img\/logo.jpg","reference_id":"","file_token":"file_zgvxnwk_ttcf82von8vufyzlafasdu","filename":"7o_wh_00rx76f4v32og35r4t7tg2ns28qca734cb0b","actions":"save"},{"src_url":"http:\/\/cdn.sandcage.com\/p\/a\/img\/logo.jpg","reference_id":"","file_token":"file_d2txv7hst7u0wmrguilzi55sve9pliz34f51c7","filename":"hello_world.jpg","actions":"resize","width":200},{"src_url":"http:\/\/cdn.sandcage.com\/p\/a\/img\/logo.jpg","reference_id":"","file_token":"file_v0h52kwo2sl1s6pwspeu0dq2ieisg20px4i","filename":"fdlapnxd9sclfzhwi890og8bla2s2l61ff1r91z5sc1luv44p60wdufdqatmzvhko8wx","actions":"crop","coords":"10,10,50,50"},{"src_url":"http:\/\/cdn.sandcage.com\/p\/a\/img\/logo.jpg","reference_id":"123456789","file_token":"file_3qw7fhq64euxdzqvwjjbpp2faxgpbrq_smyiq6_d","filename":"_yocs0v7rz55xwl3p_skku62c84ssvdbkgbni2bvuq_9lzvh331ahr4iiwfa1hcgunbqkk","actions":"rotate","degrees":90},{"src_url":"http:\/\/cdn.sandcage.com\/p\/a\/img\/logo.jpg","reference_id":"123456789","file_token":"file_lnohxfuyql1m3es1r_djqis3z_d_eyxcdey7vegd","filename":"dc4hgw76rdnsh05n26ssadosd57xo4m_3t_gt6uix9ml4r94tylb7ntgbusu_w","actions":"cover","height":30,"width":30,"cover":"bottom,right"},{"src_url":"http:\/\/cdn.sandcage.com\/p\/a\/img\/header_404.png","reference_id":"","file_token":"file_i_h6ct8iz46wrrx1t2xwlc2h8xaiz9kd8etfnj93","filename":"vz2vc978bst__19v60vzd6l_w2z9x8k78c75nk7qw_vy5xsnq8g_8fvayuhtuk2kvst1u0","actions":"resize","height":30}]}

Example Error Response

{"request_id":"req_BIwZxRLaZnucI_J4z0KbUJ_4GJFQqYq","status":"error","error_msgs":[{"code":1234,"short":"Short error message","long":"This is a long error message that describes in more detail the error that occurred."}]}

Example Success Response With Warning

{"request_id":"req_BIwZxRLaZnucI_J4z0KbUJ_4GJFQqYq","status":"success","warning_msgs":[{"code":1234,"short":"Short warning message","long":"This is a long warning message that describes in more detail the issue that occurred."}]}

Request Parameters

key*

string

requiredYour API key.
jobs*

array

Paid plans: 1...1000

requiredAn array of jobs to be placed in the queue.
jobs[]

struct

A single job
url*

string

4...1000

requiredThe url of the source file.
tasks*

array

1...10

requiredAn array of tasks to be placed in the queue.
tasks[]

struct

A single task
reference_id

string

0...100

optionalIf provided and not empty, then it will be returned as part of any callback and/or task status reports.
If it is not blank, then it should be unique for each of your images.
overwrite_file

boolean

optionalWhether or not the resulting image to be stored will overwrite any existing file at the specified path.
Default is false.
directory

string

0...500

optionalThe directory path where the resulting image will be stored.
If the specified directory or any the specified parent directories do not exist at the specified storage location, then they will be created.
filename

string

0...250

optionalThe file name with which the resulting image will be stored as.
If provided, combined with the directory in which the image will be stored it must specify a path which is not already in use, unless if the value of "overwrite_file" has been set to "true". If omitted, then a unique for the specified directory filename will be automatically assigned.
actions*

string

requiredIn the current version it must be one of the following actions are allowed:
  • save
  • resize
  • crop
  • rotate
  • cover

Note that image metadata is stripped off for the actions resize, crop, rotate and cover.
width

integer

1...20000

conditionalThe width of the resulting image.
This parameter will only be taken into account if the action "resize" or "cover" has been specified as the value of the "actions" parameter.
If the action "cover" has been specified as the value of the "actions" parameter, then a value for "width" is mandatory and must be equal to or smaller than the source image.
height

integer

1...20000

conditionalThe height of the resulting image.
This parameter will only be taken into account if the action "resize" or "cover" has been specified as the value of the "actions" parameter.
If the action "cover" has been specified as the value of the "actions" parameter, then a value for "height" is mandatory and must be equal to or smaller than the source image.
resize_percent

float

0.01...99.99

conditionalThe percent-wise dimensions of the resulting resized image relative to the dimensions of the source image.
If a value has been provided for either "width" or "height", the value provided for this parameter will not be taken into account.
This parameter will only be taken into account if the action "resize" has been specified as the value of the "actions" parameter.
fit

boolean

conditionalWhether or not the resulting image should fit within the specified width and height.
This flag will only take affect if both "width" and "height" have been specified.
If the "width" and "height" are both specified without the "fit" parameter being set to "true" and the set values for "width" and "height" do not respect the aspect ratio of the image, then the produced image will be skewed.
Available options:
  • true
  • false

Default is false.
coords

string

conditionalExample: 10,10,50,50
In this example the above value represents the coordinates for x1,y1,x2,y2. These represent respectively the upper-left corner coordinates (x1,y1), followed by the bottom-right corner coordinates (x2,y2). x1 and y1 must be equal or larger than 1, whereas x2 and y2 must be equal or smaller than the dimensions of the source image. In addition x1 must be smaller than x2 and y1 must be smaller than y2.
If these conditions are not met, then an error will be returned.
This parameter will only be taken into account if the action "crop" has been specified as the value of the "actions" parameter.
If omitted or if the value does not match the format of the example above, then 0 will be used for x1 and x2, whereas the width and height of the source image will be respectively used for x2 and y2.
degrees

integer

conditionalOne of the following values:
  • 90
  • 180
  • 270
The amount of the degrees to rotate clock-wise.
This parameter will only be taken into account if the action "rotate" has been specified as the value of the "actions" parameter.
If omitted or if the value is not one the accepted values, then a 90 degree clock-wise rotation will be applied.
cover

string

conditionalOne or two of the following values:
  • top
  • bottom
  • middle
  • left
  • right
  • center
Multiple, non-conflicting values can be provided by comma separating them. Example: top,right or middle,left
This parameter will only be taken into account if the action "cover" has been specified as the value of the "actions" parameter.
If omitted or if the value is not one the accepted values, then this value will default to "middle,center".
compress

boolean

optionalWhether or not the resulting image should be compressed.
Available options:
  • true
  • false

Default is false.
callback_url

string

4...1000

optionalYour callback url.
If provided, a callback will be sent to this url whenever there is an update available for any of the tasks included in this request. See Callback for more details.

Response Format

request_id

string

A unique identifier for this request.
status

string

Either "success" or "error".
tasks

array

1...10000

An array of tasks.
This will only be included as part of the response if the value of "status" was not "error".
tasks[]

struct

A single task
src_url

string

4...1000

always returnedThe provided in the request value for the "url" for the related parent job.
reference_id

string

0...100

always returnedThe "reference_id" that was provided within the request for the respective task.
file_token

string

30...70

always returnedThe unique token of the task.
This is generated by and can be used as an alternative identifier.
filename

string

0...250

always returnedThe file name with which the resulting image was stored.
actions

string

always returnedThe value that was provided for the "actions" of the respective task.
In the current version it must be one of the following actions are allowed:
  • save
  • resize
  • crop
  • rotate
  • cover
width

integer

1...20000

conditionally returnedThe value that was provided for the "width" of the respective task.
If a value was not provided, then this node will be omitted.
height

integer

1...20000

conditionally returnedThe value that was provided for the "height" of the respective task.
If a value was not provided, then this node will be omitted.
resize_percent

float

0.01...99.99

conditionally returnedThe value that was provided for the "resize_percent" of the respective task.
If a value was not provided, then this node will be omitted.
fit

boolean

conditionally returnedThe value that was provided for the "fit" of the respective task.
If a value was not provided, then this node will be omitted
coords

string

conditionally returnedThe value that was provided for the "coords" of the respective task.
If a value was not provided, then this node will be omitted.
degrees

integer

conditionally returnedThe value that was provided for the "degrees" of the respective task.
If a value was not provided, then this node will be omitted.
compress

boolean

conditionally returnedThe value that was provided for the "compress" of the respective task.
If a value was not provided, then this node will be omitted
error_msgs

array

An array of errors.
Error messages will only be included as part of the response if the request was not successful.
error_msgs[]

struct

An error.
code

string

The error code.
short

string

The short error message.
long

string

The long and more detailed error message.
warning_msgs

array

An array of warnings.
Warning messages will only be included as part of the response if the request was successful.
warning_msgs[]

struct

A warning.
code

string

The warning code.
short

string

The short warning message.
long

string

The long and more detailed warning message.

Callbacks


Example Callback Payload

{"tasks":[{"status":"success","request_id":"req_BIwZxRLaZnucI_J4z0KbUJ_4GJFQqYq","src_url":"http:\/\/cdn.sandcage.com\/p\/a\/img\/logo.jpg","reference_id":"","file_token":"file_kbx3_lwybbn0c1uaaa1jeusfz95oex3omm9knx","filename":"7o_wh_00rx76f4v32og35r4t7tg2ns28qca734cb0b","actions":"save","mime":"image\/png"},{"status":"success","request_id":"req_BIwZxRLaZnucI_J4z0KbUJ_4GJFQqYq","src_url":"http:\/\/cdn.sandcage.com\/p\/a\/img\/logo.jpg","reference_id":"","file_token":"file_aqtv0y2vbczrogrf3hsdb2__vbaqq0","filename":"hello_world.jpg","actions":"resize","width":200,"height":150,"mime":"image\/png"},{"status":"success","request_id":"req_BIwZxRLaZnucI_J4z0KbUJ_4GJFQqYq","src_url":"http:\/\/cdn.sandcage.com\/p\/a\/img\/logo.jpg","reference_id":"123456789","file_token":"file_qxtfll34mlb29gckn38dx5iz4wky0v1k81ka","filename":"fdlapnxd9sclfzhwi890og8bla2s2l61ff1r91z5sc1luv44p60wdufdqatmzvhko8wx","actions":"crop","width":40,"height":40,"mime":"image\/png"},{"status":"success","request_id":"req_BIwZxRLaZnucI_J4z0KbUJ_4GJFQqYq","src_url":"http:\/\/cdn.sandcage.com\/p\/a\/img\/logo.jpg","reference_id":"","file_token":"file__brlgt5_ec2ti7wd5mjrk12s7nxkby3dm0iu8y7","filename":"_yocs0v7rz55xwl3p_skku62c84ssvdbkgbni2bvuq_9lzvh331ahr4iiwfa1hcgunbqkk","actions":"rotate","width":773,"height":972,"mime":"image\/png"},{"status":"success","request_id":"req_BIwZxRLaZnucI_J4z0KbUJ_4GJFQqYq","src_url":"http:\/\/cdn.sandcage.com\/p\/a\/img\/logo.jpg","reference_id":"","file_token":"file_rmflxu3c02sgwl99ykvtk1haqjj5foa5xjmj31","filename":"dc4hgw76rdnsh05n26ssadosd57xo4m_3t_gt6uix9ml4r94tylb7ntgbusu_w","actions":"cover","width":60,"height":60,"mime":"image\/png"},{"status":"error","request_id":"req_BIwZxRLaZnucI_J4z0KbUJ_4GJFQqYq","src_url":"http:\/\/cdn.sandcage.com\/p\/a\/img\/header_404.png","reference_id":"","file_token":"file_e78gje0d53g6fczv15facfmm4kuerf74arc0yl4v","filename":"vz2vc978bst__19v60vzd6l_w2z9x8k78c75nk7qw_vy5xsnq8g_8fvayuhtuk2kvst1u0","actions":"resize","error_code":"1105","error_msg":"The source image request responded with a 404."}]}

Callback Format

tasks

array

1...10000

An array of tasks.
tasks[]

struct

A single task
status

string

always returnedEither "success", "error".
request_id

string

always returnedThe "request_id" that was associated the respective task action.
src_url

string

4...1000

always returnedThe provided in the request value for the "url" for the related parent job.
reference_id

string

0...100

always returnedThe "reference_id" that was provided within the request for the respective task.
file_token

string

30...70

always returnedThe unique token of the task.
This is generated by and can be used as an alternative identifier.
filename

string

0...250

always returnedThe file name with which the resulting image was stored.
actions

string

always returnedThe action that was selected for this task. Namely:
  • save
  • resize
  • crop
  • rotate
  • cover
cdn_url

string

4...1000

conditionally returnedThe url from which the resulting image is available from.
This will only be included if the value of "status" for this tasks was "success" and if the file was not deleted.
width

integer

1...20000

conditionally returnedThe resulting image width.
This will only be included if the value of "status" for this tasks was "success" and the respective action was anything but "save".
height

integer

1...20000

conditionally returnedThe resulting image height.
This will only be included if the value of "status" for this tasks was "success" and the respective action was anything but "save".
mime

string

conditionally returnedThe mime type of the file.
This will only be included if the value of "status" for this tasks was "success".
error_code

string

conditionally returnedThe error code.
This will only be included if the value of "status" for this tasks was "error".
error_msg

string

conditionally returnedThe error message.
This will only be included if the value of "status" for this tasks was "error".

Still Have Questions?

We're always happy to help with code and integrations. Talk to us!