媒体上传

视频生成与图生图都会用到媒体素材 —— 参考图、参考视频与音频、源图、蒙版。怎么送进来只有一条判据：

• 素材已在公网（你的 CDN / 对象存储）—— 直接填它的 http(s) URL，零上传开销。仅视频参考素材支持。
• 素材在本地 —— 先用预签名直传上传，再用返回的 upload_id 引用。这是本地文件唯一的通路，也是图生图（源图与蒙版）唯一的通路。

上传端点是 POST https://api.alltoken.ai/v1/uploads/presign（复数 uploads）。别和账户服务的 /upload/presign 搞混，后者是站内头像等用途，只收图片 MIME。

文件不经过我方网关。你先换一个一次性直传地址，把原始字节 PUT 到对象存储，再用返回的 upload_id 创建任务。网关只搬运一个几十字节的 ID。视频参考素材与图生图共用这套机制，区别只在 purpose 和引用它的字段。

第 1 步 —— 申请直传地址：

请求体：purpose（决定允许的 MIME 与体积，见下）、content_type（文件 MIME，小写）、content_length（精确字节数）、content_md5、checksum_sha256。

响应返回 upload_id（upl_ 开头）、upload_url（预签名 PUT 地址）、required_headers（第 2 步原样回填）、expires_in（URL 有效期，300 秒）、claim_expires_at（upload_id 有效期，2 小时）、max_content_length。

第 2 步 —— 把原始字节 PUT 到 upload_url，并把 required_headers 里的头原样回填。body 是原始文件字节 —— 不是 base64、不是 multipart：

第 3 步 —— 用 upload_id 创建任务。视频在 content[].upload_id 里用它；图生图用 image_upload_id / mask_upload_id 顶层字段。网关会校验字节数与 ETag、把对象转入与该任务绑定的正式区、换成上游可访问地址提交 —— 全程对你透明，你只看到 202 + task_id。

三条必须记住的规则：

• 同一项里 upload_id 与 URL 字段互斥 —— 两个都填返 400 upload_url_conflict。
• presign 与创建任务必须用同一把 API Key —— 归属按（用户 + API Key + purpose）校验，换 Key 返 404 upload_not_found。
• purpose 必须与用途对应，用错也返 404 upload_not_found。

完整的请求 / 响应字段表见 图像 API 与 视频 API 参考。

每个 purpose 固定了允许的 MIME 与单文件体积上限。

蒙版不收 image/jpeg，是因为需要 alpha 通道表达「改哪里」，而 jpeg 没有透明通道。

也就是说：拿到地址就传，但传完之后有两小时从容组装并提交生成请求。

一个 upload_id 只绑定一次任务，重复使用返 409 upload_already_used。这是防重复计费的设计 —— 一份素材、一次任务、一条账单。任务创建失败时，临时对象会被自动回收。

正常「传完就用」的节奏不会碰到这两条。大批量图生图请注意日上限：25 MiB × 约 80 张就到 2 GiB。

上传阶段（presign）：

绑定阶段（创建任务时）：