TMDb Enrichment

Offline operation: TMDb prefetch now checks local identity files first (identities/_index.json + *.tmdb.json). If local files exist, no external API call is made. Internet is only needed for initial data seeding.

Overview

TMDb enrichment is an optional identity enrichment step that can be run after Pipeline face detection completes. The workflow is:

1. Prefetch (requires internet): Download movie cast data from TMDb API → cache to {file_uuid}.tmdb.json
2. Probe: Read local cache → create identities for all cast members (source='tmdb') + save identity.json + download profile image to {OUTPUT}/identities/{uuid}/profile.jpg
3. Match: The worker automatically matches video faces against TMDb identities when MOMENTRY_TMDB_PROBE_ENABLED=true

POST /api/v1/agents/tmdb/prefetch

Auth: Required Scope: file-level

Fetch TMDb cast data for a registered file and cache it locally. This is the only step requiring internet access.

Request Parameters

Example

curl -s -X POST "$API/api/v1/agents/tmdb/prefetch" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $KEY" \
  -d '{"file_uuid": "'"$FILE_UUID"'"}'

Response (200)

{"success": true, "file_uuid": "...", "cache_path": "/output/...tmdb.json"}

POST /api/v1/file/:file_uuid/tmdb-probe

Auth: Required Scope: file-level

Read local TMDb cache and create/update identities. Requires prefetch to have been run first.

Example

curl -s -X POST "$API/api/v1/file/$FILE_UUID/tmdb-probe" \
  -H "X-API-Key: $KEY" | jq '{identities_created, movie_title}'

Response (200 — identities created)

{"success": true, "identities_created": 15, "movie_title": "Charade"}

Response (200 — no cache)

{"success": false, "message": "No TMDb cache found. Run tmdb-prefetch first."}

GET /api/v1/resource/tmdb

Auth: Required Scope: system-level

View TMDb resource status including configuration, identity counts, and cache file count.

Example

curl -s "$API/api/v1/resource/tmdb" -H "X-API-Key: $KEY" \
  | jq '{identities_seeded, cache_files}'

POST /api/v1/resource/tmdb/check

Auth: Required Scope: system-level

Ping the TMDb API to verify connectivity and measure latency.

Example

curl -s -X POST "$API/api/v1/resource/tmdb/check" \
  -H "X-API-Key: $KEY" | jq '.status'

Response

{
  "api_key_configured": true,
  "enabled": false,
  "api_reachable": true,
  "api_latency_ms": 120
}

POST /api/v1/tmdb/fetch

Auth: Required Scope: system-level

Fetch TMDb data by filename, create identities with profile images and embeddings. Similar to prefetch+probe combined, but also downloads profile images and generates embeddings.

Request Parameters

Example

curl -s -X POST "$API/api/v1/tmdb/fetch" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $KEY" \
  -d '{"filename": "charade.mp4"}'

Response (200)

{
  "success": true,
  "movie_title": "Charade (1963)",
  "tmdb_id": 1234,
  "identities_created": 15,
  "profile_images_downloaded": 12
}

POST /api/v1/agents/tmdb/match/:file_uuid

Auth: Required Scope: file-level

Match TMDb identities to face traces using Qdrant vector similarity. Compares face embeddings against TMDb identity embeddings to find the best matches.

Example

curl -s -X POST "$API/api/v1/agents/tmdb/match/$FILE_UUID" \
  -H "X-API-Key: $KEY"

Response (200)

{
  "success": true,
  "file_uuid": "d3f9ae8e471a1fc4d47022c66091b920",
  "matches": [
    {
      "trace_id": 0,
      "identity_uuid": "a9a90105-6d6b-46ff-92da-0c3c1a57dff4",
      "identity_name": "Audrey Hepburn",
      "confidence": 0.92,
      "tmdb_id": 1234
    }
  ],
  "total_matches": 5
}

TMDb Auto-Match

When MOMENTRY_TMDB_PROBE_ENABLED=true, the worker automatically runs TMDb matching during the post-process phase:

1. Register phase: Searches TMDb by filename, creates identities with tmdb_id/tmdb_profile
2. Post-process phase: Matches detected faces against TMDb identities via cosine similarity using Qdrant

No manual API call needed if auto-match is enabled.

Updated: 2026-06-20 — Added tmdb/fetch and tmdb/match endpoints