> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evolink.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Wan2.7 参考视频

> - WAN2.7 (wan2.7-reference-video) 模型支持参考生视频模式，可将人或物体作为主角，生成单角色表演或多角色互动视频
- 支持多模态输入：首帧图（`image_start`）、多张参考图片（`image_urls`）、多个参考视频（`video_urls`）以及多角色音色绑定
- **必须**至少提供一个参考图片（`image_urls`）或参考视频（`video_urls`），仅传 `image_start` 不满足此要求；`image_urls` + `video_urls` 合计 ≤ 5
- **prompt 中角色指代规则：** 中文用「图1、图2 / 视频1、视频2」指代（与 `image_urls` / `video_urls` 数组顺序一一对应，1-based）；英文用 "Image 1"、"Video 1"。图片与视频分别计数，可同时存在「图1」「视频1」
- **多角色音色绑定：** 推荐使用 `model_params.voice_bindings`（精确绑定），兼容旧协议 `audio_urls`（按顺序对齐）
- 异步处理模式，使用返回的任务ID  [进行查询](/cn/api-manual/task-management/get-task-detail)
- 生成的视频链接，有效期为24小时，请尽快保存
- **计费说明**：采用「输入视频时长 + 输出视频时长」联合计费，仅成功生成视频后计费，失败不收费



## OpenAPI

````yaml cn/api-manual/video-series/wan2.7/wan2.7-reference-video.json POST /v1/videos/generations
openapi: 3.1.0
info:
  title: wan2.7-reference-video接口
  description: 使用WAN2.7模型进行参考视频生成视频，通过上传参考图片、参考视频及音频生成新视频
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.evolink.ai
    description: 生产环境
security:
  - bearerAuth: []
paths:
  /v1/videos/generations:
    post:
      tags:
        - 视频生成
      summary: wan2.7-reference-video接口
      description: >-
        - WAN2.7 (wan2.7-reference-video) 模型支持参考生视频模式，可将人或物体作为主角，生成单角色表演或多角色互动视频

        -
        支持多模态输入：首帧图（`image_start`）、多张参考图片（`image_urls`）、多个参考视频（`video_urls`）以及多角色音色绑定

        - **必须**至少提供一个参考图片（`image_urls`）或参考视频（`video_urls`），仅传 `image_start`
        不满足此要求；`image_urls` + `video_urls` 合计 ≤ 5

        - **prompt 中角色指代规则：** 中文用「图1、图2 / 视频1、视频2」指代（与 `image_urls` /
        `video_urls` 数组顺序一一对应，1-based）；英文用 "Image 1"、"Video
        1"。图片与视频分别计数，可同时存在「图1」「视频1」

        - **多角色音色绑定：** 推荐使用 `model_params.voice_bindings`（精确绑定），兼容旧协议
        `audio_urls`（按顺序对齐）

        - 异步处理模式，使用返回的任务ID 
        [进行查询](/cn/api-manual/task-management/get-task-detail)

        - 生成的视频链接，有效期为24小时，请尽快保存

        - **计费说明**：采用「输入视频时长 + 输出视频时长」联合计费，仅成功生成视频后计费，失败不收费
      operationId: createWan27ReferenceVideoGeneration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Wan27ReferenceVideoRequest'
            examples:
              single_reference_video:
                summary: 单条参考视频
                value:
                  model: wan2.7-reference-video
                  prompt: 参考视频中的人物在草地上跳舞
                  video_urls:
                    - https://example.com/reference.mp4
              multi_subject_with_voice_bindings:
                summary: 多主体参考 + 精确音色绑定（推荐）
                value:
                  model: wan2.7-reference-video
                  prompt: 图1抱着图2，在图3的椅子上弹奏一支舒缓的乡村民谣，并说道："今天的阳光真好"
                  image_urls:
                    - https://example.com/girl.jpg
                    - https://example.com/object.png
                    - https://example.com/chair.png
                  model_params:
                    voice_bindings:
                      image1: https://example.com/girl_voice.mp3
                  duration: 10
              multi_grid_storyboard:
                summary: 单图参考（多宫格故事板）
                value:
                  model: wan2.7-reference-video
                  prompt: >-
                    参考图片，3D 卡通冒险电影风。分镜：1. 全景奇幻森林；2. 男孩拨开藤蔓探路；3. 小机器人扫描前方；4.
                    藏宝图特写；5. 男孩兴奋表情；6. 跳过树根继续深入
                  image_urls:
                    - https://example.com/storyboard.png
                  duration: 10
      responses:
        '200':
          description: 视频任务创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoGenerationResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: invalid_request
                  message: Invalid request parameters
                  type: invalid_request_error
        '401':
          description: 未认证、Token无效或过期
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: unauthorized
                  message: Invalid or expired token
                  type: authentication_error
        '402':
          description: 配额不足、需要充值
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: insufficient_quota
                  message: Insufficient quota. Please top up your account.
                  type: insufficient_quota
        '403':
          description: 无权限访问
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: model_access_denied
                  message: 'Token does not have access to model: wan2.7-reference-video'
                  type: invalid_request_error
        '429':
          description: 请求频率超限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: rate_limit_exceeded
                  message: Too many requests, please try again later
                  type: rate_limit_error
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: internal_error
                  message: Internal server error
                  type: api_error
