Creative Tags API Guide

The Creative Tags API (also called Creative Aperture) uses Vidmob's visual AI to analyze the content of your media assets and return structured tags describing what's in them. Unlike the Scoring API — which evaluates assets against predefined pass/fail rules — the Tags API is open-ended: it tells you what visual, audio, and semantic elements are present in each creative.

📘

Prerequisites

You'll need an API key with the appropriate scope. Contact your Vidmob account team to confirm your key has access to the Creative Tags (Aperture) endpoints.

What the Tags API Returns

For each submitted asset, the API returns a set of detected tags organized into categories:

• Visual elements — objects, settings, scenes (e.g. outdoor, product close-up, text overlay)
• People and emotions — human presence, facial expressions, body language
• Brand signals — logos, brand colors, product appearances
• Audio — music presence, voiceover, sound effects
• And much more!

How It Works

Like the Scoring API, tagging is asynchronous. The workflow has two steps — unlike Scoring, there is no separate fetch step: results are returned inline with the status response once the job is complete.

1. Create a job — Submit a list of assets and receive a job_id
2. Poll for completion — Check status until COMPLETE, then read results from the same response

Step 1 — Create an Annotation Job

Submit your assets with POST /v1/aperture/jobs. You can submit multiple assets in a single job.

curl -X POST https://public-api.vidmob.com/v1/aperture/jobs \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assets": [
      { "url": "https://your-cdn.com/creative-a.mp4" },
      { "url": "https://your-cdn.com/creative-b.mp4" }
    ],
    "clientTags": [
      { "label": "lifestyle", "description": "Assets featuring real-life settings or activities" },
      { "label": "product-forward", "description": "Assets where the product is the primary focus" }
    ]
  }'

The response returns a job_id. Store it.

{
  "status": "OK",
  "result": {
    "job_id": "a3f9c12e-7b4d-4e21-9f1c-8d2e6b0a5c3f"
  }
}

Step 2 — Poll for Completion

Check job status with GET /v1/aperture/jobs/{job_id}/status. When status is COMPLETE, the full annotation results are included in the same response — no additional fetch is required.

curl -H "Authorization: Bearer $API_KEY" \
  https://public-api.vidmob.com/v1/aperture/jobs/a3f9c12e-7b4d-4e21-9f1c-8d2e6b0a5c3f/status

Status values:

Polling interval: Processing time scales with the number and size of assets in the job. For small jobs (a handful of short videos), results typically arrive within minutes. For larger batches, plan for longer wait times. Start with a 5-minute interval and adjust based on observed behavior.

Reading the Results

When status is COMPLETE, the response includes an annotations array — one entry per submitted asset. Each entry contains the asset URL and its detected tags.

{
  "status": "OK",
  "result": {
    "job_id": "a3f9c12e-...",
    "status": "COMPLETE",
    "annotations": [
      {
        "url": "https://your-cdn.com/creative-a.mp4",
        "tags": [
          { "category": "visual", "label": "human presence" },
          { "category": "visual", "label": "outdoor scene" },
          { "category": "brand", "label": "logo visible" },
          { "category": "client", "label": "lifestyle" }
        ]
      }
    ]
  }
}

Client-sourced tags appear with "category": "client" so you can distinguish them from Vidmob's standard annotations.

Scoring and Tagging Together

The two APIs are complementary and often used together:

• Tags API tells you what's in a creative — useful for content inventory, analysis, and understanding the creative elements across your library.
• Scoring API tells you how well a creative performs against your rules — useful for pre-flight checks, optimization, and brand compliance.

Some scoring guidelines depend on tagging having been completed first. If you see NO_DATA_MEDIA_NOT_TAGGED in your score results, it means the asset needs to go through the Tags API before those guidelines can be evaluated.

Common Integration Patterns

Polling until complete

import time, requests

headers = {'Authorization': f'Bearer {API_KEY}'}
base = 'https://public-api.vidmob.com/v1'

# 1. Create job
res = requests.post(f'{base}/aperture/jobs', headers=headers, json={
    'assets': [{'url': 'https://cdn.example.com/ad.mp4'}],
    'clientTags': [{'label': 'lifestyle', 'description': 'Real-life settings'}]
})
job_id = res.json()['result']['job_id']

# 2. Poll until complete
while True:
    res = requests.get(f'{base}/aperture/jobs/{job_id}/status', headers=headers).json()
    status = res['result']['status']
    if status == 'COMPLETE':
        annotations = res['result']['annotations']
        break
    if status == 'FAILED':
        raise Exception('Job failed')
    time.sleep(300)  # 5 minutes

Tips:

• Batch multiple assets into a single job rather than creating one job per asset — it's more efficient.
• Define client tags with clear, specific descriptions. The more precise your description, the better the AI can map assets to your taxonomy.
• If a scored asset returns NO_DATA_MEDIA_NOT_TAGGED, submit it through the Tags API first, then re-trigger scoring.