Scene VLM Stats API¶

Endpoint: /api/v1/file/{file_uuid}/scene-vlm-stats
Method: GET
Purpose: 快速获取文件的 Scene VLM 统计数据

Overview¶

Scope: File processing statistics
Status: Active
Applicable to: All registered files with Scene VLM processing

Request¶

Parameters¶

Parameter	Type	Location	Required	Description
`file_uuid`	String	Path	Yes	File UUID

Example¶

curl http://localhost:3002/api/v1/file/dac75694ee550ff57d74f26391fcc751/scene-vlm-stats

Response¶

Success (200 OK)¶

{
  "total_scenes": 2,
  "status": "completed",
  "vlm_done": 2,
  "vlm_total": 2
}

Fields¶

Field	Type	Description
`total_scenes`	i64	Total number of scenes detected
`status`	String	Scene VLM processing status (`pending`, `processing`, `completed`)
`vlm_done`	i64	Number of scenes with VLM descriptions completed
`vlm_total`	i64	Total scenes needing VLM processing

Default Response¶

If the file has no scenes file:

{
  "total_scenes": 0,
  "status": "",
  "vlm_done": 0,
  "vlm_total": 0
}

Performance¶

Response Time: < 10ms

Why Fast: - Directly reads {file_uuid}.scenes.json - No database queries - No complex calculations

Use Cases¶

1. UI Display¶

Display Scene VLM progress in Library view:

const stats = await loadSceneVlmStats(fileUuid)
console.log(`${stats.vlm_done}/${stats.vlm_total} scenes completed`)

2. Performance Optimization¶

Replace expensive get_file_stats call: - Old: get_file_stats - 100-500ms - New: scene-vlm-stats - < 10ms - Improvement: 10-50x faster

3. Real-time Updates¶

Poll for Scene VLM progress without heavy API load:

setInterval(() => {
  loadSceneVlmStats(fileUuid)
}, 5000)

Implementation Details¶

Backend¶

File: src/api/scan.rs:1647

Logic: 1. Check if {file_uuid}.scenes.json exists 2. Read JSON file 3. Parse and count scenes 4. Return statistics

Code:

async fn get_scene_vlm_stats(
    Path(file_uuid): Path<String>,
) -> Result<Json<SceneVlmStats>, StatusCode> {
    let scenes_path = format!("{}/{}.scenes.json", output_dir, file_uuid);

    if !Path::new(&scenes_path).exists() {
        return Ok(Json(SceneVlmStats::default()));
    }

    let scenes_json = std::fs::read_to_string(&scenes_path)?;
    let scenes_data: Value = serde_json::from_str(&scenes_json)?;

    // ... parse and return stats
}

Error Handling¶

File Not Found¶

Status: 200 OK
Response: Default values (all zeros)

Parse Error¶

Status: 500 Internal Server Error

Note: Rare case, indicates corrupted JSON file

GET /api/v1/file/{file_uuid} - Full file info (slower)
GET /api/v1/file/{file_uuid}/processor-counts - Processor counts
GET /api/v1/stats/file/{file_uuid} - Detailed stats (slower)

Best Practices¶

1. Use for Scene VLM Progress¶

Recommended: Use this API for Scene VLM progress display Avoid: Using get_file_stats for simple Scene VLM stats

2. Caching¶

Frontend should cache results:

if (fileStatsCache.value[fileUuid].scene_vlm) {
  return fileStatsCache.value[fileUuid].scene_vlm
}

3. Error Handling¶

Always handle failures gracefully:

try {
  const stats = await loadSceneVlmStats(fileUuid)
} catch (e) {
  console.warn('Scene VLM stats failed:', e)
  // Use cached data or show 'Unknown'
}

Version History¶

Version	Date	Changes
1.0.0	2026-10-14	Initial API endpoint

Cross-References¶

Frontend Integration: Studio team commit 3e7eba0
Test Script: momentry_studio/scripts/test_scene_vlm_api.sh
Backend Code: src/api/scan.rs:1647

Last Updated: 2026-10-14