diff --git a/contracts/rest-api.yaml b/contracts/rest-api.yaml
index 2971303..66dc71b 100644
--- a/contracts/rest-api.yaml
+++ b/contracts/rest-api.yaml
@@ -398,6 +398,25 @@ paths:
       responses:
         '204': { description: 已删除 }
 
+  /api/models/{id}/reanalyze:
+    parameters: [{ $ref: '#/components/parameters/Id' }]
+    post:
+      tags: [models]
+      summary: 重新分析模型并重建缩略图（升级回填 / 文件替换后刷新）
+      description: |
+        重新计算 `stats`（面数、骨骼树、humanoid 覆盖、可驱动性）并重出缩略图，
+        只改这两个字段。用于：升级到带 `stats` 的版本后回填历史模型、
+        模型文件被替换后刷新、缩略图渲染器升级后重出图。
+        批量回填用 `node scripts/reanalyze-models.mjs --url http://127.0.0.1:3000`。
+      responses:
+        '200':
+          description: 重新分析后的模型
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Model' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '409': { description: 模型没有文件资产，无法分析 }
+
   /api/models/{id}/primary:
     parameters: [{ $ref: '#/components/parameters/Id' }]
     post: