This documentation describes the Cloudsto.re new Core Web Services API
Version 2.0 (Released Jan 2019)
Make all requests to: https://api.cloudsto.re/core
TLS 1.2 (or better) encryption is required for all calls to all the Cloudsto.re Web Services. TLS version 1.1 and earlier are not supported.
The Cloudsto.re API is designed as RESTful API. All API calls are implemented as httpMethod: POST. The HTTP response codes 200 is success responses, all other response codes are errors. Data will only be returned for HTTP response code 200. Error descriptions can be obtained from the response body. See Error handling section for further information.
All request data sent to the Cloudsto.re API must be in JSON objects. See the section for each API call for the full details of the request data format. The content-type header should be set accordingly to application/x-www-form-urlencoded .
Return data from the API is in JSON objects by default. See the section for each API call for the full details of the return values within the response object. JSON is the recommended data format for returned data and accept header should be set to either: application/json or */*. (XML format data returns can be requested by setting the accept header to application/xml, This feature is currently experimental and not fully tested)
Each API call should contain an API key for authentication. API keys are created when you are registered to use the service (see /APIKey endpoint for further onformation)
Endpoint | Description | Functions |
---|---|---|
/apikey | Work with account API Key | · Get API Key for account |
/publisher/business | Work with Publisher businesses | · Request list of publisher business and its information |
/publisher/medias | Work with Publisher Paper medias | · Request list of publisher paper medias and its information |
/publisher/medias/add | Work with Publisher Paper Medias | · Request add a new publisher paper media information |
/publisher/medias/remove | Work with Publisher Paper Medias | · Request removal of a publisher paper media information |
/publisher/medias/update | Work with Publisher Paper Medias | · Request update of publisher paper media information |
/publisher/update | Work with Publisher | · Request update of publisher information |
/vault/remove | Work with Vault | · Request removal of an image from Vault |
/vault/update | Work with Vault | · Request update of an image in Vault |
/vault/upload | Work with Vault | · Request upload to Vault |
Request an API Key for the account to be used with all subsequent API calls for authorisation. API keys should be stored in memory by the calling app for the use within the session, but you are encouraged to make a new call for API Key between sessions and not to store the key locally. The API Key may change periodically for security reasons.
This call also returns some additional information about the business associated with the login.
{ "Username": "user@example.com", "Password" : "mypassword" }
Name | Type | Description | Required |
---|---|---|---|
Username | string | Account username (URI Encoded) | Yes |
Password | string | Account password (URI Encoded) | Yes |
{ "APIKey": "x-a3A1qLrXStYDgThU3dfA", "BusinessID" : "BS-25", "BusinessName": "Artsto.re", "CurrencyCode" : "GBP", "IsPublisher" : false }
Name | Type | Description |
---|---|---|
APIKey | string | Unique key associate with account to be used with all API calls |
BusinessID | string | Business ID |
BusinessName | string | Business Name |
CurrencyCode | string | GBP, USD or EUR |
IsPublisher | boolean | if true the account has publishing rights |
$.ajax({ url: "https://api.cloudsto.re/core/apikey", contentType: 'application/x-www-form-urlencoded', dataType: 'json', type: 'POST', data: JSON.stringify({“Username”:“user@example.com”, "Password" : "mypassword"}), success: function(response) { // process returns }, error: function(err) { // handle error } });
$curl -d '{“Username” : “user@example.com”,"Password" : "mypassword"}' \ -X POST https://api.cloudsto.re/core/apikey
Request a list of all information about this account’s publisher.
Only accounts with publisher privilege are allowed to get paper media information.
{ "APIKey": "x-a3A1qLrXStYDgThU3dfA" }
Name | Type | Description | Required |
---|---|---|---|
APIKey | string | Authorisation key unique to account | Yes |
{ "PublisherID":"PB-27", "PublisherName":"imagesto.re", "CostValue": 50.0, "CostUnit": 5, "FixedCostValue": 0, "PremiumFactor": 1, "PublisherAvailable" : true, "FactorP" : 1, "CurrencyCode" "GBP", "CurrencyExchangeGBP" : 1, "CurrencyExchangeUSD" : 1.3, "CurrencyExchangeEUR" : 1.2 }
Name | Type | Description |
---|---|---|
PublisherID | string | Publisher ID |
PublisherName | string | Publisher name |
Available | boolean | Publisher available flag: true or false |
CurrencyCode | string | GBP, USD or EUR |
CurrencyExchangeGBP | float | Currency exchange factor for GBP |
CurrencyExchangeUSD | float | Currency exchange factor for USD |
CurrencyExchangeEUR | float | Currency exchange factor for EUR |
CostValue | float | Image Royalty cost value per cost unit (specified below) based on publisher currency. |
CostUnit | integer | Cost Unit for Cost Value (specified above). The valid values are:1 : Square Millimetre
2 : Square Centimetre 3 : Square Inch 5 : Square Meter 6 : Square Foot |
FixedCostValue | float | Specify a fixed cost value added to image printed at any size, based on publisher currency. |
FactorP | float | Additional publisher factor cost |
PremiumFactor | float | Specify factor applied to image royalty when printed on premium paper |
$.ajax({ url: "https://api.cloudsto.re/core/publisher", contentType: 'application/x-www-form-urlencoded', dataType: 'json', type: 'POST', data: JSON.stringify({“APIKey”:“x-a3A1qLrXStYDgThU3dfA”}), success: function(response) { $.each(response.Medias, function(index, value) { // process returns }); }, error: function(err) { // handle error } });
$curl -d '{"APIKey" : "x-a3A1qLrXStYDgThU3dfA"}' \ -X POST https://api.cloudsto.re/core/publisher
Request a specific or list of all business information associated with this account’s publisher.
Only accounts with publisher privilege are allowed to get business information.
{ "APIKey": "x-a3A1qLrXStYDgThU3dfA", "BusinessID" : "BS-14" }
Name | Type | Description | Required |
---|---|---|---|
APIKey | string | Authorisation key unique to account | Yes |
BusinessID | string | Business ID, if missing or empty list of all businesses is returned | No |
{ "Count":1, "Business":[ { "PublisherID" : "PB-15" "BusinessID":"BS-27", "BusinessName":"Online Business", "CurrencyCode": "GBP", "CostFactorB": 1.2, "Available" : true } ] }
Name | Type | Description |
---|---|---|
Count | integer | Count of items returned |
Business | array | List of Business Information (objects) |
PublisherID | string | Publisher ID |
BusinessID | string | Business ID |
BusinessName | string | Business Name |
CurrencyCode | string | GBP, USD or EUR |
CostFactorB | float | Additional Business factor cost |
Available | boolean | Specifies if Paper Media is Available to use. |
$.ajax({ url: "https://api.cloudsto.re/core/publisher/business", contentType: 'application/x-www-form-urlencoded', dataType: 'json', type: 'POST', data: JSON.stringify({“APIKey”:“x-a3A1qLrXStYDgThU3dfA”}), success: function(response) { $.each(response.Medias, function(index, value) { // process returns }); }, error: function(err) { // handle error } });
$curl -d '{"APIKey" : "x-a3A1qLrXStYDgThU3dfA"}' \ -X POST https://api.cloudsto.re/core/publisher/business
Request a list of all paper media information associated with this account’s publisher.
Only accounts with publisher privilege are allowed to get paper media information.
{ "APIKey": "x-a3A1qLrXStYDgThU3dfA" }
Name | Type | Description | Required |
---|---|---|---|
APIKey | string | Authorisation key unique to account | Yes |
{ "Count":1, "Medias":[ { "MediaID":"MD-27", "MediaName":"Standard Paper", "CostValue": 50.0, "CostUnit": 5, "FixedCostValue": 0, "MediaFactor": 1, "Premium":false, "Available" : true } ] }
Name | Type | Description |
---|---|---|
Count | integer | Count of items returned |
Medias | array | List of Paper Media Information (objects) |
MediaID | string | Media ID |
MediaName | string | Name of media. |
CostValue | float | Paper Royalty cost value per cost unit (specified below) based on publisher currency. |
CostUnit | integer | Cost Unit for Cost Value (specified above). The valid values are:1 : Square Millimetre
2 : Square Centimetre 3 : Square Inch 5 : Square Meter 6 : Square Foot |
FixedCostValue | float | Specify a fixed cost value added to media printed at any size, based on publisher currency. |
MediaFactor | float | Additional Media factor cost |
Premium | boolean | Specifies if Paper Media is Premium. If true the image premium factor is applied to royalty pricing for this paper type. |
Available | boolean | Specifies if Paper Media is Available to use. |
$.ajax({ url: "https://api.cloudsto.re/core/publisher/medias", contentType: 'application/x-www-form-urlencoded', dataType: 'json', type: 'POST', data: JSON.stringify({“APIKey”:“x-a3A1qLrXStYDgThU3dfA”}), success: function(response) { $.each(response.Medias, function(index, value) { // process returns }); }, error: function(err) { // handle error } });
$curl -d '{"APIKey" : "x-a3A1qLrXStYDgThU3dfA"}' \ -X POST https://api.cloudsto.re/core/publisher/medias
Add a new publisher paper media.
Only accounts with publisher privilege are allowed to update publisher paper media parameters.
{ "APIKey": "x-a3A1qLrXStYDgThU3dfA", "MediaName" : "Standard Paper", "MediaFactor" : 1.0, "Premium" : false, "CostValue" : 40.50 "CostUnit" : 5, "FixedCostValue" : 10, "Available" : true }
Name | Type | Description | Required |
---|---|---|---|
APIKey | string | Authorisation key unique to account | Yes |
MediaName | string | Media Name | No |
MediaFactor | float | additional factor applied to paper cost | No |
CostValue | float | Media Royalty cost value per cost unit (specified below) based on publisher currency. Ignored if CostUnit is missing. | No |
CostUnit | integer | Specify the Cost Unit for Cost Value (specified above).Ignored if CostValue is missing. The valid values are:
1 : Square Millimetre 2 : Square Centimetre 3 : Square Inch 5 : Square Meter 6 : Square Foot |
No |
FixedCostValue | float | Specify a fixed cost value added to media printed at any size, based on publisher currency. | No |
Premium | boolean | Specify if image premium factor is applied to image royalty when printed on this paper. | No |
Available | boolean | Specify if paper media is available to use. Default is false. | No |
{ PaperMediaID: 'PM-100' }
Name | Type | Description |
---|---|---|
PaperMediaID | string | On successful add, newly created Paper Media ID is returned. |
$.ajax({ url: "https://api.cloudsto.re/core/publisher/medias/add", contentType: 'application/x-www-form-urlencoded', dataType: 'json', type: 'POST', data: JSON.stringify({“APIKey”:“x-a3A1qLrXStYDgThU3dfA”,"MediaName":"Paper","MediaFactor" : 1.25}), success: function(response) { // process returns }, error: function(err) { // handle error } });
$curl -d '{“APIKey”:“x-a3A1qLrXStYDgThU3dfA”,"MediaName":"Paper", "MediaFactor" : 1.25}' \ -X POST https://api.cloudsto.re/core/publisher/medias/add
Remove a publisher paper media.
Only accounts with publisher privilege are allowed to update publisher paper media parameters.
{ "APIKey": "x-a3A1qLrXStYDgThU3dfA", "MediaID": "PM-27" }
Name | Type | Description | Required |
---|---|---|---|
APIKey | string | Authorisation key unique to account | Yes |
MediaID | string | Valid Papaer Media ID | Yes |
{
Message: 'Success!'
}
Name | Type | Description |
---|---|---|
Message | string | On successful remove set to ‘Success!’ or if Media ID is invalid set to ‘Media ID Not Found!” |
$.ajax({ url: "https://api.cloudsto.re/core/publisher/medias/remove", contentType: 'application/x-www-form-urlencoded', dataType: 'json', type: 'POST', data: JSON.stringify({“APIKey”:“x-a3A1qLrXStYDgThU3dfA”,"MediaID":"PM-27"}), success: function(response) { // process returns }, error: function(err) { // handle error } });
$curl -d '{“APIKey”:“x-a3A1qLrXStYDgThU3dfA”,"MediaID":"PM-27"}' \ -X POST https://api.cloudsto.re/core/publisher/medias/remove
Update information about publisher paper media.
Only accounts with publisher privilege are allowed to update publisher paper media parameters.
{ "APIKey": "x-a3A1qLrXStYDgThU3dfA", "MediaID": "PM-27", "MediaName" : "Standard Paper", "MediaFactor" : 1.0, "Premium" : false, "CostValue" : 40.50 "CostUnit" : 5, "FixedCostValue" : 10, "Available" : true }
Name | Type | Description | Required |
---|---|---|---|
APIKey | string | Authorisation key unique to account | Yes |
MediaID | string | Valid Papaer Media ID | Yes |
MediaName | string | Media Name | No |
MediaFactor | float | additional factor applied to paper cost | No |
CostValue | float | Media Royalty cost value per cost unit (specified below) based on publisher currency. Ignored if CostUnit is missing. | No |
CostUnit | integer | Specify the Cost Unit for Cost Value (specified above).Ignored if CostValue is missing. The valid values are:
1 : Square Millimetre 2 : Square Centimetre 3 : Square Inch 5 : Square Meter 6 : Square Foot |
No |
FixedCostValue | float | Specify a fixed cost value added to media printed at any size, based on publisher currency. | No |
Premium | boolean | Specify if image premium factor is applied to image royalty when printed on this paper. | No |
Available | boolean | Specify if paper media is available to use. | No |
{
Message: 'Success!'
}
Name | Type | Description |
---|---|---|
Message | string | On successful update set to ‘Success!’ |
$.ajax({ url: "https://api.cloudsto.re/core/publisher/medias/update", contentType: 'application/x-www-form-urlencoded', dataType: 'json', type: 'POST', data: JSON.stringify({“APIKey”:“x-a3A1qLrXStYDgThU3dfA”,"MediaID":"PM-27","MediaFactor" : 1.25}), success: function(response) { // process returns }, error: function(err) { // handle error } });
$curl -d '{“APIKey”:“x-a3A1qLrXStYDgThU3dfA”,"MediaID":"PM-27", "MediaFactor" : 1.25}' \ -X POST https://api.cloudsto.re/core/publisher/medias/update
Update information about publisher.
Only accounts with publisher privilege are allowed to update publisher parameters.
{ "APIKey": "x-a3A1qLrXStYDgThU3dfA", "FactorP" : 1.25, "CurrencyExchangeGBP" : 1.0, "CurrencyExchangeEUR" : 1.15, "CurrencyExchangeUSD" : 1.25, "CostValue" : 40.50 "CostUnit" : 5, "FixedCostValue" : 10, "PremiumFactor" : 1.2 }
Name | Type | Description | Required |
---|---|---|---|
APIKey | string | Authorisation key unique to account | Yes |
FactorP | float | Publisher factor | No |
CurrencyExchangeGBP | float | GBP Exchange rate factor | No |
CurrencyExchangeEur | float | EUR Exchange rate factor | No |
CurrencyExchangeUSD | float | USD Exchange rate factor | No |
CostValue | float | Image Royalty cost value per cost unit (specified below) based on publisher currency. Ignored if CostUnit is missing. | No |
CostUnit | integer | Specify the Cost Unit for Cost Value (specified above).Ignored if CostValue is missing. The valid values are:
1 : Square Millimetre 2 : Square Centimetre 3 : Square Inch 5 : Square Meter 6 : Square Foot |
No |
FixedCostValue | float | Specify a fixed cost value added to image printed at any size, based on publisher currency. | No |
PremiumFactor | float | Specify factor applied to image royalty when printed on premium paper | No |
{
Message: 'Success'
}
Name | Type | Description |
---|---|---|
Message | string | On successful update set to ‘Success’ |
$.ajax({ url: "https://api.cloudsto.re/core/publisher/update", contentType: 'application/x-www-form-urlencoded', dataType: 'json', type: 'POST', data: JSON.stringify({“APIKey”:“x-a3A1qLrXStYDgThU3dfA”,"FactorP" : 1.25}), success: function(response) { // process returns }, error: function(err) { // handle error } });
$curl -d '{“APIKey”:“x-a3A1qLrXStYDgThU3dfA”,"FactorP" : 1.25}' \ -X POST https://api.cloudsto.re/core/publisher/update
Publisher level users have access to the secure Vault for listing, uploading and image manipulation.
The Vault data model is a flat structure: a publisher has a unique Vault, and the vault stores image objects. There is no hierarchy of sub-vaults or sub-folders. However, you can infer logical hierarchy using key name prefixes. Suppose that your Vault has four objects with the following object keys:
Artist-1/portrait-675.jpg Artist-2/london-543.tiff Private/sea-6754.jpg aeroplane.jpg
The key name prefixes (Artist-1/, Artist-2/, and Private/) and delimiter (‘/’) are used to infer hierarchy and introduce the concept of folders.
Request removal of an uploaded image. this request will delete the image file, thumbnail and associated entry in images database.
Only images that have not been used in jobs or user galleries can be deleted.
Only accounts with Publisher right and the owner of the uploaded image is allowed to delete the image.
{ "APIKey": "x-a3A1qLrXStYDgThU3dfA", "PublisherID" : "15", "ImageID" : "IM-22" }
Name | Type | Description | Required |
---|---|---|---|
APIKey | string | Authorisation key unique to account | Yes |
PublisherID | string | Image Publisher ID | Yes |
ImageID | string | Image ID | Yes |
{ "Message": "Success" }
Name | Type | Description |
---|---|---|
Message | string | On successful deletion of image = “Success” |
$.ajax({ url: "https://api.cloudsto.re/core/vault/remove", contentType: 'application/x-www-form-urlencoded', dataType: 'json', type: 'POST', data: JSON.stringify({“APIKey”:“x-a3A1qLrXStYDgThU3dfA”,"PublisherID":"15","ImageID : "IM-22"}), success: function(response) { // process returns }, error: function(err) { // handle error } });
cURL Example
$curl -d '{“APIKey”:“x-a3A1qLrXStYDgThU3dfA”,"PublisherID":"15","ImageID : "IM-22"}' \ -X POST https://api.cloudsto.re/core/vault/remove
Update information about an uploaded image.
{
"APIKey": "x-a3A1qLrXStYDgThU3dfA",
"PublisherID" : "PB-123",
"ImageID" : "IM-342",
"ImageAvailable" : true,
"Artist" : "Frans Deerek",
"Category" : "Skyline",
"ItemName" : "Sky Portrait",
"Reference" : "XD1234",
"CostValue" : 40.50
"CostUnit" : 5,
"PrintLimit" : 100,
"MaxPrintSize : 250,
"Tags_en" : [ "sky", "Sun", "Sea"],
"Tags_it" : []
}
Name | Type | Description | Required |
---|---|---|---|
APIKey | string | Authorisation key unique to account | Yes |
PublisherID | string | Image Publisher ID | Yes |
ImageID | string | Image ID | Yes |
ImageAvailable | boolean | set image availability online: true or false | No |
Artist | string | Artist Name | No |
ItemName | string | Image Name/Title | No |
Reference | string | Reference value set for image | No |
Category | string | Image Category | No |
CostValue | float | Image Royalty cost value per cost unit (specified below) based on publisher currency. Ignored if CostUnit is missing. | No |
CostUnit | integer | Specify the Cost Unit for Cost Value (specified above).Ignored if CostValue is missing. The valid values are:
1 : Square Millimetre 2 : Square Centimetre 3 : Square Inch 5 : Square Meter 6 : Square Foot |
No |
FixedCostValue | float | Specify a fixed cost value added to image printed at any size, based on publisher currency. | No |
PrintLimit | integer | Set Limited Edition by specifying a positive value Print Limit for total number of prints allowed. | No |
MaxPrintSize | integer | Maximum size the image can be printed. Specify in percentage of original image size. For example To allow up to 2x the original size set to 200. | No |
Tags_en | array | array of strings specifying list of English keywords/tags for the image. Use an empty array to remove existing tags | No |
Tages_de | array | array of strings specifying list of German keywords/tags for the image. Use an empty array to remove existing tags | No |
Tags_fr | array | array of strings specifying list of French keywords/tags for the image. Use an empty array to remove existing tags | No |
Tags_it | array | array of strings specifying list of Italian keywords/tags for the image. Use an empty array to remove existing tags | No |
Tags_es | array | array of strings specifying list of Spanish keywords/tags for the image. Use an empty array to remove existing tags | No |
Tags_nl | array | array of strings specifying list of Dutch keywords/tags for the image. Use an empty array to remove existing tags | No |
{
Message: 'Success'
}
Name | Type | Description |
---|---|---|
Message | string | On successful update set to ‘Success’ |
$.ajax({
url: "https://api.cloudsto.re/core/vault/update",
contentType: 'application/x-www-form-urlencoded',
dataType: 'json',
type: 'POST',
data: JSON.stringify({“APIKey”:“x-a3A1qLrXStYDgThU3dfA”,"PublisherID" : "PB-123","ImageID" : "IM-342","ImageAvailable" : true}),
success: function(response) {
// process returns
},
error: function(err) {
// handle error
}
});
$curl -d '{“APIKey”:“x-a3A1qLrXStYDgThU3dfA”,"PublisherID" : "PB-123","ImageID" : "IM-342","ImageAvailable" : true}' \
-X POST https://api.cloudsto.re/core/vault/update
The process of upload of an image involves a time sequence events starting by requesting an upload of an image. The following time sequence diagram shows the sequence of events involved in the upload of an image.
The upload request call can contain one or more request for upload with the Image Keys specifying the path including the file name. The return from API call will contain a time-limited authorized upload link for each Image Key requested. This link is valid for 60 minutes and gives full access to upload a binary image. Example of uploads are shown below. Once the files have been uploaded, the system will process and add to catalogue. The images are typically available within minutes.
Only accounts with publisher privilege are allowed to upload images.
Each image object has a key. Image key (or key name) uniquely identifies the object in the Vault.
When you upload an image, you specify the key name, which uniquely identifies the image object in the Vault. These names are the object keys. The name for a key is a sequence of Unicode characters whose UTF-8 encoding should at most be 1024 bytes long.
AutoTag Image facility is a Deep Learning powered Image Recognition service that detects objects, scenes, and faces; it also extracts text and recognises celebrities. AutoTag Image service identifies thousands of objects such as vehicles, pets, and furniture. AutoTag service also detects scenes within an image, such as a sunset or beach. The service is continually trained on new data to expand its ability to recognise objects, scenes, and activities to improve its ability to accurately analyse images.
This service makes it easy to generate tags for large image libraries. The upload call can request the use of AutoTag service to automatically generate tags for the uploaded image. The tags are also automatically translated to all supported languages.
The upload service can also read the image metadata and extract EXIF tags to populate image information. Currently the following tags are recognised and used in the image information:
EXIF Tag | AOD Field |
---|---|
artist | Artist Name |
imageDescription | Item Name |
The following restrictions on uploaded file is currently in place:
Formats Supported | JPEG & TIFF |
Maximum File Size | 200 MB |
Concurrent Requests | 100 |
Image Key | Each image object has a key. Image key (or key name) uniquely identifies the object in the Vault. See section above about naming limitations. |
{ "APIKey": "x-a3A1qLrXStYDgThU3dfA", "ImageKeys" : [ { "ImageKey" : "Artist-1/portrait-675.jpg", "AutoTag" : true, "AutoExif" : false, "ArtistName" : "John Pierre", "ItemName" : "Day at sea", "Category" : "Pop Art", "CostValue" : 40.0, "CostUnit" : 5, "PrintLimit" : 30, "MaxPrintSize" : 250 }, { "ImageKey" : "Artist-2/london-543.tiff", "Reference" : "XY0987-DE", "Tags_en" : ["sea", "sun", "beach", "water"] "Tags_de" : ["sitz", "sonne", "strand", "wasser"] }, { "ImageKey" : "Private/sea-6754.jpg", "Tags_es" : ["noche", "cielo", "ciudad"] }, { "ImageKey" : "aeroplane.jpg" } ] }
Name | Type | Description | Required |
---|---|---|---|
APIKey | string | Authorisation key unique to account | Yes |
ImageKeys | array | array (objects) of image details to upload. At least one Image Key is required for the call. | Yes |
ImageKey | string | Image Key specifies the upload file name and path and is used as the key to identify the image upload. Must not be empty string. | Yes |
NoUpload | boolean | request the file is not uploaded if already exists and only update parameters. Default is false. | No |
AutoTag | boolean | request AutoTag service to generate tags automatically. Default is false. | No |
AutoExif | boolean | request AutoExif service to read image metadata and extract EXIF parameters automatically. Default is false. | No |
Reference | string | Image reference in AOD database. If not specified the image file basename is used as default reference. | No |
ItemName | string | Item Name/Title describing the image | No |
ArtistName | string | Artist Name | No |
Category | string | Image Category Name | No |
CostValue | float | Image Royalty cost value per cost unit (specified below) based on publisher currency. If not present (default), this value is taken from base publisher data. | No |
CostUnit | integer | Specify the Cost Unit for Cost Value (specified above). If not present (default), this value is taken from base publisher data. If present but CostValue not present this is ignored. The valid values are:
1 : Square Millimetre 2 : Square Centimetre 3 : Square Inch 5 : Square Meter 6 : Square Foot |
No |
FixedCostValue | float | Specify a fixed cost value added to image printed at any size. If not present (default), this value is taken from base publisher data. | No |
PrintLimit | integer | Set Limited Edition by specifying a positive value Print Limit for total number of prints allowed. Default is open edition and not print limited. | No |
MaxPrintSize | float | Maximum size the image can be printed. Specify in percentage of original image size. For example to allow the image to be printed up to four times the size, set to 400. If not present (default), this value is taken from base publisher data. | No |
Tags_en | array | Array of strings that contains the English language tags/keywords for the image. If AutoTag is true, the generated tags will be added to these. | No |
Tags_de | array | Array of strings that contains the German language tags/keywords for the image. If AutoTag is true, the generated tags are translated and added to these. | No |
Tags_es | array | Array of strings that contains the Spanish language tags/keywords for the image. If AutoTag is true, the generated tags are translated and added to these. | No |
Tags_fr | array | Array of strings that contains the French language tags/keywords for the image. If AutoTag is true, the generated tags are translated and added to these. | No |
Tags_it | array | Array of strings that contains the Italian language tags/keywords for the image. If AutoTag is true, the generated tags are translated and added to these. | No |
Tags_nl | array | Array of strings that contains the Dutch language tags/keywords for the image. If AutoTag is true, the generated tags are translated and added to these. | No |
{ "Count": 4, "ImageKeys":[ { "ImageKey" : "Artist-1/portrait-675.jpg", "Existing": false, "URL" : "https://aodupload.s3.eu-west-1.amazonaws.com/Publisher-XY/315d83d3-6a0d-44af-bcfd-c6d9845b2af3?AWSAccessKeyId=ASIA4LJIRF2XWYM4JIOU&Content-Type=image%2Fjpeg&Expires=1564753951&Signature=vqiHebQ82wwXWY2%2BeH6oLrVS2Aw%3D&x-amz-security-token=keaKcVr3KulyUGOQIgVhkXcB%2Fuk%2BVOItNR181%2BoXDH53wD3B5oaV0lRbzefUgqnAII1v", }, { "ImageKey" : "Artist-2/london-543.tiff", "Existing": false, "URL" : "https://aodupload.s3.eu-west-1.amazonaws.com/Publisher-XY/09865d83d3-6a0d-88af-bcfd-7856fdb2af3?AWSAccessKeyId=ASIA4LJIRF2XWYM4JIOU&Content-Type=image%2Ftiff&Expires=1564753951&Signature=vqiHebQ82wwXWY2%2BeH6oLrVS2Aw%3D&x-amz-security-token=KcVr3KulyUGOQIgVhkXcB%2Fuk%2BVOItNR181%2BoXDH53wD3B5oaV0lRbzefUgqnAII1v", }, { "ImageKey" : "Private/sea-6754.jpg", "Existing": false, "URL" : "https://aodupload.s3.eu-west-1.amazonaws.com/Publisher-XY/456265d83d3-6a0d-893f-bcfd-78098fse2af3?AWSAccessKeyId=ASIA4LJIRF2XWYM4JIOU&Content-Type=image%2Fjpeg&Expires=1564753951&Signature=vqiHebQ82wwXWY2%2BeH6oLrVS2Aw%3D&x-amz-security-token=keaKcVr3KulyUGOQIgVhkXcB%2Fuk%2BVOItNR181%2BoXDH53wD3B5oaV0lRbzefUgqnAII1v", }, { "ImageKey" : "aeroplane.jpg", "Existing": true, "URL" : "https://aodupload.s3.eu-west-1.amazonaws.com/Publisher-XY/456278643d3-6a7g-89f3f-bdfd-783428fse2af3?AWSAccessKeyId=ASIA4LJIRF2XWYM4JIOU&Content-Type=image%2Fjpeg&Expires=1564753951&Signature=vqiHebQ82wwXWY2%2BeH6oLrVS2Aw%3D&x-amz-security-token=keaKcVr3KulyUGOQIgVhkXcB%2Fuk%2BVOItNR181%2BoXDH53wD3B5oaV0lRbzefUgqnAII1v", } ] }
Name | Type | Description |
---|---|---|
Count | integer | Count of items returned. |
ImageKeys | array | List of ImageKey Information (objects) |
ImageKey | string | Image key requested |
Existing | boolean | Flag indicating if the image key exists in the vault. Uploading to the provided link will override existing image and its current data. The calling client should decide to proceed to override existing image. |
URL | string | Time limited secure upload link for the image binary data.
If NoUpload flag was set in the request and image file already exists, no URL will be returned. |
Request Upload $.ajax({ url: "https://api.cloudsto.re/core/vault/upload", contentType: 'application/x-www-form-urlencoded', dataType: 'json', type: 'POST', data: JSON.stringify({“APIKey”:“x-a3A1qLrXStYDgThU3dfA”,"ImageKeys":[{"ImageKey" : "testfile.jpg","Reference" : "XYPCD"}]}), success: function(response) { $.each(response.Transactions, function(index, value) { // process returns }); }, error: function(err) { // handle error } }); Upload File $.ajax({ url: "https://aodupload.s3.eu-west-1.amazonaws.com/Publisher-XY/456265d83d3-6a0d-893f-bcfd-78098fse2af3?AWSAccessKeyId=ASIA4LJIRF2XWYM4JIOU&Content-Type=image%2Fjpeg&Expires=1564753951&Signature=vqiHebQ82wwXWY2%2BeH6oLrVS2Aw%3D&x-amz-security-token=keaKcVr3KulyUGOQIgVhkXcB%2Fuk%2BVOItNR181%2BoXDH53wD3B5oaV0lRbzefUgqnAII1v", type: 'PUT', data: file, processData: false, headers: {'Content-Type': 'image/jpeg'}, success: function (response) { // call success } }).done(function (data) { // upload done }).fail(function (arg1, arg2) { // upload fail });
Request Upload $curl -d '{"APIKey" : "x-a3A1qLrXStYDgThU3dfA","ImageKeys":[{"ImageKey" : "testfile.jpg","Reference" : "XYPCD"}]}' \ -X POST https://api.cloudsto.re/core/vault/upload Upload File $curl -H "Content-Type: image/jpeg" --upload-file imagefile.jpg "https://aodupload.s3.eu-west-1.amazonaws.com/Publisher-XY/456265d83d3-6a0d-893f-bcfd-78098fse2af3?AWSAccessKeyId=ASIA4LJIRF2XWYM4JIOU&Content-Type=image%2Fjpeg&Expires=1564753951&Signature=vqiHebQ82wwXWY2%2BeH6oLrVS2Aw%3D&x-amz-security-token=keaKcVr3KulyUGOQIgVhkXcB%2Fuk%2BVOItNR181%2BoXDH53wD3B5oaV0lRbzefUgqnAII1v"
As part of the upload feature we have an online import facility for uploading images from web browser. You are able to fill a template (csv) file with associated data for the images and use that as part of the upload from cloudsto.re console under your own account.
Note: to use the import facility, you need to upload a CSV (.csv) file with UTF-8 encoding and comma (,) as field separator.
The console provides the facility to export an empty template (csv) file with correct heading and list of selected files. First select the files you wish to upload, use the export facility to create an empty template and then fill the template file with information about images. You can then Upload images with the associated template file which will populate the database with the provided information.
The following table describes the fields and the format of the data required. If you do not want to provide data for a field, leave it blank (the comma separator should exist for each field). The header line describing the fields should exist as first line. Enter data for each image one per line after the header.
A useful tool for working with csv files is Microsoft® Excel™ (remember to save as csv format with UTF-8 encoding).
Field | Description |
---|---|
FileName | Actual file name including any extensions from local directory. If you have exported the template file, this field should be already populated.
Example: MD_IR6765.jpg |
ImageKey | Path and name of the destination file in the Vault. All image keys are relative to root of the Vault. Image key can be different from file name, although recommended to keep the same to match files in your local storage. If the image key exists, it will be over written and its data reset to new data.
This field is case sensitive and differences in case will result in new entries. Example: artist-1/latest/MD_IR6765.jpg the file will be stored relative to vault root in sub-folders artist-1/latest/ |
Reference | Image reference allocated in AOD system which will be shown to users as image reference. If left empty the file base-name (without extension) will be used as default reference. You may wish to have your own reference system or SKU to allocate to images here.
Example: IM123 if the field is empty then reference would be the file base name : MD_IR675 |
ArtistName | Artist Name
Example: Arian Spencer |
ItemName | Image Name/Title
Example: Nightlife |
Category | Image Category
Example: Abstract |
CostValue | Image Royalty cost value per cost unit (specified below) based on publisher currency. If not present (default), this value is taken from base publisher data.
Example : 40.5 |
CostUnit | Specify the Cost Unit for Cost Value (specified above). If not present (default), this value is taken from base publisher data. If present but CostValue not present this is ignored. The valid values are:
1 : Square Millimetre 2 : Square Centimetre 3 : Square Inch 5 : Square Meter 6 : Square Foot Example : 5 |
FixedCostValue | Specify a fixed cost value added to image printed at any size. If not present (default), this value is taken from base publisher data.
Example : 5.0 |
PrintLimit | Set Limited Edition by specifying a positive value Print Limit for total number of prints allowed. Default is open edition and not print limited.
Example : 30 |
MaxPrintSize | Maximum size the image can be printed. Specify in percentage of original image size. If not present (default), this value is taken from base publisher data.
Example : 400 This allows the image to be printed up to 4 times bigger than the original size. |
NoUpload | a Boolean flag to enable/disable “No image upload” and/or update of parameters only if the image has already been uploaded. Default is false(off)
Example : false the system will upload image even if the file exists in Vault. Example: true The system will not upload image if already uploaded and update parameters only. The flag is ignored if the image has not been uploaded. |
AutoTag | a Boolean flag to enable auto image recognition to generate automatic keywords/tags by analysing the image (see upload section for more details about this feature). Default is false (off)
Example : true by setting this field to true the system will analyse the images and generate keywords/tags (currently only in English) |
AutoExif | a Boolean flag to enable auto metadata recognition by analysing the image EXIF data (see upload section for more details about this feature). Default is false (off)
Example : true by setting this field to true the system will analyse the image exif and generate certain data automatically |
Tags_en | list of English keywords/tags for the image. Separate each keyword/tag using a | separator.
Example: night|sky light|building|city if AutoTag is enabled these will be added to the auto generated tags |
Tags_de | list of German Keywords/Tags for the image.
See Tags_en for details |
Tags_fr | list of French Keywords/Tags for the image.
See Tags_en for details |
Tags_es | list of Spanish Keywords/Tags for the image.
See Tags_en for details |
Tags_it | list of Italian Keywords/Tags for the image.
See Tags_en for details |
Tags_nl | list of Dutch Keywords/Tags for the image.
See Tags_en for details |
FileName,ImageKey,Reference,ArtistName,ItemName,Category,CostValue,CostUnit,FixedCostValue,PrintLimit,MaxPrintSize,AutoTag,AutoExif,Tags_en,Tags_de,Tags_es,Tags_fr,Tags_it,Tags_nl li-yang-138248-unsplash.jpg,test/li-yang-138248-unsplash.jpg,138248,Li Yang,Shanghai,Landscape,,,,,,true,,city|sky|night life|skyscraper,,,, Gullwing.jpg,test/Gullwing.jpg,,,Mercedes,Cars,true,,,,,,
Errors are returned as standard JSON objects using HTTP statusCode. With error status, the error message text can be obtained from the response body. The HTTP response code 200 is success responses, all other response codes are errors. Data will only be returned for HTTP response code 200.
{ statusCode: 400, body: "Invalid Request" }
Code | Status | Description |
---|---|---|
200 | Success | Request successful |
400 | Invalid | Invalid or missing Request Parameters |
401 | Unauthorised | APIKEY not valid |
405 | Invalid Method | HTTP Method not supported |
500 | Database Error | Request caused a database error |
501 | File Error | Request caused a File error |