YouTube AI Video Classifier — IAB & Custom Labels

Classify public YouTube videos into the top level of IAB Content Taxonomy 3.1 or your own labels. Every label identifies whether it is supported by transcript evidence, public video metadata, or both. Transcript timestamps and metadata excerpts are resolved against trusted source data rather than generated freely by the AI.

This is a focused validation release. It accepts direct video URLs and IDs only and deliberately limits each run to 25 videos.

What makes the output useful

• IAB 3.1 IDs or stable customer-supplied label IDs
• One primary and up to two secondary labels
• Source attribution for every label: transcript, metadata, or both
• Timestamped transcript excerpts and validated metadata signals
• Transcript language, automatic/manual status, and analyzed coverage
• Qualitative confidence and explicit insufficientEvidence
• Model, prompt, classifier, taxonomy, source, and cache provenance
• Item-level failures: one unavailable video does not fail the batch
• No YouTube API key or Gemini key required from the customer

This Actor classifies content for dataset enrichment, contextual discovery, research, cataloging, and routing. It does not detect sponsorships, brand mentions, brand-safety risks, viewer demographics, or monitor new uploads.

Input

IAB 3.1 top-level classification

{
    "videoUrls": [
        "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "https://www.youtube.com/shorts/VIDEO_ID"
    ],
    "taxonomy": "iab-3.1",
    "preferredTranscriptLanguages": ["en", "de"],
    "maxTranscriptCharacters": 24000,
    "concurrency": 2
}

The initial release implements the 37 top-level IAB 3.1 rows. Leaf-level classification is intentionally deferred until demand and accuracy are validated. The output always exposes taxonomy.scope: "top-level" so integrations cannot mistake it for leaf-level coverage.

Custom taxonomy

{
    "videoUrls": ["dQw4w9WgXcQ"],
    "taxonomy": "custom",
    "customLabels": [
        {
            "id": "tutorial",
            "name": "Tutorial",
            "description": "The presenter teaches a repeatable task step by step.",
            "examples": ["coding walkthrough", "repair instructions"],
            "exclusions": ["brief product demonstration without instruction"]
        },
        {
            "id": "review",
            "name": "Review",
            "description": "The presenter evaluates a product, work, or service.",
            "examples": ["hands-on product assessment"],
            "exclusions": ["uncritical announcement"]
        }
    ]
}

Custom taxonomies require 2–25 unique labels. Definitions are important: ambiguous labels produce ambiguous classifications.

Example result

{
    "status": "SUCCEEDED",
    "input": "https://www.youtube.com/watch?v=EXAMPLE_ID",
    "video": {
        "videoId": "EXAMPLE_ID",
        "url": "https://www.youtube.com/watch?v=EXAMPLE_ID",
        "title": "Build a REST API",
        "channelName": "Example Developer"
    },
    "taxonomy": {
        "type": "iab-3.1",
        "version": "3.1",
        "scope": "top-level"
    },
    "classifications": [
        {
            "id": "596",
            "name": "Technology & Computing",
            "rank": "primary",
            "supportSources": ["transcript", "metadata"],
            "evidence": [
                {
                    "segmentId": "S0004",
                    "startMs": 72000,
                    "endMs": 106000,
                    "startTimestamp": "1:12",
                    "endTimestamp": "1:46",
                    "text": "We will create the API routes and connect them to the database..."
                }
            ],
            "metadataEvidence": [
                {
                    "field": "title",
                    "value": "Build a REST API"
                }
            ]
        }
    ],
    "confidence": "high",
    "summary": "A step-by-step tutorial for building a REST API.",
    "topics": ["REST APIs", "routing", "databases"],
    "insufficientEvidence": false,
    "transcript": {
        "languageCode": "en",
        "languageName": "English",
        "isAutoGenerated": false,
        "segmentCount": 184,
        "analyzedWindowCount": 31,
        "coverageRatio": 1,
        "samplingStrategy": "full"
    },
    "provenance": {
        "sources": ["youtube-public-metadata", "youtube-public-captions"],
        "extractor": "yt-dlp-2026.07.04",
        "model": "gemini-3.5-flash-lite",
        "classifierVersion": "0.4.0",
        "promptVersion": "youtube-content-classifier-relay-3",
        "classifiedAt": "2026-08-12T12:00:00.000Z",
        "cacheHit": false
    }
}

