MiniMax 视频生成 API​

POST https://api.yu-yu.ai/v1/video/generations

本接口用于创建 MiniMax 视频生成任务（v2 协议）：以顶层 prompt 给出文本提示词，并通过 metadata.content 数组传入图片、视频、音频等多模态信息，支持文生视频、图生视频（首帧 / 尾帧 / 首尾帧）与参考生视频。接口为异步接口，提交成功后返回 task_id，再通过查询任务接口轮询状态并获取生成的视频。

模型能力​

本接口对外暴露 MiniMax-H3 家族的三个档位。三者的调用方式与参数完全一致（同一端点、同一套请求体字段与校验规则），差异只在 model 取值以及各档位支持的 resolution、duration 取值。

• MiniMax-H3（质量档）：通用多模态视频模型，支持文生视频、图生视频（首帧 / 尾帧 / 首尾帧）与参考生视频（参考图 / 参考视频 / 参考音频）。输出分辨率 768P / 2K，时长 4–15 秒。适合对画面质量要求较高的成片场景。
• MiniMax-H3-Max（高速档）：在 MiniMax-H3 上后训练并优化生成速度的档位，支持文生视频、图生视频（首帧 / 尾帧）与参考生视频。输出分辨率 480P / 768P（缺省 768P，不支持 2K），时长 5–15 秒（4 秒不支持）。
• MiniMax-H3-Fast（速度档）：速度档位，调用方式与参数与上述两个档位一致，但可用分辨率更窄——本网关上该档位只接受 480P；该档位专属的补充字段由网关自动补齐，调用方无需传入。

鉴权​

本接口仅支持 API Key 鉴权，请在 https://api.yu-yu.ai/console 获取 API Key。

请求时在 Header 中携带：

Authorization: Bearer <API_KEY>

提交任务​

POST https://api.yu-yu.ai/v1/video/generations

Body 参数​

model string 必选

需要调用的模型 ID，取值：MiniMax-H3、MiniMax-H3-Max、MiniMax-H3-Fast。三个档位的调用方式与参数完全一致，仅档位能力不同，详见上文的模型能力。

prompt string 条件必填

输入给模型的文本提示词，描述期望生成的视频，内容不能为空。与 metadata.content 数组中的非空 text 项至少提供一个。

duration integer 可选

生成视频的时长，单位：秒，仅支持整数，写在顶层。可用取值随档位不同：

• MiniMax-H3：4–15 秒。
• MiniMax-H3-Max：5–15 秒（4 秒不支持）。

size string 可选

生成视频的分辨率，与 metadata.resolution 等价，两者同时给出时以 metadata.resolution 为准。可用取值随档位不同：

• MiniMax-H3：768P、2K。
• MiniMax-H3-Max：480P、768P，缺省 768P；不支持 2K。
• MiniMax-H3-Fast：只接受 480P。

metadata object 可选

H3 的原生参数统一收在 metadata 下，未列出的顶层字段不会生效：

• metadata.content object[]：官方 v2 的 content 数组，元素结构见下文。
• metadata.resolution string：生成视频的分辨率，取值同 size；优先级高于顶层 size，缺省 768P。
• metadata.ratio string：生成视频的宽高比，说明见下文。
• metadata.callback_url string：任务状态变化的回调地址，说明见下文。
• metadata.first_frame_image / metadata.last_frame_image string：首帧 / 尾帧图片地址（不使用 metadata.content 时的简写形式）。
• metadata.reference_image（或 reference_images）/ metadata.reference_video（或 reference_videos）/ metadata.reference_audio（或 reference_audios）：参考图 / 参考视频 / 参考音频地址，可传字符串或字符串数组。

metadata.content 数组元素​

metadata.content 是多模态信息数组，每个元素由 type 区分内容类型（text / image_url / video_url / audio_url），并可用 role 标注用途。数组中必须包含一个非空的 text 项（否则需由顶层 prompt 补上）。

支持的输入组合（对应不同的生成场景）：

• 文生视频：仅一个 text 元素。
• 图生视频-首帧：text + 1 个 image_url（role=first_frame，或不传 role）。
• 图生视频-尾帧：text + 1 个 image_url（role=last_frame）。
• 图生视频-首尾帧：text + 2 个 image_url，role 分别为 first_frame 与 last_frame。
• 参考生视频：text + 参考图（role=reference_image）、参考视频（role=reference_video）、参考音频（role=reference_audio）的任意组合。

metadata.content 文本元素 object​

• metadata.content[].type string 必选：输入内容的类型，此处应为 text。
• metadata.content[].text string 必选：输入给模型的文本提示词，描述期望生成的视频。按字符计长度，单个 text 最多 7000 字符。

