参考素材

上传素材

推荐使用临时上传接口。使用本站 API Key，以 multipart/form-data 上传图片、视频或音频，单文件不超过 512 MiB：

curl https://api.hamubox.com/v1/media/files \
  -H "Authorization: Bearer $HAMUBOX_API_KEY" \
  -F "[email protected]"

响应示例：

{
  "id": 123,
  "file_id": 123,
  "object": "file",
  "url": "https://img.hamubox.com/file/task-assets/temporary/reference/video/example.mp4",
  "media_type": "video",
  "status": "uploaded",
  "expires_at": 1790058088
}

返回的 url 可放入 image_urls、reference_video_urls、reference_audio_urls、图片接口的 images 或首尾帧字段。file_id 是本站文件记录 ID，不能当成供应商 asset:// ID。上传不会提交生成任务，也不等于向供应商素材库登记。

临时文件从上传完成起保留 24 小时，expires_at 为 Unix 秒时间戳。到期后不能用于新任务，请重新上传；已经接受的任务会继续受保护，直到所有引用该文件的任务进入成功或失败终态。默认情况下，任务使用过的临时素材会在终态后转为长期参考文件，任务详情也会改为展示转存后的地址；清理等待转存完成。没有用于任务的临时上传到期后直接清理。清理是后台异步操作，不保证链接在到期那一秒立刻失效。

临时上传本身不进入用户资产库；用于任务并转存成功后，展示长期参考文件。需要上传后立即长期保存时，可增加 -F "temporary=false"。原有 /v1/video/material-files/upload 保持默认长期保存行为，也接受 -F "temporary=true" 使用相同的临时规则。浏览器直传文件服务后登记的临时素材和 BYOK 临时素材也遵循相同规则。

任务详情与资产库

通过 API 上传或转存的文件属于当前 Key 对应的本站用户。任务详情与资产库按输入来源区分：

输入方式	任务详情中的素材地址	用户资产库
外部 HTTPS URL	保留调用方提供的原始 URL	转存成功后展示本站文件，原始外链不单独入库
Base64 / Data URL	展示转存文件地址，不展示原始编码	展示同一份转存文件
临时上传 URL	转存前为临时地址，转存成功后为长期文件地址	只展示转存后的长期文件
`temporary=false` 长期上传	展示上传后的文件地址	按普通参考素材展示

后台转存是异步操作，失败会重试。请保证外部 URL 在排队和生成期间持续可用；外链失效后，任务详情仍保留原地址，已保存的文件可在资产库查看。部分 BYOK 接口另有保存设置：关闭“保存参考素材”时，不新增用户参考资产，任务仍使用原始外链或临时链接。

从资产库删除素材只影响本站保存的文件，不会删除或更改调用方自己的外部文件。被删除的本站地址在用户任务详情中也不再展示；调用方提供的原始外链不受影响。

音视频上传后，后台会预先检测并缓存时长；正式提交仍会按所选模型检查限制。512 MiB 是此上传接口上限，不代表所有模型都接受该大小的素材。

内嵌图片

受支持的图片输入字段可以接收带 MIME 类型的 Data URL，例如 data:image/png;base64,...。网关会先将内嵌素材转为文件地址，再进行正常任务处理；图片示例：

{
  "model": "nano-banana-pro",
  "prompt": "保持人物，改成雪景背景",
  "images": ["data:image/png;base64,<替换为完整图片编码>"],
  "resolution": "1k",
  "output_format": "png",
  "n": 1
}

这是格式示意，尖括号占位内容不是有效编码。大图片、视频和音频优先使用 URL：Base64 增大请求体，也会增加提交耗时，仍受网关请求大小和模型素材上限约束。不要记录包含完整 Base64 或 Key 的请求日志。

字段与用途

用途	视频接口字段	图片接口字段
参考图片	`image_urls`	`images`
首帧	`first_frame_url`	不适用
尾帧	`last_frame_url`	不适用
参考视频	`reference_video_urls`	不适用
参考音频	`reference_audio_urls`	不适用

同类数组中的顺序就是素材编号顺序。提示词中引用「图片 1」「视频 1」时，应与对应数组一致。

首尾帧模式明确传 mode: "first_last_frame"。只传一张普通 image_urls 不足以表达它到底是首帧、尾帧还是全能参考。

时长信息

Seedance 2.0 / 2.5、Venice 视频接口以及支持音视频参考的媒体线路，会在校验和预扣前检测文件的实际时长。调用方可以省略总时长字段；旧客户端继续传入也可兼容，例如：

{
  "metadata": {
    "reference_video_seconds": 8.4,
    "reference_audio_seconds": 6.0
  }
}

这些值表示对应类型全部文件的总和，不是单段时长，也不是输出时长。服务端会用检测值覆盖调用方填写的值。视频与音频分别计算上限。

Wan 3 EP 的参考视频时长由服务端检测，用于检查参考加输出总长度和计算费用；客户端不能通过少填时长减少账单。

首次使用外部素材时，检测需要下载文件，会增加提交耗时。本站文件会复用检测缓存；外部 URL 只有版本信息仍一致时才复用，避免同一 URL 换了文件后继续使用旧时长。无法读取文件或检测时长时，会在调用上游和扣费前返回错误，不会把客户端填写的时长当成真实值。asset:// 素材须在本站登记过且能找到可访问的原文件。

素材质量检查

上传前检查格式、单边像素、比例、文件大小、时长和视频帧率。PNG 不等于透明图片，支持 PNG 的模型不一定支持透明通道；需要时将透明背景合成到不透明底色。

具体上限分别见 Seedance 与 Wan 3，两者不能混用。

素材可下载不等于必定通过供应商检查；内容、尺寸或编解码不被接受时，仍可能在任务执行阶段失败。