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 their content. Unlike the Scoring API, which evaluates assets against predefined pass/fail rules, the Tags API is open-ended: it identifies the visual, audio, and semantic elements present in each creative.

📘
Prerequisites
You need an API key with the aperture scope. This is a separate scope from scoring, so a key that works against the Scoring API will not necessarily work here. Submitting requires aperture:read_write and reading job status requires aperture:read. Contact your Vidmob account team to confirm your key has the right scope.

What the Tags API Returns

For each submitted creative, Vidmob returns a row per detected tag, covering visual elements, people, brand signals, audio, and more. Results are delivered as a CSV report rather than inline in the API response. See What is in the report for the exact columns.

How It Works

Tagging is asynchronous and has two steps.

Create a job. Submit a list of creatives and receive a jobId.
Poll the job. Check status until it reaches a terminal value, then download the CSV report from the link in the response.

Step 1 - Create a Tagging Job

Submit your creatives with POST /v1/media/aperture. You can submit up to 200 creatives in a single job.

curl -X POST https://public-api.vidmob.com/v1/media/aperture \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "creatives": [
      { "id": "creative-001", "url": "https://your-cdn.com/creative-a.mp4" },
      { "id": "creative-002", "url": "https://your-cdn.com/creative-b.mp4" }
    ],
    "clientTags": {
      "brand": "acme",
      "channels": "meta,tiktok"
    }
  }'

Request body

Field	Required	Description
`creatives`	Yes	Array of creatives to tag. Minimum 1, maximum 200 per job.
`creatives[].id`	Yes	Your own identifier for the creative. Vidmob echoes it back and uses it as the row key in the report, so use something you can join on.
`creatives[].url`	Yes	Publicly reachable URL from which Vidmob can download the media.
`clientTags`	Yes	Flat object of string key/value pairs, maximum 10 pairs. Send `{}` if you have nothing to attach.

Two constraints catch most integrators:

clientTags is required. Omitting it returns a 400. Send an empty object if you do not need it.
clientTags is a flat map of strings, not a list of objects. {"brand":"acme"} is valid. [{"label":"acme"}] is not.

clientTags are metadata that Vidmob stores against the job and returns on every read. They are a convenience for your own bookkeeping, so you can label a job by brand, market, or campaign and recognize it later. They do not influence the AI analysis.

Response

{
  "jobId": "07fd81fc-41fc-41f6-90ea-72bf141996dc",
  "status": "QUEUED",
  "dateCreated": "2026-08-25T14:30:00.000Z",
  "creativeIdentifiers": ["creative-001", "creative-002"],
  "clientTags": { "brand": "acme", "channels": "meta,tiktok" }
}

Store the jobId. It is the only handle to the job. There is no way to list your past jobs or to look a job up by creative ID or URL, so if you lose thejobId, you cannot recover the results and would have to resubmit the creatives.

Step 2 - Poll the Job and Download the Report

Check job status with GET /v1/media/aperture/{jobId}.

curl -H "Authorization: Bearer $API_KEY" \
  https://public-api.vidmob.com/v1/media/aperture/07fd81fc-41fc-41f6-90ea-72bf141996dc

{
  "jobId": "07fd81fc-41fc-41f6-90ea-72bf141996dc",
  "status": "COMPLETED",
  "dateCreated": "2026-08-25T14:30:00.000Z",
  "dateUpdated": "2026-08-25T14:52:10.000Z",
  "downloadUrlCsv": "https://<signed-s3-url>",
  "creativeIdentifiers": ["creative-001", "creative-002"],
  "clientTags": { "brand": "acme", "channels": "meta,tiktok" }
}

Status values

Status	Terminal	Meaning
`QUEUED`	No	Job accepted, not started yet.
`PROCESSING`	No	Media is downloading and being analyzed. The `message` field reports progress, for example "Job is in progress. Processed 3 out of 10 media."
`COMPLETED`	Yes	Every creative was tagged. `downloadUrlCsv` is populated.
`PARTIAL_SUCCESS`	Yes	Some creatives were tagged, and some failed. `downloadUrlCsv` is populated and covers the ones that succeeded. `errors` lists the failures.
`FAILED`	Yes	No creative could be tagged. There is no report to download. `errors` Lists the reasons.

Response fields

Field	When present	Description
`jobId`	Always	The job identifier.
`status`	Always	See the table above.
`dateCreated`	Always	When the job was submitted.
`creativeIdentifiers`	Always	The `id` values you submitted.
`clientTags`	Always	The tags you attached at submission.
`message`	While `PROCESSING`	Human-readable progress counter.
`dateUpdated`	On `COMPLETED`, `PARTIAL_SUCCESS`, `FAILED`	When the job reached its terminal state.
`downloadUrlCsv`	On `COMPLETED`, `PARTIAL_SUCCESS`	Signed link to the CSV report.
`errors`	On `PARTIAL_SUCCESS`, `FAILED`	Object keyed by your creative `id`, with the reason each one failed.

Per-creative failure reasons are:

Received invalid URL for the creative.
Download failed for the creative.
Tags could not be generated for the creative.

⚠️
The download link is time-limited
downloadUrlCsv is a signed URL that expires. Download the report promptly, or call GET /v1/media/aperture/{jobId} again to mint a fresh link. The jobId does not expire; the link does.

What is in the report

The CSV has one row per detected tag per creative, with these columns:

Column	Description
`creative_identifier`	The `id` you submitted.
`vidmob_media_id`	Vidmob's internal media ID.
`file_type`	Media file type.
`duration`	Media duration.
`aspect_ratio`	Media aspect ratio.
`type`	The kind of tag on this row.
`value`	The detected value.
`confidence`	Model confidence for the detection.
`start_seconds`	Where the detection starts in the media.
`duration_seconds`	How long the detection persists.
`bounding_box_width`, `bounding_box_height`, `bounding_box_left`, `bounding_box_top`	On-screen position of the detection, where applicable.
`tag_hierarchy_level_1` through `tag_hierarchy_level_6`	The tag's place in Vidmob's tag taxonomy, from broadest to most specific.

Errors

Status	Cause
`400`	Request body failed validation. Common causes: `clientTags` missing, more than 10 `clientTags` pairs, more than 200 creatives, empty `creatives` array, a creative missing `id` or `url`, or a URL Vidmob rejects as unsafe.
`401`	Missing or invalid API key.
`403`	The key lacks the `aperture` scope, or you requested a job that belongs to a different organization.
`404`	No job with that `jobId`.

Behavior to Plan For

There is no lookup for already-tagged creatives. The API is job-oriented. You cannot query "have you already tagged this URL," and you cannot list past jobs. Keep your own mapping of creative ID to jobId.

Resubmitting a creative re-analyzes it. There is no deduplication. If you submit the same creative twice, Vidmob downloads and analyzes it twice, resulting in two independent jobs. Cache the results on your side rather than resubmitting to re-read them.

Batch your submissions. One job with 50 creatives is better than 50 jobs with one creative each.

Poll at a sensible interval. Tagging time scales with the number and length of your media. Polling every few minutes is appropriate. Polling every few seconds is not.

Scoring and Tagging Together

The two APIs are complementary and often used together.

The Tags API tells you what is in a creative. Useful for content inventory, analysis, and understanding creative elements across a library.
The 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 a guideline in your score results comes back with no data and a reason that points at missing or incomplete tags, the asset needs to go through the Tags API before that guideline can be evaluated. Submit it for tagging, then re-trigger scoring.