CLI
本地文件与上传
输入的图片和视频如何上传、抠图，以及数量限制。
输入可以是什么
--product、--model、--still、--motion-video 和 tufty upload 都接受：
- 本地路径
data:URL- http(s) 地址
服务端只接受托管在 tufty 存储上的文件，所以 CLI 会先把每个输入变成 tufty 存储地址：
| 输入 | CLI 怎么处理 |
|---|---|
本地文件、data: URL | 上传到 tufty 存储 |
static.tufty.ai 上的地址 | 原样使用，不重复上传 |
| 其他 http(s) 地址 | 先下载，再上传到 tufty 存储 |
上传使用服务端签发的地址直传存储。API 密钥只发给 tufty.ai，不会带到存储上传或第三方下载请求里。
先校验，再上传
以下检查在上传之前统一完成，任何一项不通过都不会上传、不会扣费：
- 输入数量是否符合工具要求（
missing_input/too_many_inputs） - 本地文件是否存在（
file_not_found） - 一次出图的总张数是否超限（
too_many_images） - 选项取值是否在允许范围内（
usage_error）
自动抠图
图片输入默认先做一次识别与抠图，把主体从背景中分离出来再提交生成，每张输入图 1 积分：
- 图片工具：每张商品图（包括用
+连接的每一张）和每张模特图各 1 积分； - 视频工具：每张静帧 1 积分。
--motion-video参考视频只上传，不抠图。
没识别到主体、或抠图结果不可用时，CLI 会在标准错误中提示，并改用上传的原图继续。已经是干净主体图时，加 --no-cutout 跳过抠图：
tufty background-swap --model ./corgi-cutout.png --no-cutout同一件商品的多张图
用 + 把同一件商品的几张图连起来，作为一件商品提交，最多 4 张：
tufty pet-dressup --product ./hoodie-front.jpg+./hoodie-back.jpg --model ./corgi.jpg- 文件名本身含
+且该文件存在时不会被拆开；data:URL 也不会被拆开。 - 地址里本身带
+的，请写成%2B。
数量限制
| 限制 | 上限 |
|---|---|
一次 --product 的商品件数（+ 连接的算一件） | 8 |
| 每件商品的图片张数 | 4 |
一次 --model 的模特图 | 8 |
一次出图总张数（商品件数 × 模特图数 × --count） | 16 |
--still 静帧 | 图转视频、运镜控制恰好 1 张；商品短片、萌宠带货 1–9 张 |
视频完整性检查
上传 mp4、mov、m4v 时，CLI 会先检查文件结构：数据段被截断或缺少 moov 索引时返回 invalid_video（退出码 2），不会把损坏的文件传上去。
tufty upload
tufty upload ./corgi.jpg
tufty upload https://example.com/sweater.jpg --format url输出 { tool: "upload", data: { url } }。已经在 static.tufty.ai 上的地址原样返回，这种情况不需要登录。得到的地址可以直接作为工具输入，同一张图多次使用时省去重复上传。