Getting Started

Overview

Adverteyes API provides performance scores and improvement recommendations of ad creatives at speed & scale. Core features of Adverteyes API include:

  • Manual upload/delivery to adhere to 3rd-party AI policies

  • AI models to predict attention of users based on content attributes only

  • Performance scoring of images or video ads of up to <10 min in length

Understand which creative elements are most likely to drive human facial engagement by utilizing state-of-the-art AI technologies enhanced by Adverteyes human camera database.

Service authentication

The server supports two authentication methods, which can be used interchangeably:

API Key

You can sign up for credentials by submitting the Get API key form.

Pass the key with every request in the x-api-key header

response = requests.get('https://api.adverteyes.ai', headers={  
    "X-Api-Key": PUT_YOUR_API_KEY_HERE  
})

OAuth 2.0 Bearer Token

The server also supports OAuth 2.0 Bearer tokens.

response = requests.get('https://api.adverteyes.ai', headers={  
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"  
})

The server exposes standard OAuth 2.0 / OpenID Connect discovery endpoints so clients can auto-configure:

Both x-api-key and Authorization: Bearer cannot be used simultaneously.

Data Handling Process

Your Content

When you upload anything (“Content”) using our API, you confirm you have the right to share it. Your Content should be accurate, legal, and not infringe on anyone else’s rights.

How We Use Your Content

Any Content you upload will be added to our training data, helping us improve our models. You’re permitting us to use your Content worldwide for this purpose. Rest assured, we take steps to protect your privacy and ensure your data is handled safely. You still own your Content, but we can use it to improve our models.

Data tips

Please avoid uploading any personal or sensitive info. If you do, we’ll manage it according to our Privacy Policy

Want More Info?

For the full scoop on how we use data and protect your rights, check out our Terms of Services and Privacy Policy.

Analysing your first media file

Your first analysis involves uploading a video, processing it, and obtaining the performance score along with recommendations. You will use the Adverteyes API operations for video files. For images, follow the same steps using the Adverteyes API operations for image files.

The successful analysis includes the attention potential score at both the media and scene levels, which is the main performance predictor.

Attention Potential is also known as Sales Impact.

The API endpoint is: https://api.adverteyes.ai/

File upload

The request method is PUT /v1/files. An API reference for this functionality is available at this link.

The successful response includes the unique_file_id, which is the unique identifier for your upladed file and is needed for Adverteyes API operations.

import requests

file_upload_headers = {
    "X-Api-Key": PUT_YOUR_API_KEY_HERE,
    "Accept": "application/json",
    "File-Name": PUT_YOUR_FILE_NAME_HERE,
    "Content-Type": "video/mp4"
}

url = "https://api.adverteyes.ai/v1/files"

with open(PUT_YOUR_FILE_PATH_HERE, 'rb') as infile:
    response = requests.put(file_upload_url, 
                            headers=file_upload_headers, 
                            data=infile)
    if response.status_code == 200:
        print(response.json()['unique_file_id'])
    else:
        print(response.status_code, response.text)

Process file

You can generate the predictions of attention and performance scores using POST /v1/predicted-reactions/{unique_file_id} An API reference for this functionality is available at this link.

import requests

headers = {
    "X-Api-Key": PUT_YOUR_API_KEY_HERE,
    "Accept": "application/json",
}

# video/mp4 content-type at the video endpoint
url = "https://api.adverteyes.ai/v1/videos/predicted-reactions/" \
        + UNIQUE_FILE_ID

response = requests.post(url, headers=headers)
if response.status_code == 200:
    print(response.json())
else:
    print(response.status_code, response.text)

Get predicted reactions

You can read the predictions of attention and performance scores using GET /v1/predicted-reactions/{unique_file_id} An API reference for this functionality is available at this link.

import requests

headers = {
    "X-Api-Key": PUT_YOUR_API_KEY_HERE,
    "Accept": "application/json",
}

# video/mp4 content-type at the video endpoint
url = "https://api.adverteyes.ai/v1/videos/predicted-reactions/" \
        + UNIQUE_FILE_ID

response = requests.get(url, headers=headers)
if response.status_code == 200:
    print(response.json())
    if response.json()['state'] == 'processed':
        print('the media is processed')
else:
    print(response.status_code, response.text)

WARNING

The API has different operations for video and image. The above examples are using the Video endpoints.

You need to consistently use the same endpoint for all requests, otherwise you will get an error.

Next steps

For the full list of available endpoints and their parameters, please refer to the API reference.