Migrate clip/convert to V3 actions; add background clip support, redirect legacy route; update frontend guide

documentation/GUIDE__AE_API_V3_for_Frontend.md

@@ -60,7 +60,7 @@ The primary way to retrieve data.
 
 ### C. POST Create / PATCH Update
 Modify data in the system.
-*   **Endpoints:** 
+*   **Endpoints:**
     *   `POST /v3/crud/{obj_type}/`
     *   `PATCH /v3/crud/{obj_type}/{id}`
 *   **Strict Mode (Default):** The API validates your payload against the Pydantic model. If you send fields that do not exist in the model, the database might return a 400 "Unknown column" error.
@@ -123,6 +123,38 @@ Every Event File (`event_file`) **must** have a linked Hosted File (`hosted_file
 
 ---
 
+## 6. Hosted File Actions: Convert & Clip (Frontend Notes)
+
+These helper endpoints let the frontend request small server-side transformations without uploading new blobs. They return a newly-created `hosted_file` metadata object on success.
+
+- **Convert (PDF → Image)**
+  - Method: `GET`
+  - Path: `/v3/action/hosted_file/{hosted_file_id}/convert_file`
+  - Required query params: `link_to_type`, `link_to_id`
+  - Optional query params: `filename_no_ext` (defaults to `automated_hosted_file_conversion`), `to_type` (defaults to `webp`)
+  - Auth: standard V3 headers (`x-aether-api-key`, `x-account-id` / `x-no-account-id` / `?jwt=`)
+  - Behavior: converts the first page of a PDF to `webp` or `png`, saves a new `hosted_file`, and returns its metadata. Returns 400 on failure.
+
+- **Clip Video**
+  - Method: `GET`
+  - Path: `/v3/action/hosted_file/{hosted_file_id}/clip_video`
+  - Required query params: `link_to_type`, `link_to_id`, `start_time`, `end_time` (format `HH:MM:SS`)
+  - Optional query params: `filename_no_ext` (defaults to `automated_hosted_file_clip_video`), `reencode` (bool), `scale_down` (bool)
+  - Auth: standard V3 headers
+  - Behavior: extracts a clip using `ffmpeg` and saves it as a new `hosted_file`. Defaults to stream-copying to be fast; set `reencode=true` to force H.264 or `scale_down=true` to resize. Returns 400 on failure.
+   - Behavior: extracts a clip using `ffmpeg` and saves it as a new `hosted_file`.
+     - Defaults to stream-copying to be fast; set `reencode=true` to force H.264 or `scale_down=true` to resize.
+     - For longer-running clips you can schedule the job in the background by adding `?background=true`. When scheduled the API returns `202 Accepted` and the clip runs asynchronously on the server; check the returned `hosted_file` record later via the standard V3 `hosted_file` endpoints.
+     - Returns 400 on synchronous failure; returns 202 when scheduled successfully.
+
+Frontend guidance:
+
+- Call these routes with the same `link_to_type` / `link_to_id` you plan to associate the resulting hosted_file with — the server resolves random IDs for you.
+- After a successful response, use the V3 `hosted_file` action endpoints (download/delete) to manage or retrieve the new file.
+- These endpoints run synchronously and can take time for large inputs; for heavy or batch workloads use a queued job pattern instead.
+ - These endpoints may take time for large inputs. Prefer using `?background=true` to schedule work and receive a `202 Accepted` response for async processing. For heavy or batch workloads use a queued job pattern instead.
+
+
 ## 5. Troubleshooting 403 Forbidden
 
 If you receive a 403 on a valid ID: