Status
API Reference
Start typing to search…

Get Media

get https://api.neuronsinc.com/predict/v2/media/

Return the details of a media

Pre-requisites

It is necessary to en existing media

Use the media_id to send the GET request to the endpoint /predict/v2/media/media_id

Examples of successful responses

Images

For an existing image media, the results should look like this:

{
  "media_id": "12ee330a-9142-4640-838c-6d6fc1e65ddd",
  "name": "sample_ad",
  "status": "done",
  "type": "image",
  "aoi_status": "unspecified",
  "results": {
    "heat": "https://files.neuronsinc.com/media_nvai_heat.jpeg",
    "clarity_heat": "https://files.neuronsinc.com/media_ve_clarity_heat.jpeg",
    "engagement_heat": "https://files.neuronsinc.com/media_ve_excitedness_heat.jpeg",
    "fog": "https://files.neuronsinc.com/media_nvai_fog.jpeg",
    "formatted": "https://files.neuronsinc.com/media_nvai_formatted.jpeg",
    "first_two_heat": "https://files.neuronsinc.com/media_nvai_first2_heat.jpeg",
    "first_two_fog": "https://files.neuronsinc.com/media_nvai_first2_fog.jpeg",
    "last_two_heat": "https://files.neuronsinc.com/media_nvai_last2_heat.jpeg",
    "last_two_fog": "https://files.neuronsinc.com/media_nvai_last2_fog.jpeg",
    "engagement_new_heat": "https://files.neuronsinc.com/media_nvai_engaging_heat.jpeg",
    "memory_heat": "https://files.neuronsinc.com/media_nvai_memory_heat.jpeg",
    "intent_heat": "https://files.neuronsinc.com/media_nvai_buy_heat.jpeg",
    "trust_heat": "https://files.neuronsinc.com/media_nvai_trustworthy_heat.jpeg",
    "avoidance_heat": "https://files.neuronsinc.com/media_nvai_annoying_heat.jpeg"
  },
  "metrics": {
    "cognitive_demand": 50.904459874777665,
    "focus": 83.45828370672884,
    "focus_first_two": 80.62319981104667,
    "focus_last_two": 45.30343438115154,
    "clarity": 63.41,
    "engagement": 67.51,
    "engagement_new": 58.3116969754619,
    "memory": 56.13035924973027,
    "intent": 73.59597183042958,
    "trust": 46.642828372217,
    "avoidance": 22.09484428167343
  },
  "created_at": "2023-03-01T09:54:49Z",
  "updated_at": "2023-03-01T09:54:49Z"
}

NOTE: The assets will only be available under the URL's for a maximum period of 5 minutes, so make sure to download them before they expire.

Image prediction results

Below there's a brief explanation of each field in the image prediction results:

  • media_id: The unique identifier, which can be used to query the media.
  • name: The name of the image file.
  • status: The prediction status. If status is done then results should be visible in the response.
  • type: The type of media (image or video).

The heat maps are stored as image assets (with an expiry, as explained above), and links can be find under results:

  • heat: This is the attention heat map.
  • clarity_heat: This is the heat map for clarity.
  • engagement_heat: This is the engagement heat map.
  • fog: This is the attention fog map.
  • formatted: This is the original image (no heat map).
  • first_two_heat: This is heat map shows what draws attention in the first two seconds.
  • first_two_fog: This is fog map shows what draws attention in the first two seconds.
  • last_two_heat: This is heat map shows what draws attention in the final two seconds.
  • last_two_fog: This is fog map shows what draws attention in the final two seconds.
  • engagement_new_heat: The heat map for the brand new engagement metric.
  • memory_heat: The heat map for the brand new memory metric.
  • intent_heat: The heat map for the brand new intent to intent metric.
  • trust_heat: The heat map for the brand new trust metric.
  • avoidance_heat: The heat map for the brand new avoidance metric.

Metrics (find out what each metric means in this article):

  • cognitive_demand: The value for cognitive demand (in percentage).
  • focus: The value for total attention (in percentage).
  • focus_first_two: The value for attention during the first two seconds (in percentage).
  • focus_last_two: The value for attention during the final two seconds (in percentage).
  • clarity: The value for clarity (in percentage).
  • engagement: The value for engagement (in percentage).
  • engagement_new: The value for the brand new engagement metric (in percentage).
  • memory: The value for the brand new memory metric (in percentage).
  • intent: The value for the brand new intent metric (in percentage). Based on association words like Explore, Consider, Choose, Try, Recommend and Buy, this behavioural metric provides a gauge for how likely the viewers of the creative are to act upon the ads message. It signals the consumer’s likelihood to engage, recommend or purchase. The Intent metric translates into strong consideration, conversion or advocacy as an initial reaction to the creative.
  • trust: The value for the brand new trust metric (in percentage). Based on association words like Trustworthy, Honest and Sincere this cognitive metric gives an assessment of the level of trust built by the creative. As the other FRT Metrics (like Engagement) it measures gut reaction of to what extend the asset fosters trust and a sense of authentic message. This can drive brand equity, retention and loyalty as well as influencing consideration.
  • avoidance: The value for the brand new avoidance metric (in percentage). Based on the association words Boring and Annoying this metric shows for the first time a gut reaction of negative sentiment to the creative. It measures the extent to which a creative creates disinterest, discontent or friction. At the core of the metric is the assessment of avoidance-related motivation and behaviour and is a strong indicator of dropoff, negative association and acts against brand building and lift.

Videos

For an existing video media, the results should look like this:

