05 Process - Momentry API Docs

Processing Pipeline

`POST /api/v1/file/:file_uuid/process`

Auth: Required Scope: file-level

Trigger the processing pipeline for a registered file. Creates a monitor job that the worker picks up and processes sequentially. Returns immediately with the job info—processing runs asynchronously in the background.

Request Parameters

Field	Type	Required	Default	Description
`processors`	string[]	No	all	Specific processors to run: `["cut","asr","asrx","yolo","ocr","face","pose","visual_chunk","story","5w1h"]`
`rules`	string[]	No	all	Rule names to apply (currently unused)

Example

# Run all processors
curl -s -X POST "$API/api/v1/file/$FILE_UUID/process" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $KEY" -d '{}'

# Run specific processors only
curl -s -X POST "$API/api/v1/file/$FILE_UUID/process" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $KEY" \
  -d '{"processors": ["asr", "face", "yolo"]}'

Response (200)

{
  "success": true,
  "job_id": 42,
  "file_uuid": "3a6c1865...",
  "status": "processing",
  "pids": [12345, 12346],
  "message": "Processing triggered for video.mp4"
}

Field	Type	Description
`success`	boolean	Always true on 200
`job_id`	integer	Monitor job ID (for job tracking)
`file_uuid`	string	32-char hex UUID of the file
`status`	string	`"queued"` — file enters the FIFO queue
`pids`	integer[]	Process IDs of started processors (empty for queued)
`message`	string	Human-readable status

Error Responses

HTTP	When
`404`	File UUID not found
`401`	Missing or invalid API key

`GET /api/v1/file/:file_uuid/probe`

Auth: Required Scope: file-level

Get ffprobe metadata for a registered file. Returns video/audio stream info, codec details, duration, resolution, and frame rate.

Example

curl -s "$API/api/v1/file/$FILE_UUID/probe" -H "X-API-Key: $KEY"

Response (200)

{
  "file_uuid": "3a6c1865...",
  "file_name": "video.mp4",
  "file_size": 794863677,
  "duration": 120.5,
  "width": 1920,
  "height": 1080,
  "fps": 24.0,
  "total_frames": 2892,
  "cached": true,
  "format": {
    "filename": "/path/to/video.mp4",
    "format_name": "mov,mp4,m4a,3gp",
    "duration": "120.5",
    "size": "12345678",
    "bit_rate": "819200"
  },
  "streams": [
    {
      "index": 0,
      "codec_name": "h264",
      "codec_type": "video",
      "width": 1920,
      "height": 1080,
      "r_frame_rate": "24/1",
      "duration": "120.5"
    }
  ]
}

Field	Type	Description
`file_uuid`	string	32-char hex UUID
`file_name`	string	File name
`file_size`	integer	File size in bytes (from filesystem)
`duration`	float	Duration in seconds
`width`	integer	Video width in pixels
`height`	integer	Video height in pixels
`fps`	float	Frames per second
`total_frames`	integer	Estimated total frames
`cached`	boolean	True if result was from cached probe JSON
`format`	object	Container format info (ffprobe format section)
`streams`	array	Array of stream info objects

`POST /api/v1/progress/:file_uuid`

Auth: Required Scope: file-level

Get real-time processing progress for a file via Redis pub/sub. Includes per-processor status, current/total frames, ETA, and system resource stats.

Note: This endpoint uses POST method, not GET. The progress data is stored in Redis as a hash, and POST is used to retrieve the latest state.

Pipeline Order

Order	Processor	Dependencies	Description
1	`cut`	—	Scene detection
2	`asr`	cut	Speech-to-text (per scene)
3	`asrx`	asr	Speaker diarization
4	`yolo`	—	Object detection
5	`ocr`	—	Text recognition
6	`face`	—	Face detection & embedding (8Hz sampling)
7	`face_trace`	face	Face tracking (IoU + embedding, assigns trace_id)
8	`pose`	face_trace	Pose expansion from face traces, inherits trace_id
9	`appearance`	pose	Appearance expansion from pose traces, inherits trace_id

Key Concepts: - Face = Identity anchor (who is this person?) — requires high-quality embedding - Pose = Tracking (where is this person?) — extends tracking when face is occluded - Appearance = Tracking (what do they look like?) — extends tracking when pose is occluded

Trace ID Inheritance:

Face trace (identity anchor)
    ↓ inherits trace_id
Pose expansion (tracking continuity)
    ↓ inherits trace_id
Appearance expansion (tracking continuity)

Frame Count Relationship:

face frames ≤ pose frames ≤ appearance frames

