NAV Navbar
shell
  • Introduction
  • Authentication
  • API URL
  • Errors
  • FAQ

    • Introduction

    Welcome to the Unleash live API!

    We have two distinct opportunities for developer engagement. Our API for the core Unleash live platform and our A.I. Apps Ecosystem. Learn more about both here.

    Unleash live APIs connect you to all the data you need to build an innovative connected website or app.

    You can use our API to access Unleash API endpoints, which can get information on RESTful resources and media data. Build tools that solve real business problems around the world.

    Authentication

    All requests need to be signed using SIGv4. Resource

    # example: sign request using python
import boto3
import datetime
import json
from requests_aws4auth import AWS4Auth
import requests

boto3.setup_default_session(region_name='us-east-1')
identity = boto3.client('cognito-identity', region_name='us-east-1')

account_id='XXXXXXXXXXXXXXX'
identity_pool_id='us-east-1:YYY-YYYY-YYY-YY'
api_prefix='ZZZZZZZZZ'

response = identity.get_id(AccountId=account_id, IdentityPoolId=identity_pool_id)
identity_id = response['IdentityId']
print ("Identity ID: %s"%identity_id)

resp = identity.get_credentials_for_identity(IdentityId=identity_id)
secretKey = resp['Credentials']['SecretKey']
accessKey = resp['Credentials']['AccessKeyId']
sessionToken = resp['Credentials']['SessionToken']
expiration = resp['Credentials']['Expiration']

print ("\nSecret Key: %s"%(secretKey))
print ("\nAccess Key %s"%(accessKey))
print ("\nSession Token: %s"%(sessionToken))
print ("\nExpiration: %s"%(expiration))

method = 'GET'
headers = {}
body = ''
service = 'execute-api'
url = 'https://%s.execute-api.us-east-1.amazonaws.com/dev/helloworld' % api_prefix
region = 'us-east-1'

