minimax-image-to-video

name	minimax-image-to-video
description	使用 MiniMax 图生视频 API，通过首帧图片或首尾帧图片生成视频；适用于需要将静态图片转化为动态视频的场景，支持运镜控制、自定义时长和分辨率
license	MIT

能力概述

图生视频（MiniMax） 提供四个接口，构成完整的异步视频生成工作流：

步骤	接口	方法	说明
1. 提交任务	单帧图生视频	POST /v1/video_generation	通过首帧图片 + 文本描述生成视频
1. 提交任务	首尾帧生成视频	POST /v1/video_generation	通过首帧+尾帧图片生成过渡视频
2. 查询状态	查询任务状态	GET /v1/query/video_generation	轮询任务进度，等待 Success/Fail
3. 获取文件	视频下载	GET /v1/files/retrieve	通过 file_id 获取下载链接（有效期 1 小时）

认证方式： platform_managed，密钥由平台注入，Edge Function 中通过 Deno.env.get("INTEGRATIONS_API_KEY") 读取，header 统一为 X-Gateway-Authorization: Bearer <key>。

支持平台： Web、MiniProgram

核心约束（MiniMax-Hailuo-02 模型）：

• resolution 仅支持 768P 和 1080P（720P/512P 会返回 2013 错误），默认 768P
• duration：768P 支持 6s 或 10s；1080P 仅支持 6s（不可传 3s/5s）
• 默认 duration=6；如 UI 提供时长选择器，当 resolution=1080P 时需自动重置为 6 并禁用其他选项
• 首尾帧模式不支持 512P 分辨率

视频获取流程（2 步）：

1. 轮询查询接口直到 status=Success，获得 file_id
2. 调用 files/retrieve?file_id=... 获取 download_url（有效期仅 1 小时）
3. 必须立即将 download_url 上传到 Supabase Storage，使用持久化的 publicUrl 存入数据库

---

生成期用法（Agent 直接调用）

详见 references/video-generation-api.md 和 references/video-query-retrieve-api.md。

完整异步工作流（提交 → 轮询 → 获取文件 → 转存 Storage）：

const apiKey = process.env["INTEGRATIONS_API_KEY"]!;

// Step 1: 提交图生视频任务（单帧模式）
async function submitImageToVideo(params: {
  firstFrameImage: string;
  prompt?: string;
  duration?: number;
  resolution?: string;
}): Promise<{ taskId: string }> {
  const response = await fetch(
    "https://app-bo4w33bsdqm9-api-VaOw5VAJdQBa-gateway.appmiaoda.com/v1/video_generation",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Gateway-Authorization": `Bearer ${apiKey}`,
      },
      body: JSON.stringify({
        model: "MiniMax-Hailuo-02",
        first_frame_image: params.firstFrameImage,
        prompt: params.prompt ?? "",
        duration: params.duration ?? 6,
        resolution: params.resolution ?? "768P",
        prompt_optimizer: true,
      }),
    }
  );

  if (!response.ok) throw  ();
   json =  response.();
   (json.?. !== ) {
      ();
  }
   { : json. };
}


  (): <{
  : ;
  ?: ;
  ?: ;
  ?: ;
}> {
   response =  (
    ,
    {
      : ,
      : {
        : ,
      },
    }
  );

   (!response.)   ();
   json =  response.();
   {
    : json.,
    : json.,
    : json.,
    : json.,
  };
}


  (): <> {
   response =  (
    ,
    {
      : ,
      : {
        : ,
      },
    }
  );

   (!response.)   ();
   json =  response.();
   (json.?. !== ) {
      ();
  }
   json..;
}


  (): <{ : ; :  }> {
   { taskId } =  (params);

    = ;
    =  *  * ; 
   deadline = .() + ;

   (.() < deadline) {
      ( (r, ));
     result =  (taskId);
     (result. === ) {
       downloadUrl =  (result.!);
       { downloadUrl, : result.! };
    }
     (result. === ) {
        ();
    }
    
  }
    ();
}

