HappyHorse 1.1 API：最多9张参考图，多素材视频生成指南

AI 视频生成正在从单纯的文字转视频，逐渐转向围绕商品、人物、场景和视觉素材进行更精细的内容控制。对于开发者而言，生成一段视频并不算特别复杂，真正影响产品落地的，是如何让生成结果符合指定的视觉要求，并且能够稳定地接入现有业务系统。

2026 年 10 月，阿里云 Model Studio 的官方模型目录及 API 文档已经更新 HappyHorse 1.1 系列接口。与此前的基础视频生成模式相比，新版本提供了文生视频（T2V）、首帧图生视频（I2V）和参考图生视频（R2V）三种不同的调用方式。其中，HappyHorse 1.1 R2V 支持最多 9 张参考图输入，可以根据多张素材生成具有指定人物、物体和场景关系的视频。这项能力对电商商品视频、品牌广告、角色短片和多素材内容制作具有实际意义。

根据官方模型目录，HappyHorse 1.1 支持 480P、720P 和 1080P 分辨率，视频时长为 3—15 秒，输出帧率为 24fps，格式为 MP4。

对于希望通过 API 构建视频生成应用的团队来说，这次更新值得关注的并不只是画质参数，而是参考素材控制方式的扩展。本文将从模型选择、参数配置、参考图组织、API 接入和业务应用几个方面展开分析。

一、HappyHorse 1.1 更新了什么？三种视频生成模式如何选择？

在使用视频生成 API 之前，需要先明确不同生成模式的输入方式和适用任务。HappyHorse 1.1 提供三个主要模型：

表格

三种模式虽然都可以生成视频，但解决的问题并不相同。

1. T2V：从文字描述生成完整视频

Text-to-Video（T2V）是最直接的生成方式。开发者只需要提供文本提示词，描述视频中的主体、场景、动作、镜头和视觉风格，模型就可以根据描述生成视频。

例如，一个电商团队需要制作一段咖啡产品宣传视频，可以输入：

A premium coffee cup placed on a wooden table in a modern minimalist cafe.  Warm morning sunlight enters through the window. Steam slowly rises from the coffee. The camera gradually moves closer to the cup.  Cinematic lighting, realistic textures, smooth camera movement, commercial product photography style.

这段提示词包含主体、环境、动作和镜头运动等信息。T2V 比较适合没有现成素材、需要从创意直接生成视频的场景。但如果对商品外观、品牌标识和人物身份有明确要求，仅依靠文本描述可能无法充分控制结果，这时就应该考虑图像输入模式。

2. I2V：让静态图片产生动态效果

Image-to-Video（I2V）使用一张图片作为视频首帧，再通过文字描述指定后续运动。

例如，商家已经拥有一张完整的商品摄影图，希望将其制作成动态广告。输入图片负责确定商品的初始外观，提示词则负责描述后续动作。可以这样设计：

The camera slowly moves around the perfume bottle.  Soft light reflects across the glass surface. The background remains clean and elegant.  The bottle stays in its original shape and position. Smooth cinematic motion, premium commercial style.

与完全依赖文本生成相比，I2V 可以利用原始图片提供更明确的视觉起点。它适合：

• 商品静态图转动态视频。
• 服装模特图片动画化。
• 产品包装展示。
• 插画和角色动态效果。
• 已有视觉素材的短视频制作。

需要注意，首帧图片不代表整个视频都会严格保持原图。生成过程中，商品结构、文字和局部细节仍可能出现变化，最终素材需要进行检查。

3. R2V：利用多张参考图控制视频内容

Reference-to-Video（R2V）是这次值得重点关注的模式。与 I2V 主要依赖一张首帧图片不同，R2V 可以同时接收多张参考图，并通过提示词说明每张图片分别代表什么。

根据阿里云官方文档，HappyHorse 1.1 R2V 支持 1—9 张参考图片。

例如，制作一段服装商品展示视频，可以准备：

• 图片 1：服装模特。
• 图片 2：服装正面细节。
• 图片 3：服装背面设计。
• 图片 4：配套包包。
• 图片 5：拍摄场景参考。

在提示词中明确引用：

The model from [Image 1] wears the outfit shown in [Image 2].  Show the clothing details from [Image 3], while carrying the bag from [Image 4].  Use the visual atmosphere from [Image 5].  Create a premium fashion commercial with smooth camera movement. Preserve the key appearance of the clothing and accessories.