auth = AWS4Auth(accessKey, secretKey, region, service, session_token=sessionToken)
response = requests.request(method, url, auth=auth, data=body, headers=headers)
print(response.text)

    Requests made from client code, should be signed using temporary credentials retrieved in the event of user authentication. User authentication is not part of the Unleash API but it's described below as a reference.

    User registration

    Email signup

    On email and password sign up, user is added to Unleash live User Pool. Reference http://docs.aws.amazon.com/cognito/latest/developerguide/tutorial-integrating-user-pools-javascript.html#tutorial-integrating-user-pools-sign-up-users-javascript

    Forgot password

    http://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ForgotPassword.html

    API URL

    https://api.unleashlive.com/v1

    User

    Represents the Unleash User.

    Create a user

    Create new representation of Unleash User.

    API Endpoint

    POST /user

    Parameters

    Name Type Constraints Description
    id string required User's identity id
    username string required Username alias
    fullName string required, max length 100 Name of the user
    email string required, email format User email
    createdAt timestamp (auto generated) item created timestamp
    updatedAt timestamp (auto generated) item updated timestamp

    Get a User

    Retrieve user by ID

    API Endpoint

    GET /user/{id}

     GET /user/{id}

    Parameters

    Name Type Constraints Description
    id string required, uuid format id of the user (URI encoded)

    List users

     GET /user

    List all the users

    API Endpoint

    GET /user

    Update a User

     PATCH /user/{id}

    Replace a given subset of attributes.

    API Endpoint

    PATCH /user/{id}

    Payload

    Name Type Constraints Description
    username string required Username alias
    fullName string required, max length 100 Name of the user

    List user's companies

     GET /user/{id}/company

    List all companies that user has been assigned to.

    API Endpoint

    GET /user/{id}/company

    Path parameters

    Name Type Constraints Description
    id string required, uuid format id of the user (URI encoded)

    To upload a company logo, you need to call API to request a presigned URL and then upload it directly to s3 using the given url.

     POST /user/uploadLogo

    Logo stored location

    Company logos are saved in the following path: /pylot/${identityId}/${companyId}/${filename}

    API Endpoint

    POST /user/uploadLogo

    Parameters

    Name Type Constraints Description
    companyId string required id of the company
    filename string required logo file name

    Add device to a user

    Assign a device to a user

    API Endpoint

    POST /user/{id}/device/

    Path parameters

    Name Type Constraints Description
    id string required, uuid format id of the user (URI encoded)

    Payload

    Name Type Constraints Description
    deviceId string required device id

    List user's devices

     GET /user/{id}/device

    List all devices that user has been assigned to.

    API Endpoint

    GET /user/{id}/company

    Path parameters

    Name Type Constraints Description
    id string required, uuid format id of the user (URI encoded)

    Get user stream model

    API Endpoint

    GET /user/{token}/model

     GET /user/{token}/model

    Parameters

    Name Type Constraints Description
    token string required user's stream token

    Response

        {
      modelId: '0001',
      modelName: 'Default',
      pbPath: 'stream_test/default.pb',
      pbTxtPath: 'stream_test/default.pbtxt',
    };

    Device

    Represents single device: aircraft, camera etc.

    Create a device

    Creates new device item

    API Endpoint

    POST /device

    Parameters

    Name Type Constraints Description
    id string, uuid (optionally auto generated) unique hardware serial, autogenerated if not provided
    owner string (auto generated) The identityId of device owner
    name string max length 100, (optionally auto generated) Name of the device, autogenerated if not provided
    description string optional Description
    hwstats string optional Hardware stats
    usage string optional Usage data
    createdAt timestamp (auto generated) item created timestamp
    updatedAt timestamp (auto generated) item updated timestamp

    Get a Device

    Retrieve device by ID

    API Endpoint

    GET /device/{id}

     GET /device/{id}

    Parameters

    Name Type Constraints Description
    id string required, uuid format id of the device

    List devices

     GET /device

    List all the devices

    API Endpoint

    GET /device

    Update a device

     PATCH /device/{id}

    Replace a given subset of attributes.

    API Endpoint

    PATCH /device/{id}

    Payload

    Name Type Constraints Description
    name string optional, max length 100 Name of the device
    hwstats string optional, Hardware stats
    description string optional Description
    usage string optional Usage data

    Library

    The API represents methods to integrate user interface with Unleash live S3 storage.

    Upload a media file

    In order to upload file to Unleash live Library, call this endpoint to receive presigned POST url and headers. These will be used to construct a second request to upload the file directly to S3.

    API Endpoint

    POST /library/upload

    Parameters

    Name Type Constraints Description
    deviceId string required the device id used to capture the file
    sessionId string required the session id the file belongs to
    filename string required the name which will be assigned in s3 storage

    List session media files

    Retrieve all images and videos uploaded on a given device in particular session.

    API Endpoint

    GET /library/media/device/{deviceId}/session/{sessionId}

    List device media files

    Retrieve all images and videos uploaded on a given device in any session.

    API Endpoint

    GET /library/media/device/{deviceId}

    List all media files

    Retrieve all images and videos uploaded by user.

    API Endpoint

    GET /library/media/

    List device sessions

    Retrieve list of sessions recorded on a given device.

    API Endpoint

    GET /library/session/device/{deviceId}/

    List solutions

    Retrieve modelling solutions created from photos uploaded on given device and session

    API Endpoint

    GET /library/solution/device/{deviceId}/session/{sessionId}

    Addons

    Represents Unleash live Service addons

    Create a addon

    Creates new addon item. All new addons must be approved by Unleash Development Team.

    API Endpoint

    POST /addon

    Parameters

    Name Type Constraints Description
    id string, uuid (auto generated) database hash id
    name string required addon name
    subtitle string required addon subtitle
    description string required addon description, features available
    developer string required addon's developer name or company name
    logo string required addon logo url
    owner string required addon's author user id
    price string required addon price per month
    currency string optional price currency in standard ISO 4217 - e.g. AUD
    type string optional addon's type. e.g. 'stream'
    screenshots string array optional image url array of addon screenshots
    createdAt timestamp (auto generated) item created timestamp
    updatedAt timestamp (auto generated) item updated timestamp
    data object optional data block for AI enabled addons. See "AI addons"

    Get an addon

    Retrieve addon by ID

    API Endpoint

    GET /addon/{id}

     GET /addon/{id}

    Parameters

    Name Type Constraints Description
    id string required, uuid format id of the addon

    List addons

     GET /addon

    List all the addons

    API Endpoint

    GET /addon

    Update a addon

     PATCH /addon/{id}

    Replace a given subset of attributes.

    API Endpoint

    PATCH /addon/{id}

    Payload

    Name Type Constraints Description
    name string required addon name
    subtitle string required addon subtitle
    description string required addon description, features available
    developer string required addon's developer name or company name
    logo string required addon logo url
    owner string required addon's author user id
    price string required addon price per month
    currency string optional price currency in standard ISO 4217 - e.g. AUD
    type string optional addon's type. e.g. 'stream'
    screenshots string array optional image url array of addon screenshots
    data object optional data block for AI enabled addons. See "AI addons"

    Parameters

    Name Type Constraints Description
    id string required, uuid format id of the addon

    A.I. addons

    Addons that have data part are considered AI addons. Their data block has to be set to specified format below.

    Data block

    Data block specifies parameters that are passed to underlying machine learning solution. The following properties build the data block.

    "data": {
  "classes": 3,
  "clipping": "true",
  "stream": "true",
  "image": "true",
  "pbPath": "animals/animals.pb",
  "pbTxtPath": "animals/animals.pbtxt"
}
    Name Type Constraints Description
    classes number optional number of categories used in the model
    clipping boolean optional true means that we can use this model for media clipping jobs
    stream boolean optional true means we can use this for stream analysis ('default')
    image boolean optional true means we can use this model for image analysis
    pbPath string required path to frozen graph definition
    pbTxtPath string required path to textual graph definition

    Deploying A.I. addon

    1. Read the FAQs
    2. Create addon, upload model pb and pbTxt files via your developer Sandox within your Unleash live account.
    3. Test addon in your Sandbox.
    4. Submit for approval.

    Unleash live Recognition

    Once you have created and uploaded your A.I. App, we let you trigger A.I. processing jobs.

    Start A.I. job

    Trigger any kind of A.I. processing jobs using this endpoint. Provide the model and the clip length in parameters. This is asynchronous tasks. The response indicates that job has been successfully queued for processing. The results will be available several minutes later. To get addonId see Addons api.

    API endpoint

    POST https://api.unleashlive.com/v0/cv/process

    POST https://api.unleashlive.com/v0/cv/process 
{
    deviceId: 'W123',
    items: [{sessionId: '123', fileName:'test.mp4'}],
    options: {
        addonId: 'A123',
        clipLength: 15
    }
}

    Parameters

    Name Type Constraints Description
    deviceId string required device id
    items.sessionId string required session id of the item
    items.fileName string required file name of the item
    options.addonId string required the id of the model used for processing
    options.clipLength number required the value in seconds of the resulting clips length

    Unleash live Media Tools

    Authentication

    The endpoints are secured with IAM.

    Video crop

    Crop a video within a given time range.

    API endpoint

    POST https://8xbk6rnolh.execute-api.ap-southeast-2.amazonaws.com/dev/media/crop

    POST https://8xbk6rnolh.execute-api.ap-southeast-2.amazonaws.com/dev/media/crop
   {
     "objectKey": "ap-southeast-2:b9be243f-1c1e-4d92-8a72-2cf5fe1dc5a5/BROWSER/session-1506318704930/Riverside.mp4",
     "start": "1",
     "end": "15"
   }

    Parameters

    Name Type Constraints Description
    objectKey string required s3 object key
    start string required start time in seconds
    end string required end time in seconds

    Results

    The result video is saved in the same folder with the name appended with timestamp and uuid

    s3://pylot/ap-southeast-2:b9be243f-1c1e-4d92-8a72-2cf5fe12f5a5/BROWSER/session-1506318704930/Riverside.mp42017-09-27-21-39-62893d96-a3cc-11e7-b790-0242ac110002.mp4

    Video concat

    Merge multiple videos into one.

    API endpoint

    POST https://8xbk6rnolh.execute-api.ap-southeast-2.amazonaws.com/dev/media/concat

    POST https://8xbk6rnolh.execute-api.ap-southeast-2.amazonaws.com/dev/media/concat
   {
     "objectKeys": [
         "ap-southeast-2:b9be243f-1c1e-4d92-8a72-2cf5fe2vf5a5/BROWSER/session-1506318704930/Riverside.mp4",
         "ap-southeast-2:b9be243f-1c1e-4d92-8a72-2cf5fe2vf5a5/BROWSER/session-1506318704930/Riverside2.mp4"
         "ap-southeast-2:b9be243f-1c1e-4d92-8a72-2cf5fe2vf5a5/BROWSER/session-1506318704930/Riverside3.mp4"
     ]
   }

    Parameters

    Name Type Constraints Description
    objectKeys string required array of object keys

    Errors

    The Unlash live API uses the following error codes:

    Error Code Meaning
    400 Bad Request -- Wrong or missing parameters.
    403 Unauthorized -- Your API key is wrong.
    422 Validation failed -- Params content failed validation.
    500 Internal Server Error -- We had a problem with our server. Try again later.
    503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

    The error response format

    {"message":"","name":""}

    FAQ

    Learn about the Unleash live platform features and benefits.

    General Unleash live platform features and functionality

    Why should I use Unleash Live?

    With Unleash live your audience anywhere in the world can be connected to the field operations or events and participate in the decision making process.

    Couple this with our Artificial Intelligence Ecosystem and you have the power to use leading A.I. developers to create industry specific algorithms for even faster results. Saving you time, money and laborious manual activities.

    What plans are available and suitable for me?

    We have designed plans to meet your specific needs. Begin by testing our platform with the starter plan and simply upgrade when your workflow changes.

    For more pricing information get started with your free trial account and adjust your plan on your profile page.

    How do I setup my account?

    Setting up your account is easy. Simply go to https://cloud.unleashlive.com enter your email address and a password to get started. Your verified email address is your user name.

    Once you are logged in you will be directed to your profile page where you can edit your profile, add devices and activate services such as modelling, your media store or powerful A.I. Apps.

    Can I add and remove cameras, drones or connected robots?

    This is a unique feature of the Unleash live platform. We call any connected camera or sensor a 'device'. We allow you to add and remove devices as you need.

    Simply by clicking on the add or manage buttons you can choose to add a new device including an image for the avatar, title and description or edit a current device, as well as deleting any unused devices.

    Can I add and remove services?

    Here is another powerful feature of the platform. We integrated with some of the leaders in media anad data analytics. You can activate and connect with these 3rd party services to manage your data workflow most effectively. We will roll out more workflow optimising services, such as Autodesk for Engineering or Adobe for Media Production.

    What are A.I. Apps?

    An A.I. App is a specialised artifical intelligence powered software application designed by talented developers and stored on our cloud platform for your use. Our A.I. App Ecosystem provides you with leading industry relevant apps that you can apply to your live video streams or stored video and image to get fast, detailed insights.

    Try out our A.I. Apps Ecosystem today, go to your profile page and scroll through the list.

    How can I activate new A.I. Apps?

    The Unleash live A.I. Apps Ecosystem is located on the profile page within the services tab. Simply scroll through the list of A.I. Apps and choose the relevant app.

    Click on the A.I. App to open the description and read more or simply click on the activate button to activate the app. Once the app is activated it will change colour and display "activated", making it available for use on your live streams or in your library.

    How does Live streaming work?

    Live streaming can be activated very easily. Each device on our platform is given a seperate stream key, which is used to connect your device to the platform through your internet provider. As soon as you "go live" your live stream will be displayed in your live page and any other places you have embedded your feed.

    How do I apply A.I. to my Live stream?

    First activate a A.I. app in your profile. To apply A.I. analysis on live video streaming open the live video page. You will notice that all devices are hidden while they are inactive to reduce clutter. As soon as a device is active and streaming the live footage will appear on the page. At this point A.I. analysis can be applied by simply choosing your A.I. app from the drop down menu next to the active live stream. Within seconds the live video feed will have an A.I. analysis overlay.

    To activate A.I. on your stored videos and images you will need to navigate to your library where you will find your action button on the bottom right hand corner. Simply choose the video or image/s you want to analyse, click the action button and you will find an option to 'recognise' objects. Select this option to start the A.I. analysis. After a period of time your analysis results will appear in the Solutions Analysis page.

    Video Format

    Video Length

    Advanced Settings

    Pixel Aspect Ratio: Square. Frame Types: Progressive Scan. Audio Sample Rate: 44.1 KHz. Audio Bitrate: 128 Kbps stereo. Bitrate Encoding: CBR.

    How do I create an orthophoto and 3D model?

    Once you have your captured images in your library, simply select all the images you wish to convert into a orthophoto and click on the action button located in the bottom right hand corner. From this menu choose 'create model' and the processing will begin. The resulting orthophoto and models will be displayed in you Solutions Models page as soon as the processing has completed.

    A.I. Apps Ecosystem

    Unleash live’s unique A.I. Apps ecosystem is designed to give developers a simple framework to create, upload and monetize your industry relevant artifical intelligence apps.

    Finally, improvements and updates can be regularly committed to your developer Sandbox.

    What do I need to do to use the API as a developer?

    Simply create an account on Unleash live and enable the developer flag in your profile. This sets up a private Sandbox for your testing. Having experience with tensorflow 1.6 and object detection is a plus.

    How does the A.I. Ecosystem business model work?

    1. Unleash live displays your completed and approved A.I. model on our Services page under relevant industry categories for our customers to search and activate.

    2. Our Unleash live customers purchase a subscription to activate your A.I. model. Pricing may be billed per month or per A.I. processing minute.

    Who sets the price?

    You, the developer, select your retail price category. The price categoeries are set by Unleash live and account for various factors such as expected value/demand, cost to process, cost to maintain and other factors.

    When a customer activates your model you will receive a net revenue based on the subscription retail price, minus a Unleash live management fee.

    How do we stimulate the ecosystem?

    A.I. is in high demand and many large and niche businesses are looking for avenues to speed up decision making and productivity. Your A.I. apps can match this interest with high quality A.I. solutions.

    Through communication such as our blog and newsletters we will be sharing with developers the most requested applications for A.I. We actively promote to our industry partners in the fields of safety, mining, agriculture, infrastructure and sport, to name a few.

    We also encourage you to think of practical uses for A.I. Apps that can speed up the flow of information to faster decision making. If you have an idea that you believe will be of importance to industry, we are more than happy to discuss the relevance to our industry partners.

    Who are the target markets for the A.I. apps?

    There are several markets that A.I. Apps have relevance, Enterprise or Business and the Professional Consumer (Prosumer) markets. These markets require practical A.I. Apps that can work with data sets to produce relevant insights for decision making.

    Enterprise is a market in which large businesses require A.I. Apps that help to turn large video and image data sets into meaningful insights on a regular basis. They need to reproduce the insights often and of the same quality.

    Prosumers are more likely to have smaller jobs with less data sets that they perform for their customers, however, still require the reliability of producing reliable insights they can pass onto their customers.

    What are some example good ideas?

    We regularly promote and communicate new ideas and industry requirements to developer signed up on the platform. We plan to expand into a blog in which we promote our developer community and their AI Apps.

    Once signed up as Unleash live developer you get access to latest ideas. Unleash live is committed to be a facilitator between enterprise problems and developer solutions.

    What analytics / stats are you collecting?

    We believe it is important for the developers to gain insights into successful AI Apps so as to learn and build relevant Apps that will sell. It is also important for the developer to understand how their apps are performing.

    The data we collect is
    * Model usage (minutes / frequency)
    * Industry (which industry uses it)
    * Media type (video / images)
    * Device/Camera location

    How much customisation of my A.I. App is possible?

    We have a standard framework for A.I. apps that helps structure the deployment of new apps. You need to provide a frozen graph (pb) and label file (pbtxt) based on the latest tensorflow 1.4 or higher object detection framework.

    We also offer our customers the chance to customise A.I. apps or build new custom A.I. Apps for their business. Our “Custom Development” option allows us to connect the developer and the customer through a structured brief in which the customer outlines the requirements and use cases for the developer to consider when building a proposal. We facilitate the development process for both the customer and the developer.

    How can I publish a specific custom model, with a lots of specific details in code and output?

    We understand the complexity of code, especially A.I. models. Therefore we have worked hard with our developers to create a simple process in which the developers can upload their code and test the code in our Sandbox. This capability and process will expand in the coming months as we learn and iterate. Please send us your suggestions and feedback. For more information visit: Unleash live Platform API

    Why is my browser not supported?

    We are doing our best to support many browsers, but some new features may not work well in non-WebKit browsers. While we are continuously improving support for other browsers we advise you to use latest Google Chrome.

    shell