> For the complete documentation index, see [llms.txt](https://docs.ylytic.com/ylytic/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ylytic.com/ylytic/rest-apis/api-overview/video-analysis-api.md).

# Video Analysis API

Upload videos to analyse them against the campaign brief. Choose Raw Analysis for an overall content review or Compliance Analysis to check adherence to campaign Do's and Don'ts.

## **POST - Create Video Anlaysis**

This API creates a video analysis by processing an uploaded video against the selected campaign brief. It supports Raw and Compliance analysis modes.

```
curl --location 'https://dashboard.ylytic.com/ylytic/admin/api/v1/video_analysis/analyze' \
--header 'Authorization: Bearer {{auth_header}}' \
--form 'video="/path/to/video.mp4"' \
--form 'mode="compliance"' \
--form 'campaign_name="Summer Launch"' \
--form 'brand_name="Acme Co"' \
--form 'guidelines_file="/path/to/guidelines.pdf"'
```

Or, if no guidelines document is provided:

```
curl --location 'https://dashboard.ylytic.com/ylytic/admin/api/v1/video_analysis/analyze' \
--header 'Authorization: Bearer {{auth_header}}' \
--form 'video="/path/to/video.mp4"' \
--form 'mode="compliance"' \
--form 'campaign_name="Summer Launch"' \
--form 'brand_name="Acme Co"' \
--form 'campaign_objective="Increase product awareness"' \
--form 'key_messages="Highlight key features"' \
--form 'dos="Mention free shipping"' \
--form 'donts="Do not compare with competitors"'
```

### **Payload**

<table data-search="false"><thead><tr><th width="188.6796875">Field</th><th width="98.1640625">Type</th><th width="119.4375">Required</th><th width="146.171875">Description</th><th width="191.984375">Example</th></tr></thead><tbody><tr><td>video</td><td>File</td><td>Yes</td><td>Video file (.mp4, .mov, .avi, .mkv, .webm, .m4v).</td><td>summer_launch.mp4</td></tr><tr><td>mode</td><td>String</td><td>No</td><td>Analysis mode: raw (default) or compliance.</td><td>compliance</td></tr><tr><td>campaign_name</td><td>String</td><td>Yes</td><td>Campaign name.</td><td>Summer Launch 2026</td></tr><tr><td>brand_name</td><td>String</td><td>Yes</td><td>Brand name.</td><td>Nike</td></tr><tr><td>guidelines_file</td><td>File</td><td>No</td><td>Campaign guidelines (.pdf, .doc, .docx, .ppt, .pptx). Used only in <strong>Compliance</strong> mode. If provided, its contents are automatically extracted and override manual campaign brief fields.</td><td>campaign_guidelines.pdf</td></tr><tr><td>approved_script</td><td>String</td><td>No</td><td>Approved script for compliance analysis.</td><td>Introducing our latest running shoes...</td></tr><tr><td>campaign_objective</td><td>String</td><td>Required*</td><td>Required when mode=compliance and no guidelines_file is provided.</td><td>Increase awareness of the new product launch.</td></tr><tr><td>key_messages</td><td>String</td><td>Required*</td><td>Required when mode=compliance and no guidelines_file is provided.</td><td>Lightweight, breathable, and durable.</td></tr><tr><td>required_disclosures</td><td>String</td><td>No</td><td>Required disclosures.</td><td>Paid Partnership with Nike</td></tr><tr><td>required_hashtags</td><td>String</td><td>No</td><td>Required hashtags.</td><td>#Nike #JustDoIt #SummerLaunch</td></tr><tr><td>tone_style_guidelines</td><td>String</td><td>No</td><td>Tone and style guidelines.</td><td>Energetic and motivational</td></tr><tr><td>dos</td><td>String</td><td>No</td><td>Campaign do's.</td><td>Show the product clearly and mention key features.</td></tr><tr><td>donts</td><td>String</td><td>No</td><td>Campaign don'ts.</td><td>Do not compare with competitors.</td></tr><tr><td>prohibited_claims</td><td>String</td><td>No</td><td>Claims that must not be made.</td><td>Do not claim medical or performance guarantees.</td></tr><tr><td>call_to_action</td><td>String</td><td>No</td><td>Expected call-to-action.</td><td>Shop now at nike.com</td></tr><tr><td>other_notes</td><td>String</td><td>No</td><td>Additional campaign instructions.</td><td>Keep the video under 60 seconds.</td></tr></tbody></table>

**Note:** campaign\_name and brand\_name are mandatory top-level fields for both **Raw** and **Compliance** modes. They are not part of the campaign brief. The campaign brief is only applicable in Compliance mode and is either extracted automatically from the guidelines\_file or provided through the individual campaign brief fields.

#### Success Response (202 Accepted)

```
{
  "analysis_id": "665f1b2c8a1e4a0012abcd34",
  "status": "pending"
}
```

The analysis runs asynchronously. Use the **Get Analysis Status** API to track progress.

#### **Error Responses - 400 Bad Request**

```
{
  "error": {
    "http_status": 400,
    "internal_code": 4001,
    "message": "No video file provided"
  }
}
```

<table data-search="false"><thead><tr><th width="142.81640625">Internal Code</th><th width="269.01171875">Message</th><th>Cause</th></tr></thead><tbody><tr><td>4001</td><td>No video file provided</td><td>video is missing or the filename is empty.</td></tr><tr><td>4002</td><td>Unsupported video format</td><td>Uploaded video format is not supported. Allowed formats: .mp4, .mov, .avi, .mkv, .webm, .m4v.</td></tr><tr><td>4003</td><td>mode must be 'raw' or 'compliance'</td><td>Invalid value provided for mode.</td></tr><tr><td>4004</td><td>Guidelines file must be PDF, Word, or PowerPoint</td><td>Unsupported guidelines_file format.</td></tr><tr><td>4005</td><td>Could not read guidelines file (&#x3C;filename>)</td><td>Failed to extract text from the uploaded guidelines document.</td></tr><tr><td>4006</td><td>Compliance mode is missing required fields</td><td>campaign_objective and/or key_messages are missing when mode=compliance and no guidelines_file is provided.</td></tr><tr><td>4007</td><td>Guidelines document appears to be empty</td><td>The uploaded guidelines document contains no extractable text.</td></tr><tr><td>4008</td><td>Could not extract a campaign brief from the guidelines document</td><td>Automatic campaign brief extraction failed.</td></tr><tr><td>4009</td><td>Missing required fields: Campaign Name, Brand Name</td><td>campaign_name and/or brand_name were not provided.</td></tr></tbody></table>

## GET - Video Analysis Status

This API is used for retrieving the status and results of a video analysis.

```
curl --location 'https://dashboard.ylytic.com/ylytic/admin/api/v1/video_analysis/analyze/<analysis_id>' \
--header 'Authorization: Bearer {{auth_header}}'
```

**Path Parameters**

| Parameter    | Type   | Description                                             | Example                  |
| ------------ | ------ | ------------------------------------------------------- | ------------------------ |
| analysis\_id | String | analysis\_id returned by the Create Video Analysis API. | 665f1b2c8a1e4a0012abcd34 |

#### Success Response - 200 OK

```
{
  "analysis_id": "665f1b2c8a1e4a0012abcd34",
  "mode": "compliance",
  "status": "complete",
  "error": null,
  "campaign_name": "Summer Launch",
  "brand_name": "Acme Co",
  "raw_analysis": "…full TwelveLabs analysis text…",
  "campaign_brief": {
    "approved_script": null,
    "campaign_objective": "...",
    "key_messages": "...",
    "required_disclosures": "...",
    "required_hashtags": "...",
    "tone_style_guidelines": "...",
    "dos": "...",
    "donts": "...",
    "prohibited_claims": "...",
    "call_to_action": "...",
    "other_notes": "..."
  },
  "compliance_report": {
    "compliant_elements": ["..."],
    "violations": [
      {
        "issue": "...",
        "why_it_matters": "...",
        "evidence": "..."
      }
    ],
    "missing_requirements": ["..."],
    "rectifications": ["..."],
    "compliance_score": 82,
    "summary": "..."
  }
}
```