Request params

Path

Field	Type	Required	Description
`media_id`	string (UUID)	Yes	Identifier of the mixed media object.

Body

Field	Type	Required	Description
`aois`	array	Yes	List of AOI definitions to calculate.

Each item in aois:

Field	Type	Required	Description
`points`	array	Yes	Polygon vertices for the AOI region. Each point has `x` and `y` (normalized coordinates, 0–1).
`name`	string	No	AOI label. Defaults to an empty string.
`start_frame`	integer	Yes	First frame where the AOI applies. Must be greater than `0`.
`end_frame`	integer	Yes	Last frame where the AOI applies. Must be greater than `start_frame`.
`aoi_type`	string	No	Optional AOI type (for example `branding`, `product`, `headline_text`).

The total number of frame–AOI entries across all AOIs must not exceed 150,000 (sum of end_frame - start_frame + 1 for each AOI).

Prerequisites: mixed media prediction must be complete (status is done) and saliency results must be available.

Response `200 OK`

Field	Type	Description
`frame_data`	array	Per-frame AOI calculation output, including attention values per frame.
`aoi_metrics`	array	Aggregated metrics per AOI (availability, attention, relative attention, etc.).

Each item in aoi_metrics:

Field	Type	Description
`uuid`	string	Identifier assigned to the AOI for this calculation.
`name`	string	AOI name from the request.
`availability`	number	Overall availability metric.
`availability_start`	number	Availability at the start of the range.
`availability_end`	number	Availability at the end of the range.
`attention`	number	Overall attention metric.
`attention_start`	number	Attention at the start of the range.
`attention_end`	number	Attention at the end of the range.
`relative_attention`	number	Relative attention metric.

Other responses

Status	Description
400 Bad Request	Media is not mixed media, or the AOI payload is invalid.
422 Unprocessable Entity	Prediction has not completed yet, or prediction failed.
500 Internal Server Error	Saliency data is missing, or the AOI calculation service failed.

Example request

PUT /predict/v2/mixed-media/036d5cb3-4fb1-4e88-98e6-1854b607d296/aois
X-API-Key: {your_api_key}
Content-Type: application/json

{
  "aois": [
    {
      "points": [
        {"x": 0.1, "y": 0.1},
        {"x": 0.1, "y": 0.5},
        {"x": 0.5, "y": 0.5},
        {"x": 0.5, "y": 0.1}
      ],
      "name": "Logo",
      "start_frame": 1,
      "end_frame": 140
    }
  ]
}

Example response

{
  "frame_data": [
    {
      "frame": 1,
      "aois": [
        {
          "uuid": "11111111-1111-1111-1111-111111111111",
          "name": "Logo",
          "points": [
            {"x": 0.1, "y": 0.1},
            {"x": 0.1, "y": 0.5},
            {"x": 0.5, "y": 0.5},
            {"x": 0.5, "y": 0.1}
          ],
          "attentionpercent": 0.75
        }
      ],
      "total_brand_attention": 0.75
    }
  ],
  "aoi_metrics": [
    {
      "uuid": "11111111-1111-1111-1111-111111111111",
      "name": "Logo",
      "availability": 1.0,
      "availability_start": 0.0,
      "availability_end": 1.0,
      "attention": 0.75,
      "attention_start": 0.7,
      "attention_end": 0.8,
      "relative_attention": 0.85
    }
  ]
}

Typical workflow

Create and predict mixed media — complete Create Mixed Media (or Create VAST Mixed Media) and Predict Mixed Media until prediction status is done.
Define AOIs — PUT /predict/v2/mixed-media/{media_id}/aois (this endpoint) with polygon points and frame ranges. Metrics are returned in the same response.
Optionally run Detect Mixed Media AOIs first if you want automatic AOI suggestions, then refine regions with this endpoint.

200OK

400Bad Request

401Unauthorized

404Not Found

412Precondition Failed

422Unprocessable Content

500Internal Server Error

502Bad Gateway