Failed items produce status: "FAILED", a stable errorCode, a readable message, and retryable. They are not billable.

Source-attributed evidence and long transcripts

Each classification includes supportSources, which is transcript, metadata, or both. Transcript captions are combined into deterministic evidence windows such as S0004; the model may select only supplied IDs, and the Actor resolves them back to trusted text and timestamps. Metadata evidence contains a field name and an exact value or excerpt. Both the relay and Actor reject metadata text that is not present in the extracted title, description, channel name, declared category, or tags.

A label may be metadata-only when the transcript does not directly establish it. For example, song lyrics are not accepted as transcript proof that a video is a pop-culture meme; an exact title, description, category, or tag must support that claim instead.

When a transcript exceeds maxTranscriptCharacters, windows are selected uniformly from the beginning through the end. coverageRatio describes the fraction of transcript-window characters analyzed; it is not an accuracy score.

Limitations

• Only public videos with accessible captions can receive an evidence classification.
• Private, deleted, members-only, login-walled, and some age-restricted videos are unsupported.
• Live streams may not have a finalized caption track.
• IAB mode covers top-level Content Taxonomy 3.1 categories in this release.
• AI labels are inferences, not YouTube-provided categories or measured audience attributes.
• YouTube may block cloud IPs. Configure an Apify residential proxy if direct extraction becomes unreliable.
• The Actor returns short evidence excerpts, not complete transcripts.

Maintainer setup

The customer never supplies an AI credential. Gemini is accessed through the separately deployed hardened relay in ./relay/README.md; the Gemini key exists only on that static-IP server and is never placed in the Actor.

The Actor needs an encrypted relay URL and one HMAC credential. Follow the relay deployment guide to generate and configure them, then store them with apify secrets add as:

• youtubeClassifierRelayUrl
• youtubeClassifierRelayCredential

.actor/actor.json maps these encrypted values to the Actor environment. The credential signs a narrow classification request; it cannot call Gemini directly or select arbitrary prompts, models, tools, or upstream URLs.

For local development, provide input without putting the key in the command line:

$apify run --input '{"videoUrls":["dQw4w9WgXcQ"],"taxonomy":"iab-3.1"}'

Important environment settings:

Variable	Default	Purpose
CLASSIFIER_RELAY_URL	required	HTTPS URL of the maintainer's hardened relay
CLASSIFIER_RELAY_CREDENTIAL	required	Encrypted JSON containing the relay HMAC key ID and base64 secret
CLASSIFIER_RELAY_TIMEOUT_MS	75000	Actor-to-relay request timeout
ACTOR_DAILY_CLASSIFICATION_LIMIT	90	Secondary, best-effort Actor-side request guard; 0 disables it
YT_DLP_PATH	yt-dlp	Optional override for the pinned caption-extractor binary

The Actor-side guard counts uncached relay attempts, including retries, and resets at midnight Pacific time. It is defense in depth only. The relay is authoritative and centrally enforces durable daily, per-minute, concurrency, payload, and idempotency limits across Actor runs.

Paid Actor event

Configure pay-per-event monetization in Apify Console:

Event	Suggested validation price	When emitted
evidence-classification	$0.012	One schema-valid classification successfully stored

Do not enable a synthetic default-dataset-item charge. Error rows use an uncharged dataset write. The code couples each successful dataset write with evidence-classification via Actor.pushData(result, eventName).

Development

npm install
npm run build
npm test
npm run lint
npm run format:check
apify validate-schema .actor/input_schema.json

The Docker image pins and verifies yt-dlp version 2026.07.04. Update the version and SHA-256 together after running the live caption canary tests.

Data and policy notes

This unofficial Actor is not affiliated with YouTube, Google, or IAB Tech Lab. It accesses public metadata and captions, does not use account cookies, and does not attempt to bypass access restrictions. YouTube access can change and is subject to YouTube's terms and applicable law.

IAB identifiers and names are derived from the IAB Tech Lab Taxonomies repository. yt-dlp is an independent open-source project used solely for public metadata and caption discovery.