接入指南

媒体 API 参考素材最佳实践：图片与 MiniMax H3 输入预检

生成图片或 MiniMax H3 视频前，检查参考 URL、实际文件、有效期和输入模式，区分素材失败与创意拒收，避免重复提交任务。

任务 JSON 合法不代表参考素材可读取、可解码或可被模型使用。提交 Nano Banana、GPT Image 或 MiniMax H3 请求前，应分别检查素材与它在请求中的用途。本篇补充提交和轮询流程，不新增上传端点，也不改变平台限制。

把四类检查分开

层级	要回答的问题	通过后仍不能证明什么
授权	素材是否允许用于本任务？	URL 能读取
传输	URL 是否提供预期文件字节？	媒体能解码
文件	图片、视频或音频能否按预期类型打开？	模型接受该尺寸或时长
契约	输入模式与字段组合符合当前 schema 吗？	生成结果会符合创意要求

在本地媒体查看器中打开获授权素材，检查实际格式、尺寸，以及需要时的时长和音轨。不要只凭 URL 后缀判断类型。地址以 .png 结尾但返回 HTML 登录页，仍然不是图片。

为准确素材版本保留记录

记录应用素材 ID、版本或校验值、用途、实测文件属性和 URL 过期时间。签名 URL 与凭证不要进入公开日志。这是应用元数据，不是可随意追加到 input 的字段。

浏览器访问可能依赖 cookie 或本地网络，应确认生成服务能通过支持的输入方式获取素材。浏览器预览成功并不足够。签名 URL 应覆盖必要处理窗口，包括可能的排队时间；不存在通用安全有效期，应按路由说明与应用需要设置余量。

不要把平台 API Key 转发给素材域名。素材地址被网络策略拒绝时，选择受支持且获授权的托管方式，不绕过策略。私有内容使用受控存储，只开放处理所需的有限访问。

整体验证 H3 模式

下面是 768P 的 H3 首尾帧示例。替换两条占位地址，确保素材获授权且可读取，再用完整实时 schema 校验后进行计费提交。

{
  "model": "minimax-h3",
  "input": {
    "prompt": "一个连续镜头，从开场桌面视角缓慢移动到结束特写。保留相同台灯形状和奶油色材质，没有额外物件或切镜。",
    "frames_images": [
      "https://assets.example.com/lamp-start.png",
      "https://assets.example.com/lamp-end.png"
    ],
    "seconds": 5,
    "resolution": "768P",
    "aspect_ratio": "16:9"
  }
}

frames_images 的顺序有意义：先首帧，再尾帧。不要在此模式下追加 H3 的 images、videos、audios。普通参考素材使用另一种受支持模式，并核对组合规则。Nano Banana 和 GPT Image 的参考图字段是 images，不能复制 H3 字段名。参见 H3 模式选择与图片规格。

排查时避免重复提交

拿到任务 ID 后，保留并检查原任务。后续素材错误不同于“提交根本没有到达服务器”。记录任务 ID、素材版本、有效期和脱敏错误；先查素材可读取性与格式，再决定新尝试。不假设报错等于未收费，应核对真实任务记录。

如果生成完成但主体不对，应检查参考版本、模式和提示词。这是创意或输入选择问题，不能据此认定传输失败。修改需求再生成属于新的预算内尝试。

有意识地复用已检查素材

批量任务应固定获批素材版本，不在同一 URL 后悄悄替换文件。后续提交前重新检查有效期。将合格输出关联到原始素材版本和预算记录，才能区分回归与主动创意变更。

平台字段按 2026-11-03 仓库 schema 及 H3、Nano Banana 2、GPT Image 2.5 Flare指南核对。MiniMax 原生 API用于理解概念，不代表原生上传机制和限制自动成为平台功能。本篇不承诺通用文件大小或 URL 有效期。