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

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

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"
  }
}

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

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