这里最重要的是 [Image 1]、[Image 2] 等引用标记。它们需要与 API 请求中的参考图排列顺序对应。如果图片顺序发生变化，提示词中的素材指向也必须同步调整，否则模型可能无法按照预期理解素材关系。

这使得 R2V 不只是增加了图片数量，而是为多素材视频生成提供了更明确的组织方式。

二、最多 9 张参考图，如何提高视频生成的素材控制能力？

多参考图能力并不意味着上传越多图片，生成质量就一定越好。开发者需要先明确每张图片承担的作用，再组织素材。对于电商视频而言，可以将参考图分成以下几类：

表格

1. 参考图片的技术要求

官方 R2V 文档给出了明确的素材要求：

• 支持 JPEG、JPG、PNG 和 WEBP。
• 最短边至少 400 像素。
• 单张图片最大 20MB。
• 建议使用 720P 或更高分辨率的清晰素材。
• 支持公开可访问的图片 URL，也支持 Base64 编码图片。
• 最多输入 9 张参考图。

这些条件不仅影响 API 是否能够成功接收请求，也会影响模型对图片内容的识别。例如，一张分辨率过低的服装细节图，可能无法提供足够的信息来识别纹理和配饰；即使成功生成视频，最终细节也可能与预期存在差异。

2. 多张图片应该如何排序？

建议按照主体、关键细节、辅助物品和场景的顺序组织图片。例如：

[Image 1] 人物主体 [Image 2] 商品服装 [Image 3] 商品细节 [Image 4] 配饰 [Image 5] 场景环境

这样做的好处是方便开发者维护素材映射关系，也便于后续修改提示词。如果需要批量生成视频，可以在后端建立素材索引表，将图片 URL、素材类型和引用编号关联起来。不要只保存图片文件名，否则当素材顺序发生变化时，很容易造成提示词与参考图不匹配。

3. 不要把参考图当成绝对约束

参考图可以为模型提供视觉条件，但不能等同于传统视频剪辑中的逐帧锁定。例如，商品图上的小字号文字、复杂图案和品牌 Logo，在动态生成过程中仍可能出现变化。

如果任务对商品外观有较高要求，建议采用以下流程：

1. 先生成较短的视频片段。
2. 检查主体外观和关键细节。
3. 检查镜头运动是否合理。
4. 对不符合要求的素材重新调整提示词。
5. 最终通过人工审核后再进入发布环节。

这种方法比一次性生成大量视频后再筛选，更容易定位问题。

三、HappyHorse 1.1 API 实操：如何调用 R2V 生成多参考图视频？

对于已经熟悉 REST API 的开发者，可以直接使用阿里云 Model Studio 提供的 HTTP 接口。官方 API 使用异步调用方式，创建任务后返回 task_id，再通过任务查询接口获取生成结果。

需要特别注意，下面的示例使用的是阿里云 Model Studio 新加坡区域的 Workspace 专属域名。实际调用时必须替换成自己模型所在区域对应的 Workspace ID，模型、API Key 和请求地址必须属于同一区域。

1. 配置 API Key 和基础环境

首先在阿里云 Model Studio 控制台创建对应区域的 API Key。建议通过环境变量管理密钥：

export DASHSCOPE_API_KEY="your_api_key"
export WORKSPACE_ID="your_workspace_id"

不要将密钥直接写进前端代码，也不要上传到公开代码仓库。

2. 构建 R2V 请求

下面以服装视频生成为例。准备三张图片：

• 模特主体图。
• 服装参考图。
• 配饰参考图。

然后发送请求：

curl --location \
"https://${WORKSPACE_ID}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis" \
-H "X-DashScope-Async: enable" \
-H "Authorization: Bearer ${DASHSCOPE_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
  "model": "happyhorse-1.1-r2v",
  "input": {
    "prompt": "The woman from [Image 1] wears the outfit from [Image 2] and carries the accessory from [Image 3]. Create a cinematic fashion product video with smooth camera movement. Preserve the key visual characteristics of the subject and products.",
    "media": [
      {
        "type": "reference_image",
        "url": "https://example.com/model.jpg"
      },
      {
        "type": "reference_image",
        "url": "https://example.com/outfit.jpg"
      },
      {
        "type": "reference_image",
        "url": "https://example.com/accessory.jpg"
      }
    ]
  },
  "parameters": {
    "resolution": "720P",
    "ratio": "16:9",
    "duration": 5,
    "watermark": true,
    "seed": 12345
  }
}'

