--- updatedAt: 2026-06-12T11:16:53.000Z agentTools: projectIndex: https://apidocs.neuronsinc.com/llms.txt --- # Update Video Aois Update AOIs for an existing video and return calculated metrics. This endpoint differs from the `POST /{media_id}/aois/static` endpoint: * `POST /{media_id}/aois/static` starts a **background static AOI calculation** on the video. It queues the computation via `VideoStaticAOIPrediction` and returns HTTP 202 with a simple `{"detail": ...}` message once the job has been accepted. No AOI metrics are returned in that response. * `PUT /{media_id}/aois` performs a **synchronous AOI calculation** using the already available video results (`video.results["saliency"]`). It calls the external `video_aoi_service` and returns HTTP 200 together with the full calculation output. Response: * On success, returns HTTP 200 with a body matching the `VideoAOIsCalculationResponse` schema, containing the calculated AOI results for the submitted AOIs and frame ranges, along with associated metadata. * On error, returns an appropriate HTTP status with a `Detail` payload. This endpoint differs from the **POST** `/{media_id}/aois/static` [endpoint](https://apidocs.neuronsinc.com/reference/draw-static-video-aois): The **POST** `/{media_id}/aois/static` starts a **background static AOI calculation** on the video. It queues the computation and returns HTTP 202 with a simple `{"detail": ...}` message once the job has been accepted. No AOI metrics are returned in that response. The **PUT** `/{media_id}/aois` performs a **synchronous AOI calculation** using the already available video results. It calls the newest video AOI model service and returns an HTTP status of 200, together with the full calculation output. On success, tis endpoint returns a body containing the calculated AOI results for the submitted AOIs and frame ranges, along with associated metadata. On error, it returns an appropriate HTTP status with a `Detail` payload. ### Pre-requisites You must have an existing video with an associated *media\_id* and the prediction status as *done*. Use the *media\_id* to send the **PUT** request to the endpoint `/predict/v2/videos/media_id/aois/static` ### Expected request payload For each Area of Interest (AOI), there need to be , at least, 3 points, with both **x** (horizontal) and **y** (vertical) coordinates, so that a triangle, rectangle, or polygon can be set as the AOI. **Note**: The coordinates for the points must be values within the interval 0 and 1, because it corresponds to the position relative to the with or height of the image, so values like -0.3 or 1.56 will not be valid. ```json { "aois": [ { "points": [ { "x": 0.7, "y": 0.2 }, { "x": 0.7, "y": 0.5 }, { "x": 0.9, "y": 0.5 }, { "x": 0.9, "y": 0.2 } ], "name": "Manual_Video_Brand_AOI", "start_frame": 10, "end_frame": 13 } ] } ``` ### Example of a successful response Upon updating the AOIs in your image, the successful response look should look like the snippet below. ```json { "frame_data": [ { "frame": 10, "aois": [ { "uuid": "442a1fa8-3022-41e6-9688-700890193c0b", "name": "Manual_Video_Brand_AOI", "points": [ { "x": 0.7, "y": 0.2 }, { "x": 0.7, "y": 0.5 }, { "x": 0.9, "y": 0.5 }, { "x": 0.9, "y": 0.2 } ], "attention_percent": 0.21146677434444427 } ], "total_brand_attention": 0.21146677434444427 }, { "frame": 11, "aois": [ { "uuid": "442a1fa8-3022-41e6-9688-700890193c0b", "name": "Manual_Video_Brand_AOI", "points": [ { "x": 0.7, "y": 0.2 }, { "x": 0.7, "y": 0.5 }, { "x": 0.9, "y": 0.5 }, { "x": 0.9, "y": 0.2 } ], "attention_percent": 0.2743196189403534 } ], "total_brand_attention": 0.2743196189403534 }, { "frame": 12, "aois": [ { "uuid": "442a1fa8-3022-41e6-9688-700890193c0b", "name": "Manual_Video_Brand_AOI", "points": [ { "x": 0.7, "y": 0.2 }, { "x": 0.7, "y": 0.5 }, { "x": 0.9, "y": 0.5 }, { "x": 0.9, "y": 0.2 } ], "attention_percent": 0.3613232970237732 } ], "total_brand_attention": 0.3613232970237732 }, { "frame": 13, "aois": [ { "uuid": "442a1fa8-3022-41e6-9688-700890193c0b", "name": "Manual_Video_Brand_AOI", "points": [ { "x": 0.7, "y": 0.2 }, { "x": 0.7, "y": 0.5 }, { "x": 0.9, "y": 0.5 }, { "x": 0.9, "y": 0.2 } ], "attention_percent": 0.4557400941848755 } ], "total_brand_attention": 0.4557400941848755 } ], "aoi_metrics": [ { "uuid": "442a1fa8-3022-41e6-9688-700890193c0b", "name": "Manual_Video_Brand_AOI", "availability": 0.16666666666666666, "availability_start": 0.16666666666666666, "availability_end": 0.16666666666666666, "attention": 0.3257124423980713, "attention_start": 0.3257124423980713, "attention_end": 0.3257124423980713, "relative_attention": 0.3257124423980713 } ] } ```
# OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Neurons Customers API v2", "version": "2.0.0", "description": "Neurons Customers API" }, "paths": { "/predict/v2/videos/{media_id}/aois": { "put": { "operationId": "updateVideoAois", "summary": "Update Video Aois", "parameters": [ { "in": "path", "name": "media_id", "schema": { "format": "uuid4", "title": "Media Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoAOIsCalculationResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Detail" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Detail" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Detail" } } } }, "412": { "description": "Precondition Failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Detail" } } } }, "422": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Detail" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Detail" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Detail" } } } } }, "description": "Update AOIs for an existing video and return calculated metrics.\n\nThis endpoint differs from the `POST /{media_id}/aois/static` endpoint:\n\n* `POST /{media_id}/aois/static` starts a **background static AOI calculation**\n on the video. It queues the computation via `VideoStaticAOIPrediction` and\n returns HTTP 202 with a simple `{\"detail\": ...}` message once the job has\n been accepted. No AOI metrics are returned in that response.\n* `PUT /{media_id}/aois` performs a **synchronous AOI calculation** using the\n already available video results (`video.results[\"saliency\"]`).\n It calls the external `video_aoi_service` and returns HTTP 200 together\n with the full calculation output.\n\nResponse:\n\n* On success, returns HTTP 200 with a body matching the\n `VideoAOIsCalculationResponse` schema, containing the calculated AOI\n results for the submitted AOIs and frame ranges, along with associated\n metadata.\n* On error, returns an appropriate HTTP status with a `Detail` payload.", "tags": [ "Videos" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaticVideoAOIRequest" } } }, "required": true }, "security": [ { "LegacyPredictAPIAuth": [] } ] } } }, "components": { "schemas": { "Detail": { "properties": { "detail": { "title": "Detail", "type": "string" } }, "required": [ "detail" ], "title": "Detail", "type": "object" }, "AOISpecPoint": { "properties": { "x": { "title": "X", "type": "number" }, "y": { "title": "Y", "type": "number" } }, "required": [ "x", "y" ], "title": "AOISpecPoint", "type": "object" }, "StaticVideoAOIRequest": { "properties": { "aois": { "items": { "$ref": "#/components/schemas/StaticVideoAOISpec" }, "title": "Aois", "type": "array" } }, "required": [ "aois" ], "title": "StaticVideoAOIRequest", "type": "object" }, "StaticVideoAOISpec": { "properties": { "points": { "items": { "$ref": "#/components/schemas/AOISpecPoint" }, "title": "Points", "type": "array" }, "name": { "default": "", "title": "Name", "type": "string" }, "aoi_type": { "title": "Aoi Type", "enum": [ "product", "branding", "headline_text", "call_to_action", "body_text" ], "type": "string" }, "start_frame": { "exclusiveMinimum": 0, "title": "Start Frame", "type": "integer" }, "end_frame": { "exclusiveMinimum": 0, "title": "End Frame", "type": "integer" } }, "required": [ "points", "start_frame", "end_frame" ], "title": "StaticVideoAOISpec", "type": "object" }, "BoundingBoxPoint": { "properties": { "x": { "title": "X", "type": "number" }, "y": { "title": "Y", "type": "number" } }, "required": [ "x", "y" ], "title": "BoundingBoxPoint", "type": "object" }, "VideoAOIMetrics": { "properties": { "uuid": { "title": "Uuid", "type": "string" }, "name": { "title": "Name", "type": "string" }, "availability": { "title": "Availability", "type": "number" }, "availability_start": { "title": "Availability Start", "type": "number" }, "availability_end": { "title": "Availability End", "type": "number" }, "attention": { "title": "Attention", "type": "number" }, "attention_start": { "title": "Attention Start", "type": "number" }, "attention_end": { "title": "Attention End", "type": "number" }, "relative_attention": { "title": "Relative Attention", "type": "number" } }, "required": [ "uuid", "name", "availability", "availability_start", "availability_end", "attention", "attention_start", "attention_end", "relative_attention" ], "title": "VideoAOIMetrics", "type": "object" }, "VideoAOIOutput": { "properties": { "uuid": { "title": "Uuid", "type": "string" }, "name": { "title": "Name", "type": "string" }, "points": { "items": { "$ref": "#/components/schemas/BoundingBoxPoint" }, "title": "Points", "type": "array" }, "attention_percent": { "title": "Attention Percent", "type": "number" } }, "required": [ "uuid", "name", "points", "attention_percent" ], "title": "VideoAOIOutput", "type": "object" }, "VideoAOIsCalculationResponse": { "properties": { "frame_data": { "items": { "$ref": "#/components/schemas/VideoFrameOutput" }, "title": "Frame Data", "type": "array" }, "aoi_metrics": { "items": { "$ref": "#/components/schemas/VideoAOIMetrics" }, "title": "Aoi Metrics", "type": "array" } }, "required": [ "frame_data", "aoi_metrics" ], "title": "VideoAOIsCalculationResponse", "type": "object" }, "VideoFrameOutput": { "properties": { "frame": { "title": "Frame", "type": "integer" }, "aois": { "items": { "$ref": "#/components/schemas/VideoAOIOutput" }, "title": "Aois", "type": "array" }, "total_brand_attention": { "title": "Total Brand Attention", "type": "number" } }, "required": [ "frame", "aois", "total_brand_attention" ], "title": "VideoFrameOutput", "type": "object" } }, "securitySchemes": { "LegacyPredictAPIAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" } } }, "servers": [ { "url": "https://api.neuronsinc.com" } ] } ```