Status
Guides
Start typing to search…

Migrating from v1 to v2

If you have been using the version 1 of the Neurons API, you can now safely migrate to the new version 2. Read more below.

With the new version 2 of the Neurons API, we have introduced a few changes, namely:

  • The endpoints will be updated from /v1/ to v2
  • Removed redundant endpoints
  • Images can now be uploaded and predicted in one go, and prediction can be re-run
  • Automated AOI detection
  • New and improved AOI drawing flow
  • Updated account usage metrics
  • A new endpoint to get information on the account and the current plan

Authentication

The authentication process remains the same. The same X-API-Key header which was used for v1 can be used for v2.

Fetching and deleting media

Changes

  • In version 2, users can get a list of existing media from GET /predict/v2/media. The list can be filtered according to certain criteria such as prediction status and media type.
  • In order to fetch or delete an image or a video, simply use the GET or DELETE request on the endpoint /predict/v2/media/{media_id} .
  • The media prediction metrics in version 2 are included in the response object, without the need to downloading a JSON file from the bucket.
  • When fetching a list of existing media, in v2, this list is sorted by oldest to most recent media and it does not include deleted media. It does, however, include the prediction results and metrics for each media.

NOTE: The URLs to the heatmaps in v2 point to a file proxy that is accessible for a maximum period of 5 minutes, before expiring.

Deprecations

  • The GET and DELETE endpoints for images (/predict/v1/images/{media_id}) and videos (/predict/v1/videos/{media_id}) were removed.

List of existing media - v1 vs v2

In v1:

{
  "pagination": {
    "total": 117,
    "offset": 0,
    "limit": 3
  },
  "media": [
    {
      "media_id": "a7df1125-e862-46ef-87e9-bf57cc7fa62c",
      "media_type": "image",
      "created": "2023-12-11 14:28:57.381715+00:00",
      "status": "done",
      "deleted": false
    },
    {
      "media_id": "56e6a39e-e199-4c5f-9f67-eddad731e90d",
      "media_type": "image",
      "created": "2023-12-11 14:32:55.370165+00:00",
      "status": "done",
      "deleted": false
    },
    {
      "media_id": "f4530bd0-e520-47cd-826e-1d365c07053a",
      "media_type": "image",
      "created": "2023-12-11 14:36:09.754604+00:00",
      "status": "done",
      "deleted": false
    }
  ]
}

In v2:

{
    "items": [
      {
        "media_id": "fcd9b862-d0b6-4d76-8a90-a3ca57816001",
        "name": "FandB_Kelloggs_001",
        "status": "done",
        "type": "video",
        "aoi_status": "done",
        "results": {
          "heat": "https://files.neuronsinc.com/media_nvai_heat.mp4",
          "clarity_heat": "",
          "engagement_heat": "",
          "cognitive_demand_heat": "",
          "fog": "https://files.neuronsinc.com/media_nvai_fog.mp4",
          "formatted": "https://files.neuronsinc.com/media_nvai_formatted.mp4",
          "first_two_heat": "",
          "first_two_fog": "",
          "last_two_heat": "",
          "last_two_fog": "",
          "brand_detection": "https://files.neuronsinc.com/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": 62.337313496407994,
          "focus": 59.14408950523628,
          "focus_first_two": null,
          "focus_last_two": null,
          "clarity": null,
          "engagement": null
        },
        "created_at": "2023-11-22T11:04:19Z",
        "updated_at": "2023-11-22T11:08:39Z",
        "deleted_at": null
      },
      {
        "media_id": "12b271c5-5b03-4a31-a1c0-bb93377e4bc8",
        "name": "Auto_2_Midas",
        "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",
          "cognitive_demand_heat": "https://files.neuronsinc.com/media_nvai_cog_demand_heat.jpeg",
          "fog": "https://files.neuronsinc.com/media_nvai_fog.jpeg",
          "formatted": "https://files.neuronsinc.com/media.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",
          "brand_detection": "",
          "brand_detection_metrics": "",
          "aoi_scores": ""
        },
        "metrics": {
          "cognitive_demand": 54.5465917592954,
          "focus": 57.836433810505895,
          "focus_first_two": 69.1144785661363,
          "focus_last_two": 43.55928663089914,
          "clarity": 83.2,
          "engagement": 71.98
        },
        "created_at": "2023-11-22T11:04:40Z",
        "updated_at": "2023-11-22T11:04:55Z",
        "deleted_at": null
      }
    ],
    "count": 2,
    "total": 111
  }

Image prediction

The image prediction now makes use of the new image prediction service, which makes for a more efficient prediction with faster results.