(Each level expands outward from the previous level's traces)

All processors except story and 5w1h run concurrently when their dependencies are met. Story and 5W1H run sequentially after their prerequisites.

Example

curl -s -X POST "$API/api/v1/progress/$FILE_UUID" -H "X-API-Key: $KEY" | jq '{overall_progress, processors: [.processors[] | {name, status}]}'

Response (200)

{
  "file_uuid": "3a6c1865...",
  "overall_progress": 71,
  "cpu_percent": 45.2,
  "gpu_percent": 30.1,
  "memory_percent": 62.4,
  "processors": [
    {"processor_type": "asr", "status": "complete", "progress": 100},
    {"processor_type": "yolo", "status": "running", "progress": 65},
    {"processor_type": "face", "status": "pending", "progress": 0}
  ]
}

Field	Type	Description
`file_uuid`	string	32-char hex UUID
`overall_progress`	integer	Overall progress percentage (0–100)
`processors`	array	Per-processor status list
`processors[].processor_type`	string	Processor name (`asr`, `cut`, `yolo`, etc.)
`processors[].status`	string	`"pending"`, `"running"`, `"complete"`, or `"failed"`
`processors[].progress`	integer	Per-processor progress (0–100)
`processors[].eta_seconds`	integer	Estimated seconds remaining (running processors)
`processors[].current`	integer	Current frame count
`processors[].total`	integer	Total frame count
`cpu_percent`	float	Current CPU usage
`gpu_percent`	float	Current GPU utilization
`memory_percent`	float	Current memory usage

`GET /api/v1/jobs`

Auth: Required Scope: system-level

List all processing jobs (monitor jobs) in the system. Shows job status, which file each job is processing, and current processor info.

Example

curl -s "$API/api/v1/jobs" -H "X-API-Key: $KEY" | jq '{count, jobs: [.jobs[] | {uuid, status}]}'

Response (200)

{
  "jobs": [
    {
      "id": 42,
      "uuid": "3a6c1865...",
      "status": "running",
      "current_processor": "yolo",
      "created_at": "2026-05-16T12:00:00Z",
      "started_at": "2026-05-16T12:01:00Z"
    }
  ],
  "count": 15,
  "page": 1,
  "page_size": 20
}

Field	Type	Description
`jobs`	array	Array of job info objects
`jobs[].id`	integer	Job ID
`jobs[].uuid`	string	File UUID being processed
`jobs[].status`	string	`"pending"`, `"running"`, `"completed"`, `"failed"`
`jobs[].current_processor`	string	Currently active processor, or null
`count`	integer	Total job count
`page`	integer	Current page number
`page_size`	integer	Jobs per page

`GET /api/v1/job/:uuid`

Auth: Required Scope: file-level

Get detailed information about a specific processing job, including its queue position.

Response (200)

{
  "id": 51,
  "uuid": "c36f35685177c981aa139b66bbbccc5b",
  "status": "queued",
  "current_processor": null,
  "progress_current": 0,
  "progress_total": 0,
  "processors": [],
  "created_at": "2026-06-22 23:08:48.497018",
  "started_at": null,
  "updated_at": null,
  "queue_position": 3
}

Field	Type	Description
`id`	integer	Monitor job ID
`uuid`	string	File UUID
`status`	string	`"pending"`, `"queued"`, `"running"`, `"completed"`, `"failed"`
`current_processor`	string	Currently active processor, or null
`progress_current`	integer	Current progress count
`progress_total`	integer	Total progress count
`processors`	array	Processor list
`created_at`	string	Job creation timestamp
`started_at`	string	Processing start timestamp, or null
`updated_at`	string	Last update timestamp, or null
`queue_position`	integer	Position in FIFO queue (null if not pending/queued)

Status Lifecycle

register ──→ pending
                  │
            trigger (POST /process)
                  │
              queued ←── queue_position counts jobs ahead
                  │
            worker picks up
                  │
            processing
                  │
         ┌────────┴────────┐
         ▼                  ▼
    completed             failed
         │
    checkin ──→ indexed
    checkout ──→ checked_out

Status	Meaning
`pending`	File registered, not yet triggered
`queued`	Triggered, waiting for worker in FIFO queue
`processing`	Worker actively processing
`completed`	All processors finished successfully
`failed`	One or more essential processors failed
`indexed`	Post-processing checkin complete
`checked_out`	User checked out the file

Queue order is FIFO (created_at ASC). The GET /api/v1/job/:uuid endpoint returns queue_position showing how many jobs are ahead.

Frontend Status Mapping

When displaying file status in the frontend list (e.g. after GET /api/v1/files/scan), map the status field as follows:

DB Status	Status Label	Filter: 待處理	Filter: 處理中	Count: pendingCount	Count: processingCount
`unregistered`	未註冊	No	No	No	No
`registered`	待處理	Yes	No	Yes	No
`pending`	待處理	Yes	No	Yes	No
`queued`	排隊中	Yes	Yes	Yes	Yes
`processing`	處理中	No	Yes	No	Yes
`completed`	已完成	No	No	No	No
`failed`	處理失敗	No	No	No	No
`indexed`	已入庫	No	No	No	No

queued 的特殊處理： - statusLabel → 顯示「排隊中」，加 ms-badge-warn 樣式（黃色） - filterPending → 應包含 queued，讓它在「待處理」filter 可見 - pendingCount + processingCount → 兩者都應包含 queued，因它既是「待處理」也是「正在排隊」 - 在 refreshAllStatus / loadFiles 中，如果檔案狀態是 queued，應顯示簡單的排隊訊息（無需 polling progress） - 當 worker pickup 後，狀態會變為 processing，此時 refreshAllStatus 會自動偵測到並開始 polling progress - 也可以提供一個「queue_position」顯示：呼叫 GET /api/v1/job/:uuid 取得排在第幾位

`GET /api/v1/file/:file_uuid/processor-counts`

Auth: Required Scope: file-level

Get counts of processor JSON output files. See 15_tkg.md for full documentation.

Pipeline Steps (Manual)

These endpoints execute individual pipeline steps. They are typically called by the worker automatically, but can be invoked manually for debugging or re-processing.

`POST /api/v1/file/:file_uuid/store-asrx`

Auth: Required Scope: file-level

Store ASRX diarization results as chunk records in the database. Converts ASRX segments into searchable chunk entries.

Example

curl -s -X POST "$API/api/v1/file/$FILE_UUID/store-asrx" \
  -H "X-API-Key: $KEY"

Response (200)

{
  "success": true,
  "message": "ASRX chunks stored",
  "file_uuid": "3a6c1865..."
}

`POST /api/v1/file/:file_uuid/rule1`

Auth: Required Scope: file-level

Execute Rule 1 pipeline step. Applies rule-based chunking to create structured chunk records from processor outputs.

Example

curl -s -X POST "$API/api/v1/file/$FILE_UUID/rule1" \
  -H "X-API-Key: $KEY"

Response (200)

{
  "success": true,
  "message": "Rule 1 complete: 45 chunks",
  "file_uuid": "3a6c1865...",
  "chunks": 45
}

Field	Type	Description
`success`	boolean	Always true on 200
`message`	string	Human-readable completion message
`file_uuid`	string	32-char hex UUID
`chunks`	integer	Number of chunks produced

`POST /api/v1/file/:file_uuid/vectorize`

Auth: Required Scope: file-level

Generate vector embeddings for all chunks of a file and store them in Qdrant for semantic search.

Example

curl -s -X POST "$API/api/v1/file/$FILE_UUID/vectorize" \
  -H "X-API-Key: $KEY"

Response (200)

{
  "success": true,
  "message": "Vectorization complete",
  "file_uuid": "3a6c1865..."
}

`POST /api/v1/file/:file_uuid/phase1`

Auth: Required Scope: file-level

Execute Phase 1 of the post-processing pipeline. Combines store-asrx, rule1, and vectorize into a single step.

Example

curl -s -X POST "$API/api/v1/file/$FILE_UUID/phase1" \
  -H "X-API-Key: $KEY"

Response (200)

{
  "success": true,
  "message": "Phase 1 complete",
  "file_uuid": "3a6c1865..."
}

`POST /api/v1/file/:file_uuid/complete`

Auth: Required Scope: file-level

Mark a video as fully processed. Updates the video status to completed and finalizes all pipeline state.

Example

curl -s -X POST "$API/api/v1/file/$FILE_UUID/complete" \
  -H "X-API-Key: $KEY"

Response (200)

{
  "success": true,
  "message": "Video marked as completed",
  "file_uuid": "3a6c1865..."
}

Pipeline Step Order

  process (trigger)
    │
    ├─→ cut, yolo, ocr, face, pose, asrx (parallel processors)
    │
    ├─→ store-asrx  (store diarization as chunks)
    │
    ├─→ rule1       (rule-based chunking)
    │
    ├─→ vectorize   (embed chunks to Qdrant)
    │
    └─→ complete    (mark done)

Phase 1 (/phase1) combines store-asrx + rule1 + vectorize into one call.

Updated: 2026-06-23 — Added queued status, FIFO queue order, queue_position in job detail, frontend status mapping table