MiniMax H3 API 参考素材提交失败？先查URL再预检音视频

调用 MiniMax H3 API 时，纯文本请求可以正常执行，加入图片、视频或音频后却失败，问题不一定出在提示词。

素材地址可能返回登录页面，临时链接可能已经失效，视频也可能只是扩展名为 MP4，内部编码却不符合要求。还有一种情况是文件本身没有问题，但请求混用了不同生成模式的素材角色。

这些问题发生在不同环节，反复提交同一份请求通常不能解决。更有效的方法是：在创建生成任务之前，先检查素材能否被读取，再检查真实媒体属性，最后检查输入组合。

本文不重复介绍任务轮询、结果下载和模型部署，而是围绕 “提交前的素材预检” 建立一套排查流程。

一、先确认：是素材问题，还是请求本身没有跑通？

开始检查素材前，应准备一个能够成功执行的最小请求。

这个请求只保留必要的提示词、模型名称和输出参数，不附加图片、视频或音频。确认它正常后，再逐步增加参考素材。

建议按以下顺序测试：
纯文本请求。
文本加一张符合要求的图片。
文本加一段参考视频。

确认单素材正常后，再测试多素材组合。每次只增加一种条件。如果纯文本请求也失败，应先核对鉴权、模型权限、余额和请求结构，不必立即转向文件格式排查。

官方创建任务文档要求请求包含非空的文本项，同时区分首尾帧图生视频和参考生成模式。两类模式中的素材角色不能混用。因此，“素材文件正确” 与 “请求组合正确” 需要分别验证。

这里可以建立三个检查关口：

表格

三个关口全部通过，才值得继续排查生成阶段的问题。

二、浏览器能打开，不代表模型服务能读取

浏览器访问素材时，可能自动携带登录 Cookie、缓存和其他请求信息。模型服务读取素材 URL 时，不一定具备这些条件。

因此，“我在浏览器里能看到图片” 只能证明当前浏览器能够访问，不能证明上游服务也能取得同一个文件。

排查时，至少检查以下情况。

第一，链接是否直接指向素材。
网盘分享页、相册预览页和后台管理页，可能展示了图片，但返回的实际内容是 HTML。接口需要的是对应输入方式支持的素材地址，而不是供人浏览的页面。

第二，链接是否依赖登录。
如果退出账号后打不开，或者必须携带 Cookie 才能读取，就需要重新确认素材传递方式。不要把浏览器登录信息直接复制到模型请求中。

第三，地址是否发生跳转。
重定向本身不一定有问题，但最终地址可能进入鉴权页面，也可能换到另一个存在访问限制的域名。应检查跳转后的响应，而不只看最初链接。

第四，临时链接是否仍然有效。
带签名的对象存储 URL 通常存在有效期。链接在上传时可以访问，不代表任务实际读取时仍然有效。应结合排队和重试流程，为素材获取留出合理时间。

使用 星链 API 这类 API 中转站接入时，还应确认素材是由中转服务读取、原样传给上游，还是通过其他方式上传。不同路径对应的访问条件可能不同，不能只验证业务服务器这一端。

三、HTTP 200 为什么不能作为预检通过的依据？

HTTP 状态码描述的是请求处理结果，不直接证明返回内容是有效素材。

一个地址返回 200，响应体仍可能是登录页、错误提示页，或者对象存储返回的业务提示。即使 Content-Type 标成了媒体类型，也需要继续检查真实内容。

建议同时观察：
HTTP 状态码。
是否发生重定向。
响应声明的 Content-Type。
是否返回明显的 HTML 内容。
文件是否能够被对应的媒体工具识别。

也不要反过来只凭 Content-Type: application/octet-stream 就判定文件无效。部分存储服务可能使用通用二进制类型，仍需进一步探测文件内容。

实际排查可以使用一个有限读取脚本。它通过 GET 请求读取文件前部，避免为了检查链接就完整下载大视频。

下面的代码只检查 URL 响应特征，不会判断素材已经符合 H3 要求，也不会创建收费生成任务。