components:
  schemas:
    Wan27ReferenceVideoRequest:
      required:
        - model
        - prompt
      type: object
      properties:
        model:
          type: string
          description: 模型名称，固定为 `wan2.7-reference-video`
          enum:
            - wan2.7-reference-video
          example: wan2.7-reference-video
        prompt:
          type: string
          description: >-
            视频生成的文本提示词。支持中英文，每个汉字/字母/标点占 1 个字符，超过部分会自动截断，最大长度 5000 字符


            **角色指代规则：**

            - 中文：用「图1、图2 / 视频1、视频2」指代参考素材，与 `image_urls` / `video_urls`
            数组顺序一一对应（1-based）

            - 英文：用 "Image 1"、"Video 1"（首字母大写，字母数字之间空格）

            - 图片与视频分别计数，即可同时存在「图1」与「视频1」

            - 若仅有一张参考图或一个参考视频，可简化为「参考图片」或「参考视频」


            **多宫格图像（故事板）：** 当传入一张多宫格图像时，提示词建议按多分镜形式描述关键画面，模型会自动识别宫格逻辑并补全镜头
          maxLength: 5000
          example: 视频1抱着图3，在图4的椅子上弹奏一支舒缓的乡村民谣
        negative_prompt:
          type: string
          description: 负面提示词，描述不希望在视频画面中出现的内容。支持中英文，最大长度 500 字符，超过部分会自动截断
          maxLength: 500
          example: 模糊, 低质量
        image_start:
          type: string
          format: uri
          description: >-
            首帧图片 URL，作为视频的起始画面。**不计入** `image_urls` + `video_urls` 合计 ≤ 5
            的参考媒体上限。**不接受音色绑定**（首帧图本身不参与多角色音色分配）


            **搭配场景：**

            - 首帧中已出现待参考主体：可与参考素材联合控制，强化主体一致性

            - 首帧中未出现待参考主体：可用参考素材定义视频动态过程中新出现的主体


            **图像限制：**

            - 格式：JPEG、JPG、PNG（不支持透明通道）、BMP、WEBP

            - 分辨率：宽和高的范围为 `[240, 8000]` 像素

            - 宽高比：1:8 ～ 8:1

            - 文件大小：不超过 `20MB`
          example: https://example.com/first_frame.jpg
        image_urls:
          type: array
          items:
            type: string
            format: uri
          description: |-
            参考图片 URL 数组。可提供主体角色（人物/动物/物体）或场景背景；当包含主体时，建议每张图仅含**单一**角色

            **数量限制：**
            - `image_urls` + `video_urls` 合计 ≤ 5
            - 必须与 `video_urls` 至少二选一传入（仅传 `image_start` 不满足要求）

            **图像限制：**
            - 格式：JPEG、JPG、PNG（不支持透明通道）、BMP、WEBP
            - 分辨率：宽和高的范围为 `[240, 8000]` 像素
            - 宽高比：1:8 ～ 8:1
            - 文件大小：不超过 `20MB`
          example:
            - https://example.com/ref1.jpg
            - https://example.com/ref2.jpg
        video_urls:
          type: array
          items:
            type: string
            format: uri
          description: >-
            参考视频 URL
            数组。视频内容建议包含主体（人物/动物/物体），不建议使用空镜或纯背景视频；当包含主体时，建议每个视频仅含**单一**角色。若视频自带声音，可作为音色参考


            **数量限制：**

            - `image_urls` + `video_urls` 合计 ≤ 5

            - 必须与 `image_urls` 至少二选一传入


            **视频限制：**

            - 格式：mp4、mov

            - 时长：`1 ~ 30` 秒

            - 分辨率：宽和高的范围为 `[240, 4096]` 像素

            - 宽高比：1:8 ～ 8:1

            - 文件大小：不超过 `100MB`


            **注意：** 当请求中传入了 `video_urls` 时，`duration` 上限收紧到 10 秒
          example:
            - https://example.com/reference.mp4
        audio_urls:
          type: array
          items:
            type: string
            format: uri
          maxItems: 5
          description: >-
            **【兼容字段，推荐改用 `model_params.voice_bindings`】**


            参考音色音频 URL 数组，按顺序与参考素材绑定——先匹配 `video_urls` 数组、再匹配 `image_urls`
            数组（按出现顺序一一对齐）。最多 5 个元素


            **优先级：**

            - 同时传入 `model_params.voice_bindings` 与 `audio_urls` 时，仅使用
            `voice_bindings`，本字段被忽略

            - 若 `video_urls` 中的视频自带音频且未指定音色绑定，则使用视频原声；指定音色绑定后覆盖原声


            **音频限制：**

            - 支持格式：`wav`、`mp3`

            - 时长范围：`1 ~ 10` 秒

            - 文件大小：不超过 `15MB`
          example:
            - https://example.com/voice1.mp3
            - https://example.com/voice2.mp3
        model_params:
          type: object
          description: 高级参数容器（推荐使用）
          properties:
            voice_bindings:
              type: object
              description: >-
                **多角色音色精确绑定（推荐）。** 优先级高于 `audio_urls`


                **绑定规则：**

                - key 形如 `image{N}` 或 `video{N}`（1-based，不允许前导零，如
                `image1`、`video2`）

                - key 中的 N 对应 prompt 中「图N」或「视频N」标识，与 `image_urls[N-1]` /
                `video_urls[N-1]` 一一对应

                - value 为对应角色的音色音频 URL

                - 总绑定数 ≤ 5

                - `image_start`（首帧图）**不接受**音色绑定

                - 可跳过部分角色（如仅绑定 image1 与 image3，image2 不绑定）


                **音频限制：**

                - 支持格式：`wav`、`mp3`

                - 时长范围：`1 ~ 10` 秒

                - 文件大小：不超过 `15MB`


                **校验失败示例：**

                - key 格式错误：`voice_bindings key "img1"/"image01" invalid`

                - 索引越界：`voice_bindings.image5 out of range`

                - value 为空字符串、重复绑定、绑定总数超过 5
              additionalProperties:
                type: string
                format: uri
              example:
                image1: https://example.com/voice_a.mp3
                image3: https://example.com/voice_c.mp3
                video1: https://example.com/voice_v.mp3
        quality:
          type: string
          description: |-
            视频清晰度，默认为`720p`

            **说明：**
            - `720p`: 标准清晰度，标准价格，此为默认值
            - `1080p`: 高清晰度，价格会提升
          enum:
            - 720p
            - 1080p
          default: 720p
          example: 720p
        aspect_ratio:
          type: string
          description: >-
            视频宽高比，默认为 `16:9`


            **生效逻辑：**

            - 未传入 `image_start`：按指定的 `aspect_ratio` 生成视频

            - 已传入 `image_start`：本字段**被忽略**，自动以首帧图像的宽高比生成近似比例的视频


            **不同档位输出分辨率：**


            | 分辨率档位 | 16:9 | 9:16 | 1:1 | 4:3 | 3:4 |

            | --- | --- | --- | --- | --- | --- |

            | 720p | 1280×720 | 720×1280 | 960×960 | 1104×832 | 832×1104 |

            | 1080p | 1920×1080 | 1080×1920 | 1440×1440 | 1648×1248 | 1248×1648
            |
          enum:
            - '16:9'
            - '9:16'
            - '1:1'
            - '4:3'
            - '3:4'
          default: '16:9'
          example: '16:9'
        duration:
          type: number
          description: |-
            视频时长（秒），整数

            **取值范围：**
            - 未传 `video_urls`：`2 ~ 15`，默认 `5`
            - 已传 `video_urls`：`2 ~ 10`（上限收紧到 10 秒）

            **计费说明：** 实际扣费以生成视频秒数为准
          minimum: 2
          maximum: 15
          default: 5
          example: 5
        seed:
          type: integer
          description: |-
            随机种子，默认随机

            **说明：**
            - 取值范围：`1` ~ `2147483647`
            - 固定 seed 可在调试 prompt 时降低参数变化的干扰，提升结果可复现性
          minimum: 1
          maximum: 2147483647
          example: 42
        prompt_extend:
          type: boolean
          description: |-
            是否开启prompt智能改写，开启后将使用大模型优化正向提示词，对描述性不足、较为简单的prompt提升效果较明显。

            **注意：** 默认值为 `false`，不传或传 `false` 时不会触发改写，如需开启请显式传 `true`
          default: false
          example: false
        callback_url:
          type: string
          description: |-
            任务完成后的HTTPS回调地址

            **回调时机：**
            - 任务完成（completed）、失败（failed）或取消（cancelled）时触发
            - 在计费确认完成后发送

            **安全限制：**
            - 仅支持HTTPS协议
            - 禁止回调到内网IP地址（127.0.0.1、10.x.x.x、172.16-31.x.x、192.168.x.x等）
            - URL长度不超过`2048`字符

            **回调机制：**
            - 超时时间：`10`秒
            - 失败后最多重试`3`次（会分别在失败的`1`秒/`2`秒/`4`秒后进行重试）
            - 回调响应体格式与任务查询接口返回的格式一致
            - 回调地址若返回2xx状态码视为成功，其他状态码会触发重试
          format: uri
          example: https://your-domain.com/webhooks/video-task-completed
    VideoGenerationResponse:
      type: object
      properties:
        created:
          type: integer
          description: 任务创建时间戳
          example: 1757169743
        id:
          type: string
          description: 任务ID
          example: task-unified-1757169743-7cvnl5zw
        model:
          type: string
          description: 实际使用的模型名称
          example: wan2.7-reference-video
        object:
          type: string
          enum:
            - video.generation.task
          description: 任务的具体类型
        progress:
          type: integer
          description: 任务进度百分比 (0-100)
          minimum: 0
          maximum: 100
          example: 0
        status:
          type: string
          description: 任务状态
          enum:
            - pending
            - processing
            - completed
            - failed
          example: pending
        task_info:
          $ref: '#/components/schemas/VideoTaskInfo'
          description: 视频任务详细信息
        type:
          type: string
          enum:
            - text
            - image
            - audio
            - video
          description: 任务的输出类型
          example: video
        usage:
          $ref: '#/components/schemas/Usage'
          description: 使用量和计费信息
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: 错误代码标识符
            message:
              type: string
              description: 错误描述信息
            type:
              type: string
              description: 错误类型
    VideoTaskInfo:
      type: object
      properties:
        can_cancel:
          type: boolean
          description: 任务是否可以取消
          example: true
        estimated_time:
          type: integer
          description: 预估完成时间（秒）
          minimum: 0
          example: 120
    Usage:
      type: object
      description: 使用量和计费信息
      properties:
        billing_rule:
          type: string
          description: 计费规则
          enum:
            - per_call
            - per_token
            - per_second
          example: per_call
        credits_reserved:
          type: number
          description: 预估消耗积分数
          minimum: 0
          example: 5
        user_group:
          type: string
          description: 用户组类别
          enum:
            - default
            - vip
          example: default
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |-
        ##所有接口均需要使用Bearer Token进行认证##

        **获取 API Key ：**

        访问 [API Key 管理页面](https://evolink.ai/dashboard/keys) 获取您的 API Key

        **使用时在请求头中添加：**
        ```
        Authorization: Bearer YOUR_API_KEY
        ```

````