Welcome to CloudSight API’s documentation!

Consult full API documentation for details.

Installation

$ pip install cloudsight

Configuration

You need your API key and secret (if using OAuth1 authentication). They are available on CloudSight site after you sign up and create a project.

Usage

Import the cloudsight module:

import cloudsight

Create an cloudsight.API instance using simple key-based authentication:

auth = cloudsight.SimpleAuth('your-api-key')
api = cloudsight.API(auth)

Or, using OAuth1 authentication:

auth = cloudsight.OAuth('your-api-key', 'your-api-secret')
api = cloudsight.API(auth)

Send the image request using a file:

with open('your-file.jpg', 'rb') as f:
    response = api.image_request(f, 'your-file.jpg', {
        'image_request[locale]': 'en-US',
    })

Or, you can send the image request using a URL:

response = api.remote_image_request('http://www.example.com/image.jpg', {
    'image_request[locale]': 'en-US',
})

Then, update the job status to see if it’s already processed:

status = api.image_response(response['token'])
if status['status'] != cloudsight.STATUS_NOT_COMPLETED:
    # Done!
    pass

It usually takes 6-12 seconds to receive a completed response. You may use cloudsight.API.wait() method to wait until the image is processed:

status = api.wait(response['token'], timeout=30)

API parameters

image_request[image] (required)
Image attached as a multipart-form-request part. Either this field or image_request[remote_image_url] must be provided, but not both.
image_request[remote_image_url] (required)
URL to a remote image to use. Either this field or the image_request[image] must be provided, but not both.
image_request[locale] (required)
The locale of the request.
image_request[language]
The language of the request. Return the response in this language.
image_request[device_id]
A unique ID generated for the device sending the request. We recommend generating a UUID.
image_request[latitude]
Geolocation information for additional context.
image_request[longitude]
Geolocation information for additional context.
image_request[altitude]
Geolocation information for additional context.
image_request[ttl]
Deadline in seconds before expired state is set. Use a high ttl for low-priority image requests. Set image_request[ttl]=max for maximum deadline.
focus[x]
Focal point on image (x-coordinate) for specificity.
focus[y]
Focal point on image (y-coordinate) for specificity.

API documentation

Possible values for current job status:

cloudsight.STATUS_NOT_COMPLETED

Recognition has not yet been completed for this image. Continue polling until response has been marked completed.

cloudsight.STATUS_COMPLETED

Recognition has been completed. Annotation can be found in Name and Categories field of Job structure.

cloudsight.STATUS_NOT_FOUND

Token supplied on URL does not match an image.

cloudsight.STATUS_SKIPPED

Image couldn’t be recognized because of a specific reason. Check the reason field.

cloudsight.STATUS_TIMEOUT

Recognition process exceeded the allowed TTL setting.

The API may choose not to return any response for given image. Below constants include possible reasons for such behavior.

cloudsight.REASON_OFFENSIVE

Offensive image content.

cloudsight.REASON_BLURRY

Too blurry to identify.

cloudsight.REASON_CLOSE

Too close to identify.

cloudsight.REASON_DARK

Too dark to identify.

cloudsight.REASON_BRIGHT

Too bright to identify.

cloudsight.REASON_UNSURE

Content could not be identified.

class cloudsight.API(auth)
__init__(auth)

API instance constructor.

Parameters:auth – Instance of Auththorization handler (cloudsight.SimpleAuth or cloudsight.OAuth).
image_request(image, filename, params=None)

Send an image for classification. The image is a file-like object. The params parameter is optional.

On success this method will immediately return a job information. Its status will initially be cloudsight.STATUS_NOT_COMPLETED as it usually takes 6-12 seconds for the server to process an image. In order to retrieve the annotation data, you need to keep updating the job status using the cloudsight.API.image_response() method until the status changes. You may also use the cloudsight.API.wait() method which does this automatically.

Parameters:
  • image – File-like object containing the image data.
  • filename – The file name.
  • params – Additional parameters for CloudSight API.
image_response(token)

Contact the server and update the job status.

After a request has been submitted, it usually takes 6-12 seconds to receive a completed response. We recommend polling for a response every 1 second after a 4 second delay from the initial request, while the status is cloudsight.STATUS_NOT_COMPLETED. cloudsight.API.wait() method does this automatically.

Parameters:token – Job token as returned from cloudsight.API.image_request() or cloudsight.API.remote_image_request()
remote_image_request(image_url, params=None)

Send an image for classification. The imagewill be retrieved from the URL specified. The params parameter is optional.

On success this method will immediately return a job information. Its status will initially be cloudsight.STATUS_NOT_COMPLETED as it usually takes 6-12 seconds for the server to process an image. In order to retrieve the annotation data, you need to keep updating the job status using the cloudsight.API.image_response() method until the status changes. You may also use the cloudsight.API.wait() method which does this automatically.

Parameters:
  • image_url – Image URL.
  • params – Additional parameters for CloudSight API.
repost(token)

Repost the job if it has timed out (cloudsight.STATUS_TIMEOUT).

Parameters:token – Job token as returned from cloudsight.API.image_request() or cloudsight.API.remote_image_request()
wait(token, timeout=600)

Wait for the job until it has been processed. This method will block for up to timeout seconds.

This method will wait for 4 seconds after the initial request and then will call cloudsight.API.image_response() method every second until the status changes.

Parameters:token – Job token as returned from cloudsight.API.image_request() or cloudsight.API.remote_image_request()
class cloudsight.SimpleAuth(key)
class cloudsight.OAuth(key, secret)
class cloudsight.APIError(description)

Indices and tables