metadata.content 图片元素 object​

• metadata.content[].type string 必选：输入内容的类型，此处应为 image_url。
• metadata.content[].image_url object 必选：输入给模型的图片对象。
  • metadata.content[].image_url.url string 必选：图片位置。支持公网 URL、mm_file://{file_id}（引用平台已有文件，例如已上传文件或上一次产物的 file_id）、data:image/<图片格式>;base64,<Base64编码>（<图片格式> 需小写）。
• metadata.content[].role string 条件必填：图片的位置或用途。

role 取值

• first_frame：首帧图片（图生视频）。只有一张图片且未指定 role 时，默认按 first_frame 处理。
• last_frame：尾帧图片（首尾帧图生视频，需与 first_frame 配对）。
• reference_image：参考图（参考生视频）。

metadata.content 视频元素 object​

仅参考生视频场景使用。

• metadata.content[].type string 必选：输入内容的类型，此处应为 video_url。
• metadata.content[].video_url object 必选：参考视频对象。
  • metadata.content[].video_url.url string 必选：视频位置。支持公网 URL、mm_file://{file_id}、data:video/mp4;base64,<Base64编码>。
• metadata.content[].role string 必选：此处应为 reference_video。

metadata.content 音频元素 object​

仅参考生视频场景使用。

• metadata.content[].type string 必选：输入内容的类型，此处应为 audio_url。
• metadata.content[].audio_url object 必选：参考音频对象。
  • metadata.content[].audio_url.url string 必选：音频位置。支持公网 URL、mm_file://{file_id}、data:audio/<音频格式>;base64,<Base64编码>（<音频格式> 需小写）。
• metadata.content[].role string 必选：此处应为 reference_audio。

metadata.ratio​

生成视频的宽高比。缺省 adaptive（根据输入自动选择最合适的比例，实际比例可从查询接口返回的 ratio 字段读取）。

取值：adaptive、21:9、16:9、4:3、1:1、3:4、9:16。

不同生成场景的要求不同：

• 文生视频（metadata.content 只含 text）：ratio 必填，且不能为 adaptive，可取 21:9、16:9、4:3、1:1、3:4、9:16。
• 图生视频（metadata.content 含 first_frame / last_frame 图片）：宽高比由输入图片决定，ratio 恒为 adaptive；传入其它合法值不会报错，但会被忽略并按 adaptive 处理。
• 参考生视频（metadata.content 含 reference_image / reference_video / reference_audio）：ratio 可选，缺省 adaptive，也可显式指定上述任一具体比例。

metadata.callback_url​

任务状态变化的回调地址。配置后，服务端会先向该地址发送一个带有 challenge 字段的验证请求（需在 3 秒内原样返回 challenge 完成校验）；校验通过后，每次任务状态变化都会向该地址 POST 一条更新，推送体结构与查询任务接口的响应一致。

回调的 status 取值为 queued、running、succeeded、failed、cancelled。

查询任务​

GET https://api.yu-yu.ai/v1/video/generations/{task_id}

查询单个视频生成任务的状态与结果。

Path 参数​

task_id string 必选

提交任务时返回的任务 ID。

响应参数​

task object

任务对象。

• task.id string：任务 ID，与提交接口返回的 task_id 对应。
• task.model string：任务使用的模型名，例如 MiniMax-H3。
• task.status string：任务状态，取值见任务状态说明。
• task.error object：错误信息。任务成功时不返回，任务失败时返回 code 与 message。
  • task.error.code string：错误码。
  • task.error.message string：错误提示信息。
• task.created_at integer：任务创建时间的 Unix 时间戳（秒）。
• task.updated_at integer：任务状态最近一次更新时间的 Unix 时间戳（秒）。
• task.content object：任务产出内容，任务成功后返回。
  • task.content.url string：生成视频的下载地址，有效期有限，请及时下载或转存。
  • task.content.prompt string：结构化增强后的提示词，仅 task_type=h3_context_ir 的任务返回。
• task.resolution string：任务产出的分辨率。
• task.duration integer：任务产出的时长，单位：秒。
• task.usage object：本次请求的用量，仅任务成功后返回。
  • usage.total_seconds integer：总计量秒数 = 输入秒数 + 输出秒数。
  • usage.input_seconds integer：输入参考视频的秒数（存在参考视频时计量）。
  • usage.output_seconds integer：输出视频的秒数。
  • usage.input_image_count integer：输入图片总数（首帧 + 尾帧 + 参考图之和）。
  • usage.input_audio_seconds integer：输入参考音频的秒数（分段求和后取整），无参考音频时不返回。
  • usage.total_tokens integer：总 token 数 = prompt_tokens + completion_tokens。视频任务由用量换算得到。
  • usage.prompt_tokens integer：输入 token 数。
  • usage.completion_tokens integer：输出 token 数。
