# Workspace assets Assets stores reusable images, video and audio outside film projects. Upload local media or open AI Create and choose direct model generation or an Agent conversation. The library filters by media type, source and text, with newest/oldest/name sorting and reversible trash. Opening a file switches to an inline workspace: a left asset filmstrip, central preview and right provenance/version inspector. Select a version to preview or download its exact bytes, make an older version current without deleting later history, or continue editing beside the preview. Editing pins the selected parent and reference version and saves a new version without overwriting the original. The gallery and filmstrip share the loaded collection, including media type, source, search, sort and page, so entering or leaving preview does not refetch the list or flash loading cards. Returning to the same collection restores its gallery scroll position. Both side panes support bounded resizing; CSS reserves the navigation width and constrains the inspector to the available workspace without feeding measured widths back into layout. Only explicit resizing changes saved width preferences. My assets in the editor can import an exact library version into the current project; adding it to the composition remains a separate step. The editor’s upload menu offers local upload and library import. A library import waits for pending saves, pins the selected asset/version and verifies the returned project-relative file in the native project listing before closing the picker and showing a floating success notice. My assets clears hiding search/type filters and reveals the imported file first in its media category. A failed list refresh keeps the picker retryable and reuses the completed import; an uncertain transport outcome retains its request ID. Late completions cannot refresh or notify a different project. Opening or dismissing the picker preserves the project sidebar. ## Storage and jobs The installation data directory owns `asset-library/records`, immutable media in `files///`, import request receipts, staging and conversations. Files are private user data and never belong in the checkout or package. Uploads accept at most 500 MB of decodable media. Local imports snapshot regular files without following the final symlink, validate the snapshot and hash the saved bytes before committing metadata under the workspace lock. Stable upload request IDs match content and options, rather than temporary browser-upload paths. A reserved asset identity makes an interrupted metadata commit recoverable without duplicating an asset. Each version records its original name, MIME type, byte count, SHA-256, dimensions/duration when available, origin, prompt, model, request parameters, references, parent version and job/conversation identities. A reference is always `{assetId, versionId}`. Selecting an older current version preserves all versions. Trash hides an asset from normal browsing and new reference/import operations; it does not destroy bytes or alter project copies. An already-submitted generation can finish into a trashed asset without restoring it or discarding the paid result. After trash or restore succeeds, Studio exits that asset’s preview and refreshes the current list and counts without switching the filmstrip to another collection. Late reads or writes cannot replace a later selection. A floating Removed notice provides Undo for the exact asset through the same `update` operation; undo does not change another selected asset, and a failed undo remains retryable. Permanent deletion, shared cloud storage and cross-device sync are not implemented. Model Gateway keeps the existing credentials, providers, OpenDesign account connector, queues, cancellation and failure handling. A library destination needs no project. Before invoking a model for a library job, the worker checks native media readiness and starts both configured FFmpeg and FFprobe binaries. Missing or unusable tools fail the task before model usage; repairing prerequisites does not replay the failed job. Source checkouts can use `HYPERFRAMES_FFMPEG_PATH` and `HYPERFRAMES_FFPROBE_PATH` when the tools are outside PATH. A new multi-output generation creates separate assets; edits append versions to their explicit target. Source files, task IDs and original versions remain available. Compact task rows show queued, creating, saving, completed, cancelled or failed states, with cancellation and exact-result navigation. The unified Tasks popover combines direct model jobs and Agent conversations, with search, type filters and status; pending approvals and active work appear before finished history, then sort by recent activity. A compact Tasks entry remains in both the gallery and asset-preview headers after the creator closes, showing active or awaiting-approval counts. Selecting a task reopens its progress or conversation beside the current preview without changing the selected asset/version. Polling failure preserves known tasks and exposes retry; delayed reads cannot erase a new submission or replace newer progress. Only new saved outputs refresh the library during task polling. Agent-owned generation jobs remain nested under their conversation. History floats over the workspace without moving the gallery. The creator uses one compact toolbar for generation mode, task selection and a new task. Selecting a direct task restores its prompt, model, parameters and pinned references; selecting an Agent task resumes that conversation. Selection and new-task actions never submit generation. A missing model or reference prevents silent substitution. The view uses existing job and conversation records, not a second execution store. Failure details expand in place and never imply a successful output. A cancelled conversation does not automatically cancel submitted media jobs; each job can be cancelled from its task detail. Failed/interrupted generation is never resubmitted automatically. Multi-output completion can leave successfully saved versions if a later output fails; inspect the library and original job before requesting another generation. ## APIs `openmotion_assets` is an additive public protocol-1 tool shared by stdio MCP, WebMCP and Studio's `/motion-api/phase1/call` authority: | Action | Boundary | | --- | --- | | `list`, `get` | Filter/page metadata; inspect versions and provenance | | `import` | Copy a real local file using a stable requestId; optional assetId/parentVersionId appends a version | | `update` | Rename, trash/restore, or select an existing currentVersionId | | `generate` | Explicit model, modality, prompt, stable requestId and optional parameters/references; returns a job | | `jobs`, `status`, `cancel` | Observe or cancel the original library job; no implicit retries | | `import_to_project` | Explicit projectId, assetId, versionId and requestId; ordinary project import/history protection, no timeline placement | Discover available providers and models through `openmotion_media_use` before generating. User credentials stay in model settings. Reference capability is model-specific: local Codex image editing currently accepts one image reference. The Codex adapter reads bounded completion/error events and imports only one fresh, regular raster file from the isolated job directory. It does not import the reference, stale files, symlinks or arbitrary paths from model replies. CLI login and an enabled image feature do not prove image-service authorization: an authorization error remains a failed job with actionable guidance, rather than a missing-filename error. Missing proxy credentials are distinguished from account authorization errors; the active Codex provider must select the configuration matching its endpoint and authentication. OpenMotion inherits that configuration without rewriting it or copying credentials. No automatic paid retry or provider switch occurs. Other configured media models support standalone generation using their existing provider parameters; broad image/video/audio reference editing is not implied. The browser upload endpoint is `POST /motion-api/assets/upload?requestId=...` with binary body and URI-encoded `X-File-Name`. Media `GET`/`HEAD` at `/motion-api/assets//versions//file` supports single byte ranges and attachment downloads. These are local installation routes behind the existing loopback and same-origin boundary, not public remote endpoints. Browser imports use selected Files; external MCP imports require paths readable on the host. ## Conversations Studio's Agent conversation runs the installed Codex CLI's [app-server protocol](https://learn.chatgpt.com/docs/app-server). It initializes the experimental dynamic-tool interface, starts/resumes a persistent thread, streams assistant messages and calls the same asset service through dynamic tools. A private workspace directory scopes the session. The adapter requests read-only sandboxing with on-request approvals; command/file approvals are surfaced to the user, unsupported protocol requests fail explicitly, and generation proposals show their concrete model/prompt/options before submission. No CLI login secrets are copied into OpenMotion conversations. Messages, tool results and thread identity are persisted. Stop terminates the local app-server session; a new user message can resume the thread. Repeated turn request IDs do not start a second paid turn, and stale running state after a service restart is reported as interrupted. Four conversations may run concurrently, with a 30-minute turn timeout. The currently selected Codex model or its configured default drives the conversation. Other local Agents consume the public MCP tool externally; merely detecting a CLI does not establish an in-app execution adapter. The Assets interface maintains English and Chinese copy; new asset-specific labels in other configured locales currently use English fallback. Provider model names, authored prompts and Agent replies retain their original language. ## Verification boundary Deterministic tests cover storage, receipts, version references, generation job ownership, byte-range reads, project imports, protocol streaming, approvals, cancellation and thread resume using a fixture Agent. They do not prove a real paid model request, account quota, every installed CLI version or human visual acceptance. Browser checks cover the opened asset workspace, filters, inline version previews, reference dialogs, uploads, narrow layouts and both themes. Runtime packaging includes these modules and guidance through the maintained distribution list. ## Model-specific creation controls See [generation options](generation-options.md) for the shared Studio/MCP parameter profiles, native field types, model defaults, Codex reasoning controls and validation boundaries. Asset navigation and the creator can be resized by dragging or keyboard, with remembered widths.