Start local file upload
upload_file_startStart uploading a LOCAL video or image file from the user's machine into Flask. It needs a shell that can run curl; without one (a chat app), upload from a public link with upload_video. VIDEO: creates the asset immediately (container_id + shareable url, live before any bytes move) with the file as its version (asset_id / version_id), or a new version of an existing asset with version_of, and returns the shell command (next_step) that sends it while the user watches its progress at the url; then call upload_file_complete(asset_id). IMAGE (content_type image/png, image/jpeg, image/webp or image/gif, max 20MB): returns upload_url and image_url and creates NO asset yet; curl the bytes, then call upload_file_complete(image_url) with the folder_id / version_of / title / team_id you want - the asset is made there. On the free plan new assets are limited (web and agents together); a new version via version_of is always free. When the team has no free assets left, the upload is refused with a message that says how to continue. If the command fails, run it again (it resumes); calling upload_file_start again creates (and counts) another asset. Made with code? Pass notes and files (source.zip) here (an image or zip: to upload_file_complete): the version shows them from the start. LIVE ANIMATION (beta, selected teams): ONLY when the user asks to play an HTML/JS animation live (no render); by default render it and upload the MP4. Upload a zip (content_type application/zip, max 30MB): the page plus the files it loads, flask.json {"entry": "page.html"} (or index.html) at the top, nothing loaded from the network. The page must not run its own loop; it sets window.flaskComposition = { duration (seconds), seek(t) (draw the frame at t), width, height } and Flask calls seek. Returns upload_url and upload_id, NO asset yet; curl the zip, then upload_file_complete(upload_id) with folder_id / version_of / title / team_id. A zip Flask cannot play is refused there with what to fix, creating nothing.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| files | No | Video only (an image or a zip: pass them to upload_file_complete). Files to attach to the version, sent with the upload: by convention the working files that made it as ONE source.zip (the project folder without node_modules, build output or renders; over 30 MB, split into source-1.zip, source-2.zip, ...). Max 30 MB each, 20 per version, names used once. Each comes back with its upload command: run it before the main upload. | |
| notes | No | Video only (an image or a zip: pass it to upload_file_complete, where its version is made). The version's notes, in Markdown: what changed and why (link the feedback it answers), and how to continue (the tools, the command that renders it). Saved with the version, so it shows them from the start; each file's line is put above them for you. Up to 20,000 characters of text. | |
| title | No | Title for the new asset (defaults to "Untitled Video"). For an image, pass it to upload_file_complete instead. | |
| team_id | No | Team to act in: the team.id an earlier result named. Omit for the team selected in the Flask app (which the user can switch at any time). | |
| file_size | Yes | Exact size of the local file in bytes (e.g. from `stat -f%z <file>` on macOS or `stat -c%s <file>` on Linux) | |
| folder_id | No | Optional folder to upload into (you must have edit access - check with permission_get if unsure). Omit to upload to the team's top level (root). For an image, pass it to upload_file_complete instead. | |
| version_of | No | Upload as a NEW VERSION of an existing asset instead of creating a separate asset. Accepts the id of the asset (its container id, what contents/search return), or of any of its versions. The new upload becomes the current version; the asset's url then shows it. folder_id is ignored when version_of is given. | |
| content_type | No | MIME type of the file (defaults to video/mp4). image/png, image/jpeg, image/webp or image/gif uploads an image; application/zip uploads a live animation. |