{
  "media_id": "0d1aeafa-d360-47c2-afaf-c6149281c202",
  "name": "video_media",
  "status": "done",
  "type": "video",
  "aoi_status": "done",
  "results": {
    "heat": "https://files.neuronsinc.com/media_nvai_heat.mp4",
    "fog": "https://files.neuronsinc.com/media_nvai_fog.mp4",
    "formatted": "https://files.neuronsinc.com/media_nvai_formatted.mp4",
    "metrics": "https://files.neuronsinc.com/media_nvai_metrics.json",
    "frt_frame_metrics": "https://files.neuronsinc.com/media_frt_metrics.json",
    "brand_detection": "https://files.neuronsinc.com/nv-test/media_brand_detection.json?",
    "brand_detection_metrics": "https://files.neuronsinc.com/media_brand_detection_metrics.json?",
    "aoi_scores": "https://files.neuronsinc.com/media_aoi_metrics.csv"
  },
  "metrics": {
    "cognitive_demand": 91.73756099979508,
    "focus": 39.50367547395666,
    "focus_first_two": 68.92043509687068,
    "focus_last_two": 12.776237332510023,
    "engagement_new": 48.56829226514142,
    "engagement_new_start": 60.587450885026215,
    "engagement_new_end": 48.31150801571462,
    "memory": 56.917629571266,
    "memory_start": 51.441789723350155,
    "memory_end": 52.40626494502513,
    "intent": 63.22354314204671,
    "intent_start": 52.2297100223787,
    "intent_end": 36.479611806214365,
    "trust": 77.95613007510966,
    "trust_start": 63.80634240907102,
    "trust_end": 52.42010053947325,
    "avoidance": 26.19246212057231,
    "avoidance_start": 28.379557578412584,
    "avoidance_end": 28.379557578412584
  },
  "created_at": "2024-01-19T09:05:44Z",
  "updated_at": "2024-01-19T09:36:49Z"
}

Where the brand detection metrics can be found in the JSON indicated in the brand_detection_metrics field, the AOI detection results can be found in the JSON file indicated in the aoi_scores field.

NOTE: The assets will only be available under the URL's for a maximum period of 5 minutes, so make sure to download them before they expire.

Video prediction results

Below there's a brief explanation of each field in the video prediction results:

  • media_id: The unique identifier, which can be used to query the media.
  • name: The name of the video file.
  • status: The prediction status. If status is done then results should be visible in the response.
  • type: The type of media (image or video).
  • aoi_status: The status of the AOI prediction for the media.

The heat maps are stored as video assets (with an expiry, as explained above), and links can be find under results:

  • heat: This is video with its attention heat map.
  • fog: This is the video with its attention fog map.
  • formatted: This is the original video (no heat map).

Additionally, the results field contains some JSON assets with additional detection metrics:

  • metrics: This JSON contains the frame-by-frame prediction metrics.
  • frt_frame_metrics: This JSON contains the frame-by-frame FRT metrics.
  • brand_detection: This JSON contains the frame-by-frame information on detected areas-of-interest (AOIs) that resulted from the brand-detection.
  • brand_detection_metrics: This JSON file contains the aggregated result for each of the detected AOIs prediction metrics.
  • aoi_scores: This file contains contains the brand detection metrics in a CSV format.

Metrics (find out what each metric means in this article):

  • cognitive_demand: The value for cognitive demand (in percentage).
  • focus: The value for attention (in percentage).
  • focus_first_two: The value for attention during the first two seconds (in percentage).
  • focus_last_two: The value for attention during the final two seconds (in percentage).
  • engagement_new: The value for the brand new engagement metric (in percentage).
  • engagement_new_start: The value for the brand new engagement metric during the first two seconds (in percentage).
  • engagement_new_end: The value for the brand new engagement metric during the last two seconds (in percentage).
  • memory: The value for the brand new memory metric (in percentage).
  • memory_start: The value for the brand new memory metric during the first two seconds (in percentage).
  • memory_end: The value for the brand new memory metric during the last two seconds (in percentage).
  • intent: The value for the brand newintent metric (in percentage). Based on association words like Explore, Consider, Choose, Try, Recommend and Buy, this behavioural metric provides a gauge for how likely the viewers of the creative are to act upon the ads message. It signals the consumer’s likelihood to engage, recommend or purchase. The Intent metric translates into strong consideration, conversion or advocacy as an initial reaction to the creative.
  • intent_start: The value for the brand new intent to intent metric during the first two seconds (in percentage).
  • intent_end: The value for the brand new intent to intent metric during the last two seconds (in percentage).
  • trust: The value for the brand new trust metric (in percentage). Based on association words like Trustworthy, Honest and Sincere this cognitive metric gives an assessment of the level of trust built by the creative. As the other FRT Metrics (like Engagement) it measures gut reaction of to what extend the asset fosters trust and a sense of authentic message. This can drive brand equity, retention and loyalty as well as influencing consideration.
  • trust_start: The value for the brand new trust metric during the first two seconds (in percentage).
  • trust_end: The value for the brand new trust metric during the last two seconds (in percentage).
  • avoidance: The value for the brand new avoidance metric (in percentage). Based on the association words Boring and Annoying this metric shows for the first time a gut reaction of negative sentiment to the creative. It measures the extent to which a creative creates disinterest, discontent or friction. At the core of the metric is the assessment of avoidance-related motivation and behaviour and is a strong indicator of dropoff, negative association and acts against brand building and lift.
  • avoidance_start: The value for the brand new avoidance metric during the first two seconds (in percentage).
  • avoidance_end: The value for the brand new avoidance metric during the last two seconds (in percentage).
Language
Credentials
Header
Click Try It! to start a request and see the response here!