这里有几个参数需要理解：

表格

官方文档支持的画幅包括 16:9、9:16、3:4、4:3、4:5、5:4、1:1、9:21 和 21:9。对于不同平台，可以根据发布需求选择对应比例。例如，横版宣传视频可以选择 16:9，竖版短视频可以选择 9:16，电商社交素材则可以考虑 4:5。

固定 seed 可以提高生成结果的可复现性，但不意味着使用相同参数就一定能够得到完全一致的视频。

3. 理解任务返回结果

请求成功后，接口会返回类似下面的结构：

{
  "output": {
    "task_status": "PENDING",
    "task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  },
  "request_id": "xxxxxxxx"
}

开发者需要保存 task_id，用于后续查询。官方任务状态包括：

表格

官方建议以合理的间隔轮询任务，例如每 15 秒查询一次。

4. 处理生成结果和视频文件

任务成功后，响应会包含 video_url，以及视频时长、分辨率和比例等使用信息。这里有一个容易忽略的细节：官方返回的视频 URL 有效期为 24 小时。 因此，不建议将这个 URL 直接作为企业系统的永久素材地址。

更合理的处理方式是：

1. 检查任务状态是否为 SUCCEEDED。
2. 获取返回的 video_url。
3. 下载 MP4 视频文件。
4. 上传到企业自己的对象存储。
5. 将永久存储地址与业务任务 ID 关联。
6. 保存生成参数、提示词和素材引用记录。

这样即使官方临时下载链接失效，企业内部也能够继续管理和使用已经生成的视频。

四、T2V、I2V、R2V 应该如何选择？用一个商品视频工作流说明

对于实际开发项目来说，不需要让所有视频任务都走同一种生成模式。以一个服装电商团队为例，可以根据素材情况设计三条工作流。

第一种：没有现成商品图片。 如果商家只有产品创意，需要生成一段概念展示视频，可以使用 T2V。输入商品特征、使用场景和视觉风格，直接生成视频。

第二种：已经有商品主图。 如果商品摄影已经完成，希望让商品产生动态展示效果，可以使用 I2V。将商品图作为首帧，再描述镜头运动、环境变化和商品展示动作。

第三种：需要整合人物、服装和场景素材。 如果商家有模特图、服装图、配饰图和场景参考图，可以使用 R2V。这种模式适合多个素材共同参与视频生成的情况。

三种模式可以形成一个简单的选择逻辑：

表格

需要注意，HappyHorse 1.1 当前的三个模型并不等于一个完整的视频剪辑软件。官方将已有视频编辑能力单独列为 HappyHorse 1.0 Video Edit，不能将其误写成 HappyHorse 1.1 R2V 已经支持任意视频修改。

五、API 接入之后，开发者还需要处理哪些工程问题？

视频生成与普通文本 API 有一个明显区别：生成任务通常需要较长时间，而且返回结果不是立即可用的。因此，真正接入业务系统时，不能简单地在用户请求中同步等待视频生成完成。

1. 将视频生成设计成后台任务

推荐将用户请求和视频生成执行分开。用户提交视频创作需求后，业务服务先保存任务信息，再调用模型接口；随后由后台任务管理模块负责查询生成状态。

可以设计以下数据字段：

表格

业务系统可以通过数据库记录每次任务的完整状态。

2. 避免重复提交造成额外费用

例如，用户点击生成按钮后，浏览器出现网络超时。如果前端直接再次发送生成请求，可能产生两个独立的生成任务。更合理的处理方式是：

• 在业务侧生成唯一请求标识。
• 保存请求与模型 task_id 的对应关系。
• 网络异常时先查询已有任务。
• 只有明确需要重新生成时，才创建新任务。

这样可以降低重复请求带来的资源浪费。需要注意，业务侧的请求标识不等同于模型接口原生支持的幂等键，具体去重逻辑需要由应用后端实现。

3. 建立视频素材存储和生命周期管理

模型返回的临时视频链接不适合作为长期素材库。企业可以采用对象存储保存最终 MP4 文件，同时记录：

• 原始图片。
• 生成提示词。
• 模型版本。
• 输出分辨率。
• 视频时长。
• 生成时间。
• 任务状态。
• 最终文件地址。

这些信息对于后续视频复用、问题追踪和批量创作都很重要。

4. 根据业务需求选择模型和分辨率

不是每个任务都需要 1080P。例如，短视频创意验证阶段，可以先使用 720P 生成样片，确认镜头、人物和商品外观符合要求后，再使用目标分辨率制作正式素材。这样可以避免在提示词和参考素材尚未确定时，就反复投入高规格生成资源。

六、HappyHorse API 与多模型应用如何配合？

随着 AI 应用功能不断增加，企业后端往往不只需要视频生成模型，还需要文本理解、内容策划和代码处理等能力。例如，一套电商视频自动化系统可以分成几个部分：

• 使用 Gemini、DeepSeek 或 Kimi 分析商品资料，提取卖点。
• 使用文本模型生成视频脚本和镜头描述。
• 根据素材情况选择 HappyHorse T2V、I2V 或 R2V。
• 将生成的视频保存到对象存储。
• 使用文本模型辅助生成标题、字幕和发布文案。
• 将视频交给人工审核后发布。

这里需要区分不同模型的职责。HappyHorse 主要负责视频生成；DeepSeek、Gemini 和 Kimi 可以参与前期内容分析与提示词构建；Codex 则可以帮助开发者编写 API 调用代码、调试任务管理逻辑和维护后端程序。

如果企业还需要管理多个国产大模型的接口，可以通过 星链 API 进行相应的模型接入和调用管理，减少不同模型之间重复配置的工作。但视频生成 API 与文本大模型 API 属于不同的能力层，是否能够通过同一个接口网关调用 HappyHorse，需要以实际模型目录和接口支持情况为准，不能因为支持 DeepSeek 或 Kimi 就推断已经支持 HappyHorse。

七、HappyHorse 1.1 适合哪些实际业务？

从三种生成模式来看，HappyHorse 1.1 的价值主要体现在多素材视频生产和视觉内容生成。

1. 电商商品视频

商家可以将商品图片、服装细节和场景素材组织成参考图，生成商品展示视频。特别是已经拥有较完整图片素材的电商团队，可以重点测试 I2V 和 R2V。需要注意，生成视频中的商品颜色、结构和文字可能发生变化，不能直接将模型生成结果视为准确的商品实物展示。

2. 品牌营销短片

品牌团队可以准备产品图、人物图和场景参考图，再通过提示词设计镜头变化。R2V 适合多个视觉元素共同参与的场景，能够减少完全依赖文字描述所带来的素材不确定性。

3. 短视频内容生产

内容团队可以先使用文本模型整理选题、脚本和镜头描述，再调用视频生成接口制作片段。如果需要统一角色形象，可以使用参考图模式，尽量让人物、服装和场景保持一致。

4. 视频创作平台和 SaaS 产品

对于开发视频生成产品的团队，HappyHorse API 可以作为后端视频生成能力的一部分。前端负责素材上传、提示词填写和参数选择，后端负责任务提交、状态查询、文件存储和结果管理。这种架构更适合批量生成、用户任务隔离和视频素材管理。

八、总结：HappyHorse 1.1 的重点不只是生成视频，而是素材控制能力

HappyHorse 1.1 的 API 更新，为开发者提供了 T2V、I2V 和 R2V 三种不同的视频生成路径。其中，R2V 最值得关注的是最多 9 张参考图片的输入能力。开发者可以通过图片顺序和提示词引用，将人物、商品、道具和场景等素材组织起来，生成符合具体创作需求的视频。

从公开规格来看，HappyHorse 1.1 支持 480P、720P 和 1080P，视频时长 3—15 秒，24fps，MP4 输出。官方 API 采用异步任务机制，成功后返回的视频 URL 有效期为 24 小时，企业需要及时下载并保存生成文件。

对于开发者来说，建议先根据业务素材选择合适的生成模式，再通过小规模测试确定提示词结构、参考图数量和输出参数。只有将模型调用、任务管理、素材存储和结果审核结合起来，才能把视频生成能力真正整合进业务系统。

AI 视频 API 的价值不只是让应用能够生成一段视频，更重要的是让视频生成成为可以被管理、复用和规模化调用的业务能力。