momentry_core/deliverable_v1.1.0/modules/09_tmdb.md

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

Field	Type	Required	Description
file_uuid	string	Yes	File UUID to enrich

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
}