Changes

  • When uploading an image, the prediction runs synchronously and the response already contains the prediction results.
  • The prediction metrics are shown in the response object
  • New endpoint PUT /predict/v2/images/{media_id}/predict to rerun image prediction. We often update our prediction models, so sometimes it might necessary to rerun predictions to get the most up-to-date results
  • A new endpoint POST /predict/v2/images/{media_id}/aois/detect was added to run brand detection and automatically detect potential AOIs.
  • The endpoints for fetching and manually updating image AOIs have their route changed from /predict/v1/images/{media_id}/aois to/predict/v2/images/{media_id}/aois and the expected payload follows a new schema.

NOTE: The image prediction in v2 should take around 10 seconds (can take between 8 and 15 seconds) to get a response with the image prediction results.

Deprecations

  • The endpointPOST /predict/v1/images/upload becomes POST /predict/v2/images

Image prediction results - v1 vs v2

In v1:

{
  "media_type": "image",
  "media_id": "a7df1125-e862-46ef-87e9-bf57cc7fa62c",
  "status": "done",
  "results": {
    "fog": "https://storage.googleapis.com/media_nvai_fog.jpeg",
    "heat": "https://storage.googleapis.com/media_nvai_heat.jpeg",
    "metrics": "https://storage.googleapis.com/media_nvai_metrics.json",
    "formatted": "https://storage.googleapis.com/media_nvai_formatted.jpeg"
  }
}

In v2:

{
  "media_id": "a7df1125-e862-46ef-87e9-bf57cc7fa62c",
  "name": "@Open AI",
  "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/nv-production/media_nvai_fog.jpeg",
    "metrics": "https://storage.googleapis.com/media_nvai_metrics.json",
    "formatted": "https://files.neuronsinc.com/nv-production/media_nvai_formatted.jpeg"
  },
  "metrics": {
    "cognitive_demand": 53.61824214753062,
    "focus": 10.033042984283846,
    "clarity": 78.14,
    "engagement": 65.58
  },
  "created_at": "2023-12-11T14:28:57Z",
  "updated_at": "2023-12-11T14:29:58Z"
}

Video prediction

The video prediction has a few changes.

Changes

  • After uploading the video into the cloud service, it is now necessary to call the PUT /predict/v2/videos/{media_id}/predict to run prediction of the video.
  • To run brand detection on videos, there is a new endpoint POST /predict/v2/videos/{media_id}/aois/detect
  • The AOI detection status can be checked through the endpoint GET /predict/v2/videos/{media_id}/aois/status.
  • The video AOI results can be found in the prediction results when fetching a video.

Deprecations

  • The endpoint POST /predict/v1/videos/upload gets replaced by POST /predict/v2/videos
  • The endpoint PUT /predict/v1/videos/upload/{media_id} for finishing resumable video upload is discontinued.

Video prediction results - v1 vs v2

In v1:

{
    "media_type": "video",
    "media_id": "fcd9b862-d0b6-4d76-8a90-a3ca57816001",
    "status": "done",
    "results": {
      "fog": "https://storage.googleapis.com/media_nvai_fog.mp4",
      "heat": "https://storage.googleapis.com/media_nvai_heat.mp4",
      "metrics": "https://storage.googleapis.com/media_nvai_metrics.json",
      "formatted": "https://storage.googleapis.com/media_nvai_formatted.mp4"
    }
  }

In v2:

{
    "media_id": "fcd9b862-d0b6-4d76-8a90-a3ca57816001",
    "name": "FandB_Kelloggs_001",
    "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",
      "brand_detection": "https://files.neuronsinc.com/media_brand_detection.json",
      "brand_detection_metrics": "https://files.neuronsinc.com/media_brand_detection_metrics.json",
      "metrics": "https://files.neuronsinc.com/media_nvai_metrics.json",
      "aoi_scores": "https://files.neuronsinc.com/media_aoi_metrics.csv"
    },
    "metrics": {
      "cognitive_demand": 62.337313496407994,
      "focus": 59.14408950523628
    },
    "created_at": "2023-11-22T11:04:19Z",
    "updated_at": "2023-11-22T11:08:39Z"
  }

Account management

A few changes were introduced in order to enhance account management.

Changes

  • In v2 it is possible to check what is the name of the company and the current plan as well as its expiry date, by calling the GET /predict/v2/account endpoint.
  • It is also possible to keep track of usage through the GET /predict/v2/account/usage. It is now possible to filter between specific dates.

Deprecations

  • The GET /predict/v1/metrics endpoint gets deprecated and replaced by the GET /predict/v2/account/usage endpoint.

Updated 6 months ago

What’s Next

Now that you have successfully migrated to v2 you can cover more use cases.