import json
import os
import urllib.error
import urllib.parse
import urllib.request

def check_asset(url):
    parsed = urllib.parse.urlsplit(url)
    if parsed.scheme not in ("http", "https") or not parsed.hostname:
        raise ValueError("请提供有效的 HTTP(S) 素材地址")

    request = urllib.request.Request(
        url,
        headers={
            "Range": "bytes=0-4095",
            "Accept-Encoding": "identity",
        },
        method="GET",
    )

    try:
        with urllib.request.urlopen(request, timeout=15) as response:
            prefix = response.read(4096)
            media_type = response.headers.get_content_type()
            text = prefix.lstrip().lower()

            looks_html = (
                media_type == "text/html"
                or text.startswith((b"<!doctype html", b"<html"))
            )

            return {
                "status": response.status,
                "redirected": response.url != url,
                "content_type": media_type,
                "content_length_header":
                    response.headers.get("Content-Length"),
                "content_range":
                    response.headers.get("Content-Range"),
                "sample_bytes": len(prefix),
                "result": (
                    "suspected_html"
                    if looks_html
                    else "needs_media_probe"
                ),
            }

    except urllib.error.HTTPError as exc:
        return {"result": "http_error", "status": exc.code}

    except (urllib.error.URLError, OSError, ValueError) as exc:
        return {
            "result": "request_failed",
            "error_type": type(exc).__name__,
        }

print(json.dumps(
    check_asset(os.environ["ASSET_URL"]),
    ensure_ascii=False,
    indent=2,
))

运行前，将自己的素材地址写入 ASSET_URL 环境变量。只检查自己管理或确认可信的链接。

这里的 4096 字节与 15 秒是示例设置，不是 MiniMax 规定。服务器也可能忽略 Range；代码仍只向应用读取前 4096 字节，然后关闭响应。

如果返回 206，Content-Length 可能只是本次分段长度，不能直接当成完整文件大小；应结合 Content-Range 判断。若服务没有提供可靠的总大小信息，就把文件大小标记为 “待确认”。

脚本不输出完整 URL，避免把签名参数写入普通日志。其语法已检查，但没有使用你的私有素材进行联网实测。

此外，业务服务器能读到素材，仍不能保证模型上游一定能读到。地域限制、防盗链和访问策略，还需要结合存储访问日志进一步确认。

四、不要只看 MP4 扩展名，要检查内部编码

素材可访问后，下一步是检查文件内容。

MP4 和 MOV 是容器格式。容器内部还包含视频流、音频流和相关元数据。两个扩展名相同的视频，内部编码、帧率和音轨可能完全不同。

官方托管 API 文档列出的参考视频条件包括：MP4 或 MOV 容器，视频编码为 H.264/AVC 或 H.265/HEVC，视频内音频编码为 AAC 或 MP3；帧率范围为 23.976 至 60。不能因为文件名以 .mp4 结尾，就认定这些条件全部满足。

可以先将素材保存到本地，再运行：

ffprobe -v error -show_entries format=format_name,duration,size:stream=index,codec_type,codec_name,width,height,avg_frame_rate,sample_rate,channels,duration -of json "reference.mp4"

这条命令用于读取媒体信息，不会修改原文件。

重点查看：
format_name：探测到的容器格式。
codec_type：当前流是视频、音频还是其他类型。
codec_name：实际编码。
width、height：视频流尺寸。
avg_frame_rate：平均帧率。
duration：文件或流的时长。
sample_rate、channels：音频采样率和声道数。

ffprobe 官方文档明确支持探测容器和媒体流信息，并提供机器可读输出，适合接入预检流程。

工具输出需要正确解释。例如，30000/1001 是分数形式的帧率，约为 29.97，不能当作普通字符串比较。若时长或其他字段缺失，也不能直接填零，应标记为待确认。

还有一个边界：能够读取元数据，不等于整个文件都没有损坏。发现解码异常时，还需要进一步验证文件完整性，而不是仅凭探测成功放行。

