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, --motion-video 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. The
--motion-videoreference is uploaded as-is, never cut out.
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 background-swap --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 and Motion Control; 1–9 for Product Promo Video and Pet Promos |
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.