| name | asset-import |
| description | Use when acquiring or importing media into a OpenChatCut project asset library for video editing or creation, including local/attached videos, user-provided paths, public media URLs, web video/audio/image assets, upload fallback decisions, and deciding between import_media, download_media, or manual user action. |
Asset Import
This build runs the editor and its media server locally. There is no hosted import API, no CLI, and no OAuth: media enters the project through the editor UI or through the agent tools below. Pick the path by where the bytes live.
Path 1 — user's local files (primary)
Ask the user to drag the files into the editor (preview canvas or 我的素材 panel) or use the upload button. The local pipeline then runs automatically: streaming write to /media/uploads/, conditional transcode (≤1920 long edge, browser-friendly codec, ~8Mbps), audio extraction, and auto-transcription (ASR starts on upload). Do not ask the user to pre-convert, pre-trim, or transcode anything themselves — the pipeline handles it.
The agent cannot read the user's filesystem. If the user gives you a /Users/... or C:\... path, tell them to drop that file into the editor instead; you cannot fetch it.
Path 2 — public URLs (agent-driven)
Use download_media with a single URL or a batch array. The server fetches, stores under /media/uploads/, and registers pool assets. Prefer this for stock/web media the user pointed at. After download, the asset behaves like any other media-pool asset.
Path 3 — external host transfer
Call import_media with {"action":"create_session", "assetType":..., "filename":..., "contentType":..., "size":...}. It returns one short-lived upload slot bound to the current project, session, asset identity, basename, POST, MIME type, and exact byte count. A host-side script may upload to that exact URL with the declared headers. The agent sandbox cannot reach the user's localhost, so do not attempt the transfer from run_code.
The successful upload response returns an opaque receipt, echoed assetType, and uploaded path. Probe the uploaded path when exact duration, dimensions, fps, or audio presence are needed, then call finalize_uploaded_asset with the receipt, echoed assetType, measured media metadata, and durationInSeconds for audio/video/gif. The server resolves the authoritative hash, path, size, filename, and asset id. Finalize commits the asset but never starts ASR; after placing an audio/video asset on a track, invoke transcribe_track separately if transcription is desired. The asset is not present or usable before finalize succeeds. For missing-media replacement, pass the existing assetId to import_media; omit it for a new asset. Never construct /media/uploads/... yourself and never claim bytes are ready before the upload response.
Editing discipline
For multi-source edits, build reviewable work from original source assets in the OpenChatCut timeline. Do not locally concatenate, pre-trim, pre-compose, burn captions, or flatten media before import — import originals and do all composition on the timeline so every step stays reviewable and undoable.
For code assets such as hand-authored Motion Graphics, use the create-motion-graphics skill (create_motion_graphic_from_code for new assets, asset-code updates for edits) — MG code is not an imported file.
Storage notes
- Bytes live on the local disk (
/media/uploads/), served directly with Range support. If Cloudflare R2 is configured, uploads mirror to R2 and other devices can hydrate from it; without R2 the project is local-only.
- Local-only is a valid end state: preview, editing, and export all read from disk. Cloud mirroring is only needed for cross-device access.
