tmdb API

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
}

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

Field	Type	Required	Description
filename	string	Yes	Movie filename to search TMDb for

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
}

Field	Type	Description
matches[].trace_id	integer	Face trace ID
matches[].identity_uuid	string	Matched TMDb identity UUID
matches[].identity_name	string	Identity display name
matches[].confidence	float	Cosine similarity score (0.0–1.0)
matches[].tmdb_id	integer	TMDb person ID
total_matches	integer	Total successful matches

---

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

---

Version History

Version	Date	Changes
1.0	2026-10-24	Initial documentation