Visual Content Coach: Video Quality Feedback

Use the Visual Content Coach: Video Quality Feedback API to provide near real-time, automated feedback messages on user-generated content (UGC) product videos directly on the review submission form. This feedback helps consumers record higher-quality videos with their reviews. High-quality, compliant video improves review quality, influences purchase decisions, and drives conversions.

Endpoints included

The Visual Content Coach: Video Quality Feedback API includes two endpoints:

• uploadvideo.json: Accepts the consumer's uploaded video from the review submission form. The X-Product-Id request header, which contains the product ID, initiates the video quality feedback process.
• Media-score-status: Returns feedback on the uploaded video in the form of short text messages, with a maximum of three positive and three negative messages. This is the same endpoint used for photo quality feedback..

Implementation requirements

1. Enable Media Quality Feedback in the Portal: Set Media Quality Feedback to Video or All Media in the Ratings & Reviews Configuration. For step by step insurtuctions, refer to Knowledge Base.

2. Submit video: When the consumer uploads a video, send a POST request to the uploadvideo.json endpoint. Include the product ID in the X-Product-Id request header to initiate video analysis.

3. Asset ID creation: Bazaarvoice generates a unique video identifier, which is returned to the client as VideoId. This value is the permanent asset_id for the uploaded video.

4. Validation process: Bazaarvoice automatically evaluates the uploaded video against the following criteria:

   1. Frame sampling: Bazaarvoice pick a few sample frames from the video for evaluation.

   2. Local heuristics: Verifies frame resolution, file size, and blur.

   3. Quality and safety: Assesses brightness, sharpness, and contrast for each frame.

   4. Authenticity: Performs product matching, detects action shots, evaluates background clutter and text overlays, and identifies potential policy violations (for example, screen recordings, stock footage, marketing materials, or AI-generated content).

   5. Aggregation: Bazaarvoice combines the per-frame results into a single result for the video.

5. Retrieve feedback: Send a GET request to the Media-score-status endpoint with the asset_id to retrieve feedback on the uploaded video. The response includes a maximum of three positive and three negative feedback messages.

   Notes:

   • Do not request feedback immediately after upload. Wait before the first poll, then follow poll_interval_seconds.
   • Implement logic to send the GET request a few seconds after the POST call succeeds. Video analysis takes longer than photo analysis, so keep polling until the status is COMPLETED or FAILED.

6. Display feedback: Present the retrieved feedback messages on the review submission form according to your organization's business requirements.

7. Reupload video: If the consumer reuploads a video based on the feedback received, send a new POST request to the uploadvideo.json endpoint, passing the original asset_id in the X-Parent-Asset-Id request header. This is used only for analytical purposes. No additional feedback is provided for reuploaded videos.

Initiate video upload analysis

When the consumer uploads a video in the submission form, send a POST request to the uploadvideo.json endpoint. Include the product ID in the X-Product-Id request header to initiate video quality analysis.

The technical specifications are as follows:

Endpoint

POST /data/uploadvideo.json

HTTPS method

POST

URL

https://[stgmedia].api.bazaarvoice.com/data/uploadvideo.json

Parameters

Example call

curl --location 'https://[stgmedia].api.bazaarvoice.com/data/uploadvideo.json?displayCode=<DisplayCode>' \
--header 'User-Agent: <USER AGENT>' \
--header 'bv-passkey: <Passkey>' \
--header 'x-product-id: pen1' \
--form 'apiversion="5.4"' \
--form 'contenttype="review"' \
--form 'video=@"movie.mp4"'

Example response