---

首尾帧组合工作流示例

同时提供首帧（first_frame_image）和尾帧（last_frame_image），生成从起始画面平滑过渡到结束画面的视频：

const apiKey = Deno.env.get("INTEGRATIONS_API_KEY")!;

/**
 * 首尾帧组合图生视频完整工作流：提交 → 轮询 → 获取链接。
 * @param firstFrameImage - 首帧图片 URL 或 Base64 Data URL
 * @param lastFrameImage - 尾帧图片 URL 或 Base64 Data URL
 * @param prompt - 视频文本描述（可选）
 * @returns 视频下载链接及文件 ID
 */
async function generateFirstLastFrameVideo(params: {
  firstFrameImage: string;
  lastFrameImage: string;
  prompt?: string;
  duration?: number;
  resolution?: string;
}): Promise<{ downloadUrl: string; fileId: string }> {
  // Step 1: 提交首尾帧视频生成任务
  const submitResponse = await fetch(
    "https://app-bo4w33bsdqm9-api-nYWNRQr5pV1L-gateway.appmiaoda.com/v1/video_generation",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Gateway-Authorization": `Bearer ${apiKey}`,
      },
      body: JSON.stringify({
        model: "MiniMax-Hailuo-02",
        first_frame_image: params.firstFrameImage,
        : params.,
        : params. ?? ,
        : params. ?? ,
        : params. ?? ,
        : ,
      }),
    }
  );

   (!submitResponse.)   ();
   submitJson =  submitResponse.();
   (submitJson.?. !== ) {
      (
      
    );
  }
   :  = submitJson.;

  
    = ;
    =  *  * ; 
   deadline = .() + ;

   (.() < deadline) {
      ( (r, ));
     queryResponse =  (
      ,
      {
        : ,
        : { :  },
      }
    );
     (!queryResponse.)   ();
     queryJson =  queryResponse.();

     (queryJson. === ) {
      
       retrieveResponse =  (
        ,
        {
          : ,
          : { :  },
        }
      );
       (!retrieveResponse.)   ();
       retrieveJson =  retrieveResponse.();
       { : retrieveJson.., : queryJson. };
    }
     (queryJson. === ) {
        ();
    }
    
  }
    ();
}


 result =  ({
  : ,
  : ,
  : ,
  : ,
  : ,
});
.(, result.);

生成期文件下载（必须执行）：

生成接口返回的 download_url 有效期仅 1 小时，在生成期（Agent 直接调用场景）获得 URL 后，必须立即使用 Bash 工具将文件下载到本地，以便用户查看结果。

curl -L -o <本地路径> "<download_url>"

完整生成期工作流（含下载步骤）：

1. 调用生成函数获取 downloadUrl
2. 使用 Bash 工具执行 curl -L -o <本地路径> "<url>" 将文件下载到本地
3. 告知用户文件已保存到对应路径

注意：download_url 有效期仅 1 小时，必须在获得 URL 后立即下载，不要延迟。

---

生成后用法（应用内通过 Edge Function 调用）

应用内需部署 三个 Edge Function：

Edge Function	对应接口	说明
submit-image-to-video	单帧 或 首尾帧 POST	提交视频生成任务
query-video-status	GET query	轮询任务状态
retrieve-video-file	GET files/retrieve	获取下载链接并转存 Supabase Storage

平台差异：

• GET 接口的 Edge Function 调用在 H5/MiniProgram 中必须把参数放在 URL 中，不可放在 body（H5 会静默忽略 GET 请求的 body）
• 前端轮询计数器必须用 useRef，不可用 useState（useState 触发重渲染会使轮询失控）
• download_url 有效期仅 1 小时，必须立即转存到 Supabase Storage

详细 Edge Function 代码、前端代码及注意事项，见：

• references/video-generation-api.md（提交接口）
• references/video-query-retrieve-api.md（查询 + 下载接口）