• task.ratio string：任务产出的宽高比，对该任务类型不适用时可能为空字符串。
• task.task_type string：任务类型。视频生成任务为 generation；其它可能取值：h3_context_ir（结构化提示词任务）、regeneration（视频重生成任务）。
• task.modality string：产出模态。视频生成与视频重生成任务为 video；h3_context_ir 任务为 text。

请求示例​

文生视频​

curl -X POST "https://api.yu-yu.ai/v1/video/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "一位女船长独自站在巨大的观景窗前，舰队跃迁离去，舰桥震动，镜头缓慢推进",
    "duration": 5,
    "metadata": {
      "resolution": "2K",
      "ratio": "16:9"
    }
  }'

完整的 JSON body：

{
  "model": "MiniMax-H3",
  "prompt": "一位女船长独自站在巨大的观景窗前，舰队跃迁离去，舰桥震动，镜头缓慢推进",
  "duration": 5,
  "metadata": {
    "resolution": "2K",
    "ratio": "16:9"
  }
}

图生视频（首帧）​

curl -X POST "https://api.yu-yu.ai/v1/video/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "镜头聚焦到背景中的人物，并让拉面碗里的热气更浓",
    "duration": 5,
    "metadata": {
      "resolution": "2K",
      "ratio": "adaptive",
      "first_frame_image": "https://your-cdn.example.com/first-frame.png"
    }
  }'

以上是最短写法：文本走顶层 prompt，首帧图走 metadata.first_frame_image。若希望完全按官方 content 数组下发，可把图片写成 metadata.content 元素：

{
  "model": "MiniMax-H3",
  "prompt": "镜头聚焦到背景中的人物，并让拉面碗里的热气更浓",
  "duration": 5,
  "metadata": {
    "resolution": "2K",
    "ratio": "adaptive",
    "content": [
      {
        "type": "image_url",
        "image_url": {
          "url": "https://your-cdn.example.com/first-frame.png"
        },
        "role": "first_frame"
      }
    ]
  }
}

参考生视频​

curl -X POST "https://api.yu-yu.ai/v1/video/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "duration": 5,
    "metadata": {
      "resolution": "2K",
      "ratio": "adaptive",
      "content": [
        {
          "type": "text",
          "text": "人物开口说话：随风而行，自由生活。音色参考参考音频 1"
        },
        {
          "type": "video_url",
          "video_url": {
            "url": "https://your-cdn.example.com/reference.mp4"
          },
          "role": "reference_video"
        },
        {
          "type": "audio_url",
          "audio_url": {
            "url": "https://your-cdn.example.com/reference.mp3"
          },
          "role": "reference_audio"
        }
      ]
    }
  }'

查询任务​

curl -X GET "https://api.yu-yu.ai/v1/video/generations/424010985738629" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应示例​

提交成功​

{
  "task_id": "424010985738629"
}

获取 task_id 后，通过查询任务接口轮询任务状态；任务成功后从 task.content.url 获取生成的视频。

查询成功（任务已完成）​

{
  "task": {
    "id": "424010985738629",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1785125529,
    "updated_at": 1785125946,
    "content": {
      "url": "https://your-cdn.example.com/h3-generated-2k-output.mp4"
    },
    "resolution": "2K",
    "duration": 5,
    "usage": {
      "total_seconds": 5,
      "input_seconds": 0,
      "output_seconds": 5,
      "input_image_count": 1,
      "input_audio_seconds": 6,
      "total_tokens": 273890,
      "prompt_tokens": 13500,
      "completion_tokens": 260390
    },
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video"
  }
}

查询成功（任务失败）​

{
  "task": {
    "id": "424010985738630",
    "model": "MiniMax-H3",
    "status": "failed",
    "error": {
      "code": "1026",
      "message": "video description contains sensitive content"
    },
    "created_at": 1785125529,
    "updated_at": 1785125700,
    "resolution": "2K",
    "duration": 5,
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video"
  }
}

请求失败​

参数错误、鉴权失败、限流等情况返回统一的错误信封：

{
  "type": "error",
  "error": {
    "type": "bad_request_error",
    "message": "invalid params, content must include a non-empty text item (prompt is required) (2013)",
    "http_code": "400"
  },
  "request_id": "021785229015510a2c883cf675b9804d"
}

任务状态说明​

常见错误​

HTTP 状态码与 error.type

内部错误码

错误码出现在错误信封的 error.message 末尾括号内；任务级错误出现在 task.error.code：