--- updatedAt: 2026-10-13T11:19:31.000Z agentTools: projectIndex: https://developers.bazaarvoice.com/v1.0-ConversationsAPI/llms.txt --- # Visual Content Coach: Photo Quality Feedback This section outlines the purpose of the Visual Content Coach: Photo Quality Feedback API and provides implementation guidance, including sample requests and responses. Use the **Visual Content Coach: Photo Quality Feedback** to provide near real-time, automated feedback messages on User-Generated Content (UGC) product images directly on the review submission form. This feedback message helps consumers capture high-quality photos with their reviews. High-quality, compliant media improves review quality, influences purchase decisions, and drives conversions. ### Notes: This feature is a part of the Conversations API; to get started, contact [Bazaarvoice Support](/v1.0-ConversationsAPI/page/support#how-to-contact-bazaarvoice-support). ## Endpoints included The **Visual Content Coach: Media Quality Feedback** API includes two endpoints: * **Uploadphoto.json** - Accepts the consumer's uploaded photo from the review submission form. The `X-Product-Id` request header, which contains the Product ID, initiates the photo upload feedback process. * **Media-score-status** - Returns feedback on the uploaded image in the form of short text messages, with a maximum of **three positive** and **three negative** messages. ## Implementation requirements 1. **Submit photo**: Upon user image upload, send a `POST` request to the `Uploadphoto.json` endpoint. Include the product ID in the `X-Product-Id` request header to initiate image analysis. 2. **Asset ID creation**: Bazaarvoice generates a unique image UUID, which is sent to the client as `Photo.Id`. This functions as the permanent `asset_id` for the uploaded image. 3. **Validation process**: Bazaarvoice automatically evaluates the uploaded image against the following criteria: 1. **Local heuristics**: Verifies image resolution, dimensions (default 400px minimum height/width), and file size (default 50 KB minimum). 2. **Quality and safety**: Assesses image brightness, sharpness, and contrast via the `imageProperties.quality` schema. 3. **Authenticity**: Performs product matching, detects action shots, evaluates background clutter, and identifies potential policy violations (e.g., stock photos, marketing materials, screenshots, or AI-generated content). 4. **Retrieve feedback**: Send a `GET` request to the **Media-score-status** endpoint with the `asset_id` in the request body to retrieve feedback on the uploaded image. The response includes a maximum of three positive and three negative feedback messages. ### Note: Do not send the `POST` and `GET` requests simultaneously. Implement logic to send the GET request a few seconds after the `POST` call succeeds. 5. **Display feedback**: Present the retrieved feedback messages on the review submission form according to your organization's business requirements. 6. **Reupload photo:** If the consumer reuploads an image based on the feedback received, send a new `POST` request to the `Uploadphoto.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 re-uploaded images. ## Enable Media Quality Feedback 1. Sign in to the [Bazaarvoice Portal](https://portal.bazaarvoice.com). 2. From the upper-right corner, select the **Settings** icon. 3. Under **Configuration**, select **Ratings & Reviews**. The **Site Manager** lists all your active deployment zones and implementations 4. Under **Implementations**, select **Edit** next to the implementation you want to configure. 5. Under **User Experience**, select **Display Options**. 6. Go to the **Visual Content Coach** section. 7. Select **Photo** from the **Media Quality Feedback** dropdown. ![](https://files.readme.io/2f82740fd71e9149b0e66bfe6ee7d9fe55d612f592e9ae105db06fc4d39f22e0-Screenshot_2026-07-30_at_15.27.17.png) 8. Verify your changes before saving. 9. [Deploy the changes](https://docs.bazaarvoice.com/articles/ratings-reviews/config_hub_overview/a/deploy-an-implementation-to-a-deployment-zone) to the implementation. ## Initiate photo upload analysis When the consumer uploads an image in the submission form, send a `POST` request to the `Uploadphoto.json` endpoint. Include the Product ID in the `X-Product-Id` request header to initiate image analysis. The technical specifications are as follows: ### Endpoint POST /data/uploadphoto.json ### HTTPS Method POST ### URL `https://[stg].api.bazaarvoice.com/data/uploadphoto.json` ### Parameters ### Note: Parameters marked with an asterisk (\*) are mandatory. | Parameter | Placement | Data type | Description | | :--------------------------------------------------------------- | :-------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | X-Product-Id | Header | String | Use the product ID from the Bazaarvoice product catalog for the client instance.
**Note:** Ensure the product ID matches the one saved in the Bazaarvoice product catalog.
**Example:** P-7777-MSD | | bv-passkey\* | Header | String | A Conversations API passkey for authentication. This is a query parameter, which is a part of the request URL. | | X-Product-Asset-ID (for photo reupload) | Header | String | The `asset_id` (UUID) of the previously uploaded image that this new upload replaces. | ### Example call ```json curl --location 'https://[stg].api.bazaarvoice.com/data/uploadphoto.json' \ --header 'X-product-id: pen3' \ --header 'bv-passkey: ' \ --form 'apiversion="5.4"' \ --form 'contenttype="review"' \ --form 'locale="en_US"' \ --form 'displayCode="11526_55_0"' \ --form 'photo=@"68wxpg9fih24ci5pwsahedf05.jpg"' ``` ### Example response ```javascript { "Locale": "en_US", "Errors": [], "Form": [ { "Type": "Field", "Id": "photo" } ], "FormErrors": {}, "SubmissionId": null, "Data": { "Fields": { "photo": { "Options": [], "Type": "FileInput", "Required": null, "Label": null, "Value": null, "MinLength": null, "Id": "photo", "MaxLength": null, "Default": null } }, "Groups": {}, "FieldsOrder": [ "photo" ], "GroupsOrder": [] }, "Photo": { "Sizes": { "normal": { "Id": "normal", "Url": "https://c7.ugc.bazaarvoice.com/submit/11526_55_0/ps_photo_preview_b5lny4v5rdgw5hhu259t61z74/photo.jpg" }, "thumbnail": { "Id": "thumbnail", "Url": "https://c7.ugc.bazaarvoice.com/submit/11526_55_0/ps_photo_preview_b5lny4v5rdgw5hhu259t61z74/photoThumb.jpg" } }, "Id": "b5lny4v5rdgw5hhu259t61z74", // To retrieve feedback, include this uploaded image's asset ID in the subsequent GET request. "SizesOrder": [ "thumbnail", "normal" ], "Caption": null }, "TypicalHoursToPost": null, "AuthorSubmissionToken": null, "HasErrors": false } ``` ## Retrieve feedback To retrieve feedback on the uploaded image, send a `GET` request to the **Media-score-status** endpoint, passing the `asset_id` in the request body. The `asset_id` is a unique UUID returned in the `Uploadphoto.json` POST response; the client must capture this value and include it in the `GET` request body. ### Note: Implement logic to send the `GET` request a few seconds after the POST call completes successfully. Do not send the `GET` and `POST` requests simultaneously. The technical specifications are as follows: ### Endpoint GET /content-coach/v1/media-score-status ### HTTPS Method GET ### URL `https://[stg].api.bazaarvoice.com/data/content-coach/v1/media-score-status?asset_id=` ### Parameters ### Note: Parameters marked with an asterisk (\*) are mandatory. | Parameter | Placement | Data type | Description | | :--------------------------------------------------------------- | :-------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | bv-passkey\* | Header | String | A Conversations API passkey for authentication. This is a query parameter, which is a part of the request URL | | asset\_id | Header | Header | A unique UUID is returned in the *Uploadphoto.json* POST response, which the client must capture and include in the *Media-score-status* GET request body to retrieve image feedback. | ### Feedback priority order Feedback priority ranges from P0 (highest) to P7 (lowest). P0 feedback messages always appear first due to their highest priority. The `GET` response includes the following: * The `scoring_result` object holds the generated feedback for the image. * The `top_positive` and `top_negative` arrays surface up to three positive signals (e.g., `AUTHENTIC_PHOTO`, `SHARP_AND_CLEAR`, `CLEAN_IMAGE`) and three negative signals (e.g., `PRODUCT_NOT_MATCHING`). * The `all_signals` array provides the full set of detected positive and negative feedback messages. ### Feedback priority levels | Priority | Feedback category | Positive feedback | Negative feedback | | :------- | :---------------- | :-------------------- | :---------------------- | | P0 | Authenticity | AUTHENTIC\_PHOTO | USE\_REAL\_PHOTO | | P1 | Sharpness | SHARP\_AND\_CLEAR | BLURRY | | P2 | Text Overlay | CLEAN\_IMAGE | TEXT\_ON\_IMAGE | | P3 | Lighting | GREAT\_LIGHTING | LOW\_LIGHTING | | P4 | Resolution | HIGH\_RESOLUTION | LOW\_RESOLUTION | | P5 | Product Match | PERFECT\_MATCH | PRODUCT\_NOT\_MATCHING | | P6 | Product Visible | PRODUCT\_VISIBLE | PRODUCT\_NOT\_VISIBLE | | P7 | Product In Use | PERFECT\_ACTION\_SHOT | SHOW\_PRODUCT\_IN\_USE | | P8 | Background | CLEAN\_BACKGROUND | DISTRACTING\_BACKGROUND | ### Example call ```json curl --location 'https://[stg].api.bazaarvoice.com/data/content-coach/v1/media-score-status?asset_id=b5lny4v5rdgw5hhu259t61z74' \ --header 'bv-passkey: ' ``` ### Example response ```javascript { "asset_id": "b5lny4v5rdgw5hhu259t61z74", "product_id": "pen3", "client_name": "test-editreviews", "status": "COMPLETED", "scoring_result": { "top_positive": [ "AUTHENTIC_PHOTO", "SHARP_AND_CLEAR", "CLEAN_IMAGE" ], "top_negative": [ "PRODUCT_NOT_MATCHING" ], "all_signals": [ "AUTHENTIC_PHOTO", "SHARP_AND_CLEAR", "CLEAN_IMAGE", "GREAT_LIGHTING", "HIGH_RESOLUTION", "PRODUCT_NOT_MATCHING", "CLEAN_BACKGROUND" ] }, "created_at": "2026-07-16T10:02:05.259542401Z", "updated_at": "2026-07-16T10:02:07.887779439Z" } ``` ## Reupload photo If the consumer reuploads an image based on the feedback received, send a new `POST` request to the `Uploadphoto.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 re-uploaded images. ### Example call ```json curl --location 'https://[stg].api.bazaarvoice.com/data/uploadphoto.json?displayCode=12334_32_0' \ --header 'accept: application/json' \ --header 'X-product-id: pen3' \ --header 'bv-passkey: ' \ --header 'X-Parent-Asset-Id: b5lny4v5rdgw5hhu259t61z74' \ --header 'Cookie: ai-ss=f42664dbb931d4a89e31a8a7a7fb5d277a647938326d7a686b7375623872697a37646963687a6b326d70' \ --form 'ApiVersion="5.4"' \ --form 'Locale="en_US"' \ --form 'Photo=@"Pen with blue writing (1).png"' \ --form 'UserId="submissionSanity_01"' \ --form 'contentType="question"' ``` ## Response codes | Code | Endpoint | Response | | :--- | :---------------------------------- | :------------------------------------------------------------------------------------------------------------------- | | 200 | Uploadphoto.json | Returns the uploaded photo's unique UUID in the `asset_id` field. | | 200 | Media-score-status | Returns the top three positive and negative feedback messages, along with all feedback items detected for the image. | | 400 | Media-score-status | Bad request. Occurs when the `asset_id` is missing from the request body. | | 404 | Media-score-status | Not found. Occurs when the `asset_id` does not match any record in the Bazaarvoice database. | | 500 | Uploadphoto.json/Media-score-status | Internal server error. Occurs when the request fails or times out during processing. |