文件与参考素材

素材上传一次，之后按 id 引用。字节直接进对象存储 —— 不经过 API 服务器，所以一段 50 MB 的视频不需要在中途被谁缓冲一遍。

上传

先申请一个上传目标：

curl https://api.h3.studio/v1/files \
  -H "Authorization: Bearer $H3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content_type": "image/png", "size_bytes": 204800, "filename": "first.png" }'

{
  "file_id": "718293847561029",
  "uri": "mm_file://718293847561029",
  "upload_url": "https://storage.googleapis.com/…",
  "upload_method": "PUT",
  "upload_headers": { "Content-Type": "image/png" },
  "expires_at": 1785126429
}

然后按给出的头，把字节 PUT 到 upload_url：

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/png" \
  --data-binary @first.png

签名覆盖了 content type，传成别的会失败。

引用它

{
  "type": "image_url",
  "image_url": { "url": "mm_file://718293847561029" },
  "role": "first_frame"
}

查看文件

curl "https://api.h3.studio/v1/files/retrieve?file_id=$FILE_ID" \
  -H "Authorization: Bearer $H3_API_KEY"

{
  "file_id": "718293847561029",
  "uri": "mm_file://718293847561029",
  "content_type": "image/png",
  "size_bytes": 204800,
  "uploaded": true,
  "created_at": 1785125529,
  "download_url": "https://cdn.h3.studio/…?Expires=…&Signature=…"
}

因为上传是直传存储的，这个调用才是 API 得知「上传发生了」的时刻 —— uploaded 在这里变成 true，而不是在 PUT 的时候。

支持的格式

类型	格式	单个上限	数量上限
图片	JPG、PNG、WEBP、HEIC、HEIF	30 MB	首帧 1、尾帧 1，或参考图 9
视频	MP4、MOV	50 MB	3
音频	WAV、MP3	15 MB	3

参考视频与音频每段 2–15 秒，全部素材合计不超过 12 个文件。

保留期

上传的输入 7 天后删除，生成的产物 30 天后删除。要留的请自行下载。

从浏览器直传

签名 URL 限定了单个对象、单个方法、单个 content type，15 分钟过期 —— 所以它可以安全地交给浏览器，而 API key 不行。在你的服务端签发，只把 upload_url 返回给前端，由前端直接 PUT。