> 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

## **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": "..."
  }
}
```