MUSE AV

素材上传 · POST /api/upload-ref ​

参考图、垫图、蒙版、视频参考、BGM —— 全走这一个接口，拿到公网直链再传给 /api/generate 或 /api/videos。

填入你的 API Key本站所有示例里的 $MUSEAV_API_KEY 会就地换成它

只存在你自己浏览器的 localStorage 里，不会发给任何人——本站是纯静态页面，没有后端可发。 共用电脑上看完记得点「清除」。

bash
curl -X POST https://manager.museav.top/api/upload-ref \
  -H "X-API-Key: $MUSEAV_API_KEY" -F file=@垫图.jpg

可选 -F workspace_id=<工作区ID>：素材落到该工作区的子目录，跟别的工作区分开。

返回：

json
{
  "ok": true,
  "url": "https://img.webkubor.online/refs/…",
  "media_type": "image",
  "mime": "image/jpeg"
}

直接用 media_type 决定怎么渲染

用 <img> 还是 <video> / <audio>，看这个字段就行，不要再按扩展名猜一遍。

大小与格式 ​

类型格式上限
图片png / jpg / webp / gif8 MB
音频mp3 / wav / m4a / flac / ogg20 MB
视频mp4 / mov / webm50 MB

类型按字节魔数判定

不看你声明的 MIME，也不看扩展名 —— 声称是 png 的 jpeg 会被存成 jpg。

认不出的字节一律 400，不会静默收下。

限流 ​

同一归属每小时最多 120 个素材，超了 429。

国内直传（可选加速通道） ​

平台没开启时自动不生效，你不用做判断

国内客户端上传要跨境到 Cloudflare。开启之后，可以先问中台要一个预签名地址，直传国内图床。

图床密钥永远在中台、不下发；签出来的地址只能写那一个对象，几分钟内有效， 体积也焊死在签名里。

第一步：问中台要地址 ​

bash
curl -X POST https://manager.museav.top/api/upload-ref/presign \
  -H "X-API-Key: $MUSEAV_API_KEY" -H "Content-Type: application/json" \
  -d '{"ext":"mp4","size":31457280}'

size 要给准确字节数，可选 workspace_id。

返回的 strategy 有两种，两种你都必须能处理

这个接口不保证给你直传地址。

strategy: "proxy" —— 没有直传这条路

json
{ "ok": true, "strategy": "proxy", "reason": "…", "fallback": { "path": "/api/upload-ref" } }

照常走 POST /api/upload-ref 就行。reason 可能是：

reason意思
not_configured平台没开这个功能
not_cn你不在中国大陆，直传没意义
too_small文件太小，直传多两个往返反而更慢
presign_failed签名没签出来

strategy: "direct" —— 按下面两步走

json
{
  "ok": true, "strategy": "direct", "key": "…",
  "media_type": "video", "mime": "video/mp4",
  "upload": {
    "method": "PUT", "url": "…",
    "headers": { "Content-Type": "…", "Content-Length": "…" },
    "expires_in": 300
  },
  "commit": { "path": "/api/upload-ref/commit", "body": { "key": "…" } },
  "fallback": { "path": "/api/upload-ref" }
}

第二步：原样 PUT ​

bash
curl -X PUT "<upload.url>" -H "Content-Type: video/mp4" --data-binary @参考.mp4

headers 里那两个头必须一字不差地带上

它们焊在签名里，改了就是 403。

第三步：回中台登记 ​

bash
curl -X POST https://manager.museav.top/api/upload-ref/commit \
  -H "X-API-Key: $MUSEAV_API_KEY" -H "Content-Type: application/json" \
  -d '{"key":"<上一步的 key>"}'

返回与 POST /api/upload-ref 同形：

json
{ "ok": true, "url": "https://img.webkubor.online/refs/…", "media_type": "video", "mime": "video/mp4" }

所以你后续的代码不用为「刚才走了哪条路」分叉一次。

两条纪律 ​

一、PUT 失败就直接回落。 网络抖动、签名过期、你这边挡了图床域名 —— 不管什么原因，回落 POST /api/upload-ref。 直传是优化不是依赖，任何时候都有一条不经过图床的路。

二、登记时会重新验一遍。 中台会把字节头拉回来重新嗅探类型、核对真实体积。 声明 png 实际传了 mp3 会被 400 拒收，且不会写进素材库 —— 跟上面是同一条「只信字节」的纪律。

什么时候值得用 ​

大文件。

中台在国内实测（热连接）：121KB 走直传反而比直接 POST 慢（多了 presign + commit 两个往返）， 约 1MB 以上才开始划算，20MB 音频 / 50MB 视频收益最明显。

小图别绕这一圈，直接 POST。

相关 ​