五、把输入限制转换成可执行检查

MiniMax 官方开发指南对不同素材分别设置了限制：

表格

混合输入最多 12 个媒体文件。图片及参考视频的宽、高范围为 256—5760 像素，宽高比为 0.4—2.5；请求体大小上限为 64MB。以上是核查时官方指南列出的条件，接入时仍应确认具体模型和接口版本。

这些限制要分别计算，不能只看单文件。

例如，两个参考视频分别为 8 秒和 9 秒。每段都没有超过 15 秒，但合计 17 秒，超过了参考视频总时长限制。预检应指出 “总时长超限”，而不是笼统返回 “素材格式错误”。

文件大小与请求体大小也不是一回事。使用 URL 时，请求体主要携带地址和参数；使用 Base64 时，媒体数据会进入请求体，编码后体积也会增加。不能只比较原始文件大小，而忽略最终序列化后的请求体。

图片尺寸同样要分项检查。一个画面即使宽高比合规，某条边仍可能超出像素范围。缩小文件体积，也不一定改变图片尺寸或视频编码。

预检报告应明确是哪条规则没有满足，并给出对应处理动作，避免建议用户无差别压缩或转码所有素材。

六、文件符合规格，输入模式仍可能写错

素材预检不能停在文件层面，还要读取完整请求结构。

首尾帧图片用于约束视频的开始或结束；参考图片、视频和音频则属于另一类生成输入。它们不是可以随意交换的标签。

建议在业务侧明确生成模式，再构造对应参数：
首帧生成：检查首帧素材。
首尾帧生成：分别检查首帧和尾帧。
参考生成：检查参考素材的角色、数量及组合。

不要先把所有文件塞进数组，再让接口自行猜测用途。

这里适合对不同模式建立独立校验函数。这样，错误可以在提交前被定位为 “角色组合冲突”，而不是等到生成接口拒绝后，再从通用错误中反推原因。

如果接入层会转换参数，还应核对转换后的结构。聊天接口兼容，并不自动意味着视频素材角色也会按相同方式处理。

七、用预检报告代替一句 “上传失败”

预检的最终产物，应是一份可以复现和处理的报告。

下面是结构示例，不是实际调用结果，也不代表真实素材测试数据：

表格

每个结论最好保留四类信息：发现值、规则来源、判定和修复动作。

其中 “通过” 必须限定范围。URL 检查通过，只表示当前检查环境能够读取；编码检查通过，只表示编码这一项符合要求。不要把局部通过汇总成 “模型一定能生成”。

在多人协作中，可以用内部素材编号关联原始文件、预检结果和生成请求。提交给 星链 API 或其他接入服务协查时，提供脱敏后的检查结果与请求标识即可，不必在群聊中发送密钥或完整签名链接。

八、修复后做单变量复测，不要立即恢复全部素材

完成修复后，建议重新走一遍最小验证流程。

先用一张确认符合条件的图片测试；成功后再增加其他素材。测试视频时，先验证单段，再验证组合。这样可以判断问题来自某个文件，还是来自组合后的数量、时长与角色。

每次复测记录：
模型和端点。
请求模式。
素材编号及属性。
本次只修改了什么。
返回状态与错误信息。
是否取得任务标识。

获得任务标识后，应进入原有的任务管理流程，不要因为没有立即看到成品就再次创建相同任务。素材预检与任务状态管理应该衔接，但没有必要在这一篇教程里重新展开整套轮询与下载代码。

同时，预检通过不能保证内容审核通过，也不能保证画面效果符合业务要求。它解决的是可访问性、媒体规格和请求组合问题，不能替代服务端审核与生成质量验收。

MiniMax H3 参考素材排查的关键，是把 “提交失败” 拆成可以观察的原因：先确认取得了正确文件，再确认文件属性合规，最后确认参数表达了正确的生成模式。把这三步前移到任务创建之前，才能让失败信息具有明确的处理方向。