Asset Import 是做什麼的？
此建置會在本地執行編輯器及其媒體伺服器。沒有託管的匯入 API、沒有 CLI、也沒有 OAuth：媒體透過編輯器 UI 或以下的代理工具進入專案。根據位元組所在的位置選擇路徑。
路徑 1 — 使用者的本地檔案（主要方式）
請使用者將檔案拖曳到編輯器中（預覽畫布或「我的素材」面板），或使用上傳按鈕。之後本地管道會自動執行：串流寫入 /media/uploads/、有條件轉碼（長邊 ≤1920、瀏覽器友善編碼、約 8Mbps）、音訊擷取，以及自動轉錄（上傳時 ASR 即啟動）。請不要要求使用者自行預先轉換、預先修剪或轉碼 — 管道會處理一切。
代理無法讀取使用者的檔案系統。如果使用者提供 /Users/... 或 C:\... 路徑，請告訴他們將該檔案放入編輯器；代理無法擷取。
路徑 2 — 公開 URL（代理驅動）
使用 download_media 搭配單一 URL 或批次陣列。伺服器會擷取、儲存到 /media/uploads/ 底下，並註冊為素材庫資產。偏好此方式處理使用者指向的庫存/網路媒體。下載後，該資產的行為與任何其他媒體庫資產相同。
路徑 3 — 外部主機傳輸
呼叫 import_media 並傳入 {"action":"create_session", "assetType":..., "filename":..., "contentType":..., "size":...}。它會回傳一個短期上傳時段，綁定到目前專案、工作階段、資產識別、基礎檔名、POST、MIME 類型及精確位元組數。外部主機腳本可以使用宣告的標頭將資料上傳到該精確 URL。代理沙盒無法存取使用者的本地主機，因此不要嘗試從 run_code 進行傳輸。
成功上傳的回應會回傳一個不透明收據、回應的 assetType 以及上傳路徑。在需要確定時長、尺寸、fps 或音訊是否存在時，請探查上傳路徑，然後使用收據、回應的 assetType、測量到的媒體中繼資料以及音訊/影片/gif 的 durationInSeconds 來呼叫 finalize_uploaded_asset。伺服器會解析權威雜湊、路徑、大小、檔名和資產 ID。finalize_uploaded_asset 會提交資產，但絕不會啟動 ASR；將音訊/影片資產放到軌道上後，如果需要轉錄，請分別呼叫 transcribe_track。在 finalize_uploaded_asset 成功之前，資產不會存在亦無法使用。若要取代缺少的媒體，請將現有的 assetId 傳遞給 import_media；若要建立新資產則省略。切勿自行建構 /media/uploads/... 路徑，也切勿在上傳回應尚未回來之前聲稱位元組已就緒。
編輯紀律
對於多來源編輯，請在 OpenChatCut 時間軸上從原始來源資產建立可審查的作品。不要在匯入前於本地拼接、預先修剪、預先合成、燒錄字幕或平面化媒體 — 請匯入原始檔案並在時間軸上完成所有合成，使每一步都可審查且可復原。
對於程式碼資產（例如手寫動態圖形），請使用 create-motion-graphics 技能（新資產用 create_motion_graphic_from_code，編輯則更新資產程式碼）— MG 程式碼不是匯入的檔案。
儲存注意事項
- 位元組存在本地磁碟上（
/media/uploads/），直接提供 Range 支援。如果已設定 Cloudflare R2，上傳會鏡像到 R2，其他裝置可從中取得資料；沒有 R2 時，專案僅限本地。 - 僅限本地是完全有效的終狀態：預覽、編輯和匯出都從磁碟讀取。雲端鏡像僅在跨裝置存取時需要。