Local Files and Uploads
How input images and videos are uploaded and cut out, and the limits that apply.
What an input can be
--product, --model, --still and tufty upload all accept:
- a local path
- a
data:URL - an http(s) URL
The server only accepts files hosted on tufty storage, so the CLI first turns each input into a tufty storage URL:
| Input | What the CLI does |
|---|---|
Local file, data: URL | Uploads it to tufty storage |
URL on static.tufty.ai | Uses it as-is, no re-upload |
| Any other http(s) URL | Downloads it, then uploads it to tufty storage |
Uploads go straight to storage through a URL signed by the server. The API key is only ever sent to tufty.ai — never to storage or to third-party downloads.
Checked before anything is uploaded
These checks all run before the first upload; if any fails, nothing is uploaded or charged:
- the number of inputs matches what the tool needs (
missing_input/too_many_inputs) - local files exist (
file_not_found) - the total number of images in the run is within the limit (
too_many_images) - option values are allowed (
usage_error)
Automatic cutout
Image inputs are analyzed and cut out by default, separating the subject from its background before generation. Each input image costs 1 credit:
- Image tools: every product image (including each one joined with
+) and every model image costs 1 credit. - Video tools: every still costs 1 credit.
If no subject is found or the cutout can't be used, the CLI says so on stderr and carries on with the uploaded original. When your image is already a clean subject shot, skip the step with --no-cutout:
tufty pet-dressup --product ./sweater.jpg --model ./corgi-cutout.png --no-cutoutSeveral shots of one product
Join shots of the same product with + to submit them as one product, up to 4:
tufty pet-dressup --product ./hoodie-front.jpg+./hoodie-back.jpg --model ./corgi.jpg- A filename that itself contains
+isn't split if that file exists;data:URLs are never split. - Write a literal
+inside a URL as%2B.
Limits
| Limit | Maximum |
|---|---|
Products per --product (a + group counts as one) | 8 |
| Images per product | 4 |
Model images per --model | 8 |
Images per run (products × models × --count) | 16 |
--still images | Exactly 1 for Image to Video |
Video integrity check
Before uploading an mp4, mov or m4v, the CLI checks the file structure. A truncated file or one missing its moov index returns invalid_video (exit code 2) instead of uploading a broken file.
tufty upload
tufty upload ./corgi.jpg
tufty upload https://example.com/sweater.jpg --format urlPrints { tool: "upload", data: { url } }. A URL already on static.tufty.ai is returned as-is, and needs no sign-in. You can pass the resulting URL straight to a tool, which saves re-uploading an image you use more than once.