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

任务 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 校验后进行计费提交。

```json
{
  "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 模式选择](/zh/docs/media/minimax-h3-selection)与[图片规格](/zh/docs/media/image-specifications)。

## 排查时避免重复提交

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

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

## 有意识地复用已检查素材

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

平台字段按 2026-11-03 仓库 schema 及 [H3](/zh/docs/models/minimax-h3)、[Nano Banana 2](/zh/docs/models/nano-banana2)、[GPT Image 2.5 Flare](/zh/docs/models/gpt-image-2.5-flare/edits)指南核对。[MiniMax 原生 API](https://platform.minimaxi.com/docs/api-reference/video-generation-v2-create)用于理解概念，不代表原生上传机制和限制自动成为平台功能。本篇不承诺通用文件大小或 URL 有效期。