{
    "Locale": "en_US",
    "Errors": [],
    "Form": [
        {
            "Type": "Field",
            "Id": "video"
        }
    ],
    "FormErrors": {},
    "SubmissionId": null,
    "Data": {
        "Fields": {
            "video": {
                "Options": [],
                "Type": "FileInput",
                "Required": null,
                "Label": null,
                "Value": null,
                "MinLength": null,
                "Id": "video",
                "MaxLength": null,
                "Default": null
            }
        },
        "Groups": {},
        "FieldsOrder": [
            "video"
        ],
        "GroupsOrder": []
    },
    "TypicalHoursToPost": null,
    "AuthorSubmissionToken": null,
    "HasErrors": false,
    "Video": {
        "VideoId": "fc41023b-bdec-4613-a121-0f1f81b04291",
        "VideoHost": "BAZAARVOICE",
        "VideoThumbnailUrl": "https://stgvideo.api.bazaarvoice.com/fc41023b-bdec-4613-a121-0f1f81b04291/thumbnail/image-00001.png",
        "VideoUrl": "https://stgvideo.api.bazaarvoice.com/fc41023b-bdec-4613-a121-0f1f81b04291/video/movie.mp4"
    }
}

Retrieve feedback

To retrieve feedback on the uploaded video, send a GET request to the Media-score-status endpoint, passing the asset_id as a query parameter. The asset_id is the unique video identifier (VideoId) returned in the upload response. The client must capture this value and include it in the GET request.

The technical specifications are as follows:

Endpoint

GET/data/content-coach/v1/media-score-status

HTTPS method

GET

URL

https://[stg].api.bazaarvoice.com/data/content-coach/v1/media-score-status?asset_id=<Asset_ID>

Parameters

Polling behavior

Video analysis is asynchronous. Poll the endpoint until the status is COMPLETED or FAILED.

• While Bazaarvoice is analyzing the video, the endpoint returns HTTP 202 with status set to PROCESSING and a poll_interval_seconds value. Wait that many seconds before you send the next request.
• When analysis finishes, the endpoint returns HTTP 200 with the scoring_result object.
• If analysis fails, the endpoint returns HTTP 500 with an error code. Let the consumer continue submitting the review without feedback.

Feedback priority order

Feedback priority ranges from P0 (highest) to P8 (lowest). P0 feedback messages always appear first.

The GET response includes the following:

• The scoring_result object holds the generated feedback for the video.
• The top_positive and top_negative arrays surface up to three positive messages (for example, AUTHENTIC_VIDEO, SHARP_AND_CLEAR, CLEAN_VIDEO) and up to three negative messages (for example, PRODUCT_NOT_MATCHING).
• The all_signals array provides the full set of detected positive and negative feedback messages.

Feedback priority levels

Example call

curl --location 'https://[stg].api.bazaarvoice.com/data/content-coach/v1/media-score-status?asset_id=<ASSET ID>' \
--header 'bv-passkey:<PASSKEY>'

Example response

{
    "asset_id": "82849802-7210-456e-b813-4505eafc18e9",
    "product_id": "pen1",
    "client_name": "test-editreviews",
    "status": "COMPLETED",
    "scoring_result": {
        "top_positive": [
            "HIGH_RESOLUTION",
            "CLEAN_BACKGROUND"
        ],
        "top_negative": [
            "USE_REAL_VIDEO",
            "BLURRY",
            "TEXT_ON_VIDEO"
        ],
        "all_signals": [
            "USE_REAL_VIDEO",
            "BLURRY",
            "TEXT_ON_VIDEO",
            "LOW_LIGHTING",
            "HIGH_RESOLUTION",
            "PRODUCT_NOT_MATCHING",
            "CLEAN_BACKGROUND"
        ]
    },
    "created_at": "2026-10-09T09:54:56.822577430Z",
    "updated_at": "2026-10-09T09:55:05.520733434Z"
}

Reupload video

If the consumer reuploads a video based on the feedback received, send a new POST request to the uploadvideo.json endpoint, passing the original asset_id in the X-Parent-Asset-Id request header.

This is used only for analytical purposes. No additional feedback is provided for reuploaded videos.

Example call

curl --location 'https://stgmedia.api.bazaarvoice.com/data/uploadvideo.json?displayCode=<DisplayCode>' \
--header 'User-Agent: <USER AGENT>' \
--header 'bv-passkey: <Passkey>' \
--header 'x-parent-asset-id: f1eeb3ef-c75a-405e-b1ba-1d738946d849' \
--form 'apiversion="5.4"' \
--form 'contenttype="review"' \
--form 'video=@"movie.mp4"'

Response codes