视频参考素材与本地文件上传

先分清三种输入语义：普通参考图用于主体或风格参考，首帧指定起始画面，首尾帧约束开始与结束。相同图片 URL 放到不同字段，含义可能不同。

各型号支持什么

型号	单首帧	首尾帧对	普通参考图片	视频参考	音频参考	直接 multipart 图片文件
Seedance Mini/Fast	不单独接受	支持，必须成对	最多 9 张	最多 3 段	最多 3 段	不支持；先上传取得 URL
SD-2.0-MZ1	不支持关键帧模式	不支持	最多 9 张	不支持	最多 3 段，必须有图片	不支持；先上传取得 URL
MiniMax-H3	支持	支持	最多 9 张	最多 3 段	最多 3 段	不支持；先上传取得 URL
两个 Grok -6s 型号	input_reference	不支持独立首尾帧对	reference_images 最多 7 张	不支持	不支持	支持
grok-video-1.5	参考图方式生成	无统一关键帧对承诺	image_urls 最多 7 张	不在本页支持范围	不在本页支持范围	支持图片输入

Seedance Mini/Fast 和 H3 的图片/视频/音频总数最多 12 个，不能把三个单类上限相加成 15 个。关键帧模式不能与普通参考素材混用。

选择素材地址

输入 URL 必须真实指向媒体文件，并在整个任务处理期间可读取。

使用 HTTPS；不要使用电脑路径、localhost、局域网 IP、blob: 或浏览器会话 URL。
不能依赖登录 Cookie、自定义 Authorization 或只能自己浏览器打开的网盘页面。
不要在素材链接中放本站 API Key。临时签名链接应留足生成时间。
图片下载 URL 应返回图片字节，而不是 HTML 预览页、验证码或 JSON。
文件扩展名、MIME 和实际编码应一致；只改后缀不能转换格式。

公开媒体链接意味着持有链接的人可能访问素材。上传前确认素材适合用于该任务；链接不要进入公开日志或无关的聊天记录。

本站提供的三种上传入口

用途	请求	请求体
参考图片	POST /v1/video-reference-images	JSON，image 为完整图片 Data URL
参考视频	POST /v1/video-reference-media/{model}/video	文件原始二进制，不是 multipart
参考音频	POST /v1/video-reference-media/{model}/audio	文件原始二进制，不是 multipart

视频与音频入口会使用本站 Key 检查当前模型权限。model 只填写当前可用的完整 ID；SD-2.0-MZ1 只开放 audio，Grok 不通过这两个入口上传视频/音频参考。

上传只获得可引用的素材 URL，不会自动创建生成任务。拿到 URL 后再放入所选模型的请求中；上传成功也不代表全部后续生成参数合法。

上传一张图片

下载 mxb-upload.py，在本机准备真实 reference.png：

bash

python mxb-upload.py --kind image --file reference.png

脚本从服务端环境变量读取 MXB_API_KEY，将图片转为 Data URL，执行：

text

POST https://openpix.cc/v1/video-reference-images
Content-Type: application/json
Authorization: Bearer <本站 API Key>

{"image":"完整的 data:image/png;base64,..."}

以上是协议示意，不要把省略号直接提交。脚本会完成真实文件编码。成功响应结构为 {"url":"本站生成的图片地址"}；将该 url 放入 images、image_urls 或 metadata.content 中的正确字段。

推荐 PNG、JPEG、WebP。上传工具为示例主动设置图片大小上限 20 MiB，便于控制 Base64 体积；这不表示所有型号的最终图片输入能力完全相同。

上传参考视频

Mini/Fast 示例：

bash

curl --fail-with-body --max-time 120 \
  https://openpix.cc/v1/video-reference-media/dreamina-seedance-2-0-mini-260615/video \
  -H "Authorization: Bearer $MXB_API_KEY" \
  -H 'Content-Type: video/mp4' \
  --data-binary @reference.mp4

也可运行：

bash

python mxb-upload.py --kind video \
  --model dreamina-seedance-2-0-mini-260615 --file reference.mp4

不要使用 -F file=@...。此接口直接读取文件字节；发送 multipart 包装会导致 MIME 或媒体解析失败。

Mini/Fast 视频上传限制

项目	当前上传校验
文件大小	每段不超过 200 MB，按十进制字节计算
时长	3–10 秒
容器 / 视频编码	MP4 或 MOV，H.264 或 H.265
视频流	一条实际视频流；封面附图不算视频流
内嵌音轨	如有，AAC 或 MP3
帧率	24–60 FPS
每个边长	300–6000 像素
宽高比	0.4–2.5
总像素	407,696–8,295,044

这些条件要同时满足。例如 512×512 虽然边长满足，像素总数仍不足。720×1280 满足像素和比例条件；还需满足时长、格式与大小。

H3 视频上传限制

每段不超过 50 MB，至少 2 秒，MP4/MOV、H.264/H.265，一条视频流，已有音轨为 AAC/MP3。H3 上传规则不沿用 Mini/Fast 的 3–10 秒和像素范围。

上传返回的 effective_duration 对 H3 最多记录 15 秒；它是素材参考时长信息，不是本次生成输出时长，也不能替代 seconds。不要据此承诺任意长素材的全部内容都会影响生成。

上传音频

bash

curl --fail-with-body --max-time 120 \
  https://openpix.cc/v1/video-reference-media/SD-2.0-MZ1/audio \
  -H "Authorization: Bearer $MXB_API_KEY" \
  -H 'Content-Type: audio/wav' \
  --data-binary @reference.wav

型号	文件大小	时长	格式与 MIME
Mini/Fast	最多 15 MB	2–30 秒	MP3：audio/mpeg；PCM WAV：audio/wav 或 audio/x-wav
SD-2.0-MZ1	最多 15 MB	2–30 秒	同上；生成请求必须同时有图片参考
MiniMax-H3	最多 15 MB	至少 2 秒	MP3、PCM WAV，另接受 AAC / M4A

H3 的 M4A 使用 audio/mp4 或 audio/x-m4a，AAC 使用 audio/aac。上传独立音频文件，不要把含视频画面的 MP4 当作音频上传。WAV 需要 PCM 编码，扩展名为 .wav 不足以证明符合要求。

上传响应与有效期

视频/音频上传成功 HTTP 200 的结构示意：

json

{
  "url": "https://openpix.cc/reference-media/example.mp4",
  "size": 1200000,
  "ext": "mp4",
  "duration": 5,
  "effective_duration": 5,
  "width": 1280,
  "height": 720,
  "expires_at": 1793376000
}

URL 和时间为示意，不可直接下载。size 是字节数；duration 是素材容器时长；width/height 只在视频响应中出现。当前视频/音频素材保留窗口为约 48 小时，以返回 expires_at 为准；图片上传不返回相同的 expires_at 字段，不要给它强行套用音视频保留期。

应上传后及时提交生成任务，长期工作流使用自己的可靠素材存储。保留期不是生成等待时间承诺。

上传错误处理

状态	含义 / 操作
400	模型/素材类型不支持、空文件等，修正后再传
401 / 403	Key 或目标模型权限不可用
413	文件或整个请求过大
415	Content-Type 不符合当前素材类型
422	真实媒体编码、时长、像素或流结构不符合要求
429	上传繁忙或过于频繁，退避后再试
503	暂时无法验证权限，稍后重试
507	临时素材存储容量不足，稍后重试

上传失败时不要继续发送缺少素材的生成请求，也不要静默降级为纯文生视频。上传可以重试，但应避免无意义重复存储；生成 POST 必须单独遵守“提交一次、结果未知先核查”的规则。