# 上传素材

## 上传本地文件

已可公开访问的 URL 可以直接放入 `inputs.uploadedUrls`。本地文件先向 i2v.ai 申请签名地址，再将文件字节直接 PUT 到存储。上传成功后，把票据返回的 `url` 用作生成素材。同一个数组可以混用两类 URL。

```bash
API=https://api.i2v.ai
TICKET=$(curl --fail-with-body -sS "$API/api/v1/uploads" \
  -H "Authorization: Bearer $I2V_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"fileName":"reference.png"}')

curl --fail-with-body -sS -X PUT "$(jq -r .uploadUrl <<< "$TICKET")" \
  -H "Content-Type: $(jq -r .contentType <<< "$TICKET")" \
  --data-binary @reference.png
```

票据包含 `uploadUrl`、`url`、`path`、`method`、`contentType`、`expiresIn`、`confirmUrl` 和 `assetTtlSeconds`。API Key 只发往 API 域名。上传字节时使用票据中的 Content-Type，PUT 请求由存储签名授权。 持有返回链接的人可以访问素材。

API 会从常见图片、视频和音频扩展名推断类型。文件缺少扩展名或扩展名不准确时，可显式传入 `contentType`。也可以用 `fileSize` 声明并绑定确切字节数。

## 查询上传信息

```bash
curl --fail-with-body -sS "$API$(jq -r .confirmUrl <<< "$TICKET")" \
  -H "Authorization: Bearer $I2V_API_KEY"
```

`GET /api/v1/uploads?path=…` 返回路径、URL、大小、MIME、上传时间和到期时间。可读取容器头时，`media` 还会提供素材类型、显示宽高、旋转角度及毫秒时长。无法读取时，`media` 为 `null`。确认是可选步骤。PUT 成功后就可以将 `url` 传入 [createTask](/docs/api) 的 `inputs.uploadedUrls`。

视频模型会按 `uploadedUrls` 中可识别的扩展名分配图片、视频和音频槽位。视频或音频 URL 没有扩展名时，用模型对应的 `referenceVideoUrls` 或 `referenceAudioUrls` 字段。

## 有效期与限制

- 签名地址有效期为 15 分钟。PUT 完成后 24 小时内可用于新任务。到期后系统自动清理，已引用素材的在途任务可继续使用至结束。
- 图片上限为 10 MiB，视频为 50 MiB，音频为 15 MiB。省略文件大小时，系统在确认或提交任务时核对存储中的实际大小。各模型的素材限制仍适用。
- 路径不合法、类型不支持或大小不符时返回 HTTP 400。文件属于其他账户时返回 HTTP 403，尚未上传或已经过期时返回 HTTP 404。
- 需要在签名时绑定文件大小并显式完成上传时，可使用[媒体接入指南](/docs/media-workflow)中的流程。