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

# Wan 参考生视频

> 提交一个异步 Ali `wan2.7-r2v` 视频生成任务。

该能力使用顶层 `media` 数组作为公开多模态输入。当前支持的 `media.type` 包括 `reference_image`、`reference_video` 和 `first_frame`。

当前公开规则：
- `prompt` 为必填；
- 至少提供一个 `reference_image` 或 `reference_video`；
- `reference_image` 与 `reference_video` 合计最多 5 个；
- `first_frame` 为可选，最多 1 个；
- `size` 仅支持 `720P` 和 `1080P`；
- `ratio` 仅支持 `16:9`、`9:16`、`1:1`、`4:3`、`3:4`；
- `seconds` 仅接受 `2` 到 `15` 的整数字符串；若包含任意 `reference_video`，则允许范围收窄为 `2` 到 `10`。

当提供多个参考素材时，请在提示词中按提交顺序引用：图片参考写作 `图1`、`图2`，视频参考写作 `视频1`、`视频2`，图像和视频分别计数。



## OpenAPI

````yaml api-reference/zh-Hans/zmodelVideo/ali/reference-to-video.json POST /v1/videos
openapi: 3.0.1
info:
  title: Wan 参考生视频
  version: 1.0.0
  description: Ali `wan2.7-r2v` 的客户公开能力文档，统一入口为 `/v1/videos`。
  license:
    name: Project License
    url: https://github.com/QuantumNous/new-api/blob/main/LICENSE
servers:
  - url: https://api.powertokens.ai
    description: Baze API 服务地址
security: []
tags:
  - name: Wan 2.7 视频
    description: Ali wan2.7-r2v 参考生视频能力
paths:
  /v1/videos:
    post:
      tags:
        - Wan 2.7 视频
      summary: 创建 wan2.7-r2v 参考生视频任务
      description: >-
        提交一个异步 Ali `wan2.7-r2v` 视频生成任务。


        该能力使用顶层 `media` 数组作为公开多模态输入。当前支持的 `media.type` 包括
        `reference_image`、`reference_video` 和 `first_frame`。


        当前公开规则：

        - `prompt` 为必填；

        - 至少提供一个 `reference_image` 或 `reference_video`；

        - `reference_image` 与 `reference_video` 合计最多 5 个；

        - `first_frame` 为可选，最多 1 个；

        - `size` 仅支持 `720P` 和 `1080P`；

        - `ratio` 仅支持 `16:9`、`9:16`、`1:1`、`4:3`、`3:4`；

        - `seconds` 仅接受 `2` 到 `15` 的整数字符串；若包含任意 `reference_video`，则允许范围收窄为 `2` 到
        `10`。


        当提供多个参考素材时，请在提示词中按提交顺序引用：图片参考写作 `图1`、`图2`，视频参考写作 `视频1`、`视频2`，图像和视频分别计数。
      operationId: aliReferenceToVideoCreate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReferenceToVideoRequest'
            examples:
              reference_to_video:
                summary: 单图参考
                value:
                  model: wan2.7-r2v
                  prompt: 图1朝镜头走来，轻松挥手并微笑。
                  media:
                    - type: reference_image
                      url: https://example.com/assets/subject-reference.png
                  seconds: '5'
                  size: 1080P
                  ratio: '16:9'
                  prompt_extend: true
                  watermark: false
              reference_to_video_multimodal:
                summary: 图像、视频、音色与首帧混合参考
                value:
                  model: wan2.7-r2v
                  prompt: 视频1坐在桌边开始说话。图1从画面左侧走入，首帧用于固定开场构图。
                  negative_prompt: 模糊、手部畸形、低质量
                  prompt_extend: false
                  watermark: true
                  seed: 42
                  media:
                    - type: reference_image
                      url: https://example.com/assets/character-a.png
                      reference_voice: https://example.com/assets/character-a-voice.mp3
                    - type: reference_video
                      url: https://example.com/assets/character-b.mp4
                    - type: first_frame
                      url: https://example.com/assets/opening-frame.png
                  seconds: '8'
                  size: 720P
                  ratio: '9:16'
      responses:
        '200':
          description: 提交成功，返回统一的 OpenAI 风格视频任务对象。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoTaskResponse'
        '400':
          description: >-
            请求参数不合法，例如缺少参考素材、`media.type` 不支持、`size` / `ratio` / `seconds`
            非法，或字段组合冲突。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_request:
                  summary: 参数错误
                  value:
                    code: invalid_request
                    message: >-
                      wan2.7-r2v requires at least one reference_image or
                      reference_video
                    data: null
        '401':
          description: 鉴权失败，例如未提供令牌或令牌无效。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  summary: 未授权
                  value:
                    code: access_denied
                    message: 无效的令牌
                    data: null
        '413':
          description: 请求体过大。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                request_too_large:
                  summary: 请求体过大
                  value:
                    code: read_request_body_failed
                    message: 请求体过大，请缩小输入后重试
                    data: null
        '429':
          description: 触发速率限制或账户额度不足。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                quota_exceeded:
                  summary: 额度不足或速率受限
                  value:
                    code: insufficient_user_quota
                    message: 当前账户额度不足，请稍后重试
                    data: null
        '500':
          description: 服务端处理请求时发生内部错误。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal_error:
                  summary: 内部处理失败
                  value:
                    code: gen_relay_info_failed
                    message: 服务内部处理失败，请稍后重试
                    data: null
        '502':
          description: 上游服务返回异常响应。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                bad_gateway:
                  summary: 上游响应异常
                  value:
                    code: bad_response_status_code
                    message: 上游服务返回了无效响应
                    data: null
        '503':
          description: 上游服务暂不可用，或当前模型暂无可用渠道。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                service_unavailable:
                  summary: 服务暂不可用
                  value:
                    code: get_channel_failed
                    message: 当前模型暂时无可用渠道，请稍后重试
                    data: null
      security:
        - BearerAuth: []
components:
  schemas:
    ReferenceToVideoRequest:
      type: object
      required:
        - model
        - prompt
        - media
      properties:
        model:
          type: string
          enum:
            - wan2.7-r2v
          description: 模型名称。可选值：`wan2.7-r2v`。
        prompt:
          type: string
          description: >-
            文本提示词。用来描述生成视频中期望包含的元素和视觉特点。


            支持中英文，每个汉字、字母、标点占一个字符，超过部分会自动截断。


            `wan2.7-r2v`：不超过5000个字符。


            **参考指代：**

            当为中文提示词时，参考图片时通过"图1、图2"这类标识指代，参考视频时通过"视频1、视频2"这类标识指代。英文提示词则写为"Image
            1"、"Video 1"这类标识。英文字母和数字之间有空格，首字母大写。顺序与 media
            数组顺序一致。图和视频分别计数，即同时存在图1、视频1等标识。若参考素材有且仅有一张图片或一个视频，则可简化表述为"参考图片"或"参考视频"。


            **画面描述：**

            假设参考图1是一只猫，图2是一个房间，要描述猫在房间里玩耍，支持两种写法：一种是直接使用标识指代（如"图1在图2里玩耍"）；另一种是结合主体与场景补充说明（如"图1的猫在图2的房间里玩耍"）。


            **多宫格（故事板图像）：**

            当参考图片为多宫格（故事板图像）时，提示词建议按照多分镜的形式描述画面内容。无需描述每个宫格，提供关键分镜内容即可，模型将自动识别宫格逻辑并智能补全镜头内容。为达到更好的效果，建议单次仅输入一张多宫格图。
        size:
          type: string
          enum:
            - 720P
            - 1080P
          description: |-
            **重要**
            `size` 直接影响费用，请在调用前确认模型价格。

            生成视频的分辨率档位，用于控制视频的清晰度（总像素）。

            `wan2.7-r2v`：可选值：`720P`、`1080P`。默认值为 `1080P`。
          default: 1080P
        seconds:
          type: string
          description: |-
            **重要**
            `seconds` 直接影响费用，请在调用前确认模型价格。

            生成视频的时长，单位为秒。

            `wan2.7-r2v`：默认值为 `5`。
            - 当参考素材中包含视频时：取值为 [2, 10] 之间的整数。
            - 当参考素材中不包含视频时：取值为 [2, 15] 之间的整数。
          default: '5'
          enum:
            - '2'
            - '3'
            - '4'
            - '5'
            - '6'
            - '7'
            - '8'
            - '9'
            - '10'
            - '11'
            - '12'
            - '13'
            - '14'
            - '15'
        ratio:
          type: string
          enum:
            - '16:9'
            - '9:16'
            - '1:1'
            - '4:3'
            - '3:4'
          description: |-
            生成视频的宽高比。

            **生效逻辑：**
            - 未传入首帧图像：按指定的 `ratio` 参数生成视频。
            - 已传入首帧图像：自动忽略 `ratio` 参数，以首帧图像的宽高比生成近似比例的视频。

            可选值为：
            - `16:9`（默认值）
            - `9:16`
            - `1:1`
            - `4:3`
            - `3:4`

            不同宽高比对应的输出视频分辨率（宽高像素值）：

            **720P：**
            - `16:9` → 1280×720
            - `9:16` → 720×1280
            - `1:1` → 960×960
            - `4:3` → 1104×832
            - `3:4` → 832×1104

            **1080P：**
            - `16:9` → 1920×1080
            - `9:16` → 1080×1920
            - `1:1` → 1440×1440
            - `4:3` → 1648×1248
            - `3:4` → 1248×1648
          default: '16:9'
        negative_prompt:
          type: string
          description: |-
            反向提示词，用来描述不希望在视频画面中出现的内容，可以对视频画面进行限制。

            支持中英文，长度不超过500个字符，超过部分会自动截断。

            示例值：低分辨率、错误、最差质量、低质量、残缺、多余的手指、比例不良等。
        prompt_extend:
          type: boolean
          description: >-
            是否开启 prompt 智能改写。开启后使用大模型对输入 prompt 进行智能改写。对于较短的 prompt
            生成效果提升明显，但会增加耗时。

            - `true`：默认值，开启智能改写。

            - `false`：不开启智能改写。
        watermark:
          type: boolean
          description: |-
            是否添加水印标识，水印位于视频右下角，文案固定为 "AI生成"。
            - `false`：默认值，不添加水印。
            - `true`：添加水印。
          default: false
        seed:
          type: integer
          minimum: 0
          maximum: 2147483647
          description: |-
            随机数种子，取值范围为 [0, 2147483647]。

            未指定时，系统自动生成随机种子。若需提升生成结果的可复现性，建议固定 seed 值。
            请注意，由于模型生成具有概率性，即使使用相同 seed，也不能保证每次生成结果完全一致。
        media:
          type: array
          description: |-
            媒体素材数组，素材包括图像、视频和音频。支持图像/视频输入作为视觉参考，图像支持多视图，常见参考角色、道具、场景等。

            数组中每个元素为一个媒体对象，包含 `type` 与 `url` 字段。

            按照数组顺序定义 prompt 中角色引用的顺序。图和视频分别计数，即可同时存在图1、视频1。
            - 数组中的第 1 个 `reference_video` 对应 视频1，第 2 个对应 视频2，以此类推。
            - 数组中的第 1 个 `reference_image` 对应 图1，第 2 个对应 图2，以此类推。
          items:
            $ref: '#/components/schemas/ReferenceToVideoMediaInput'
    VideoTaskResponse:
      type: object
      properties:
        id:
          type: string
          description: 公开任务 ID。
        task_id:
          type: string
          description: 公开任务 ID 别名。
        object:
          type: string
          example: video
        model:
          type: string
          description: 模型名称。
        status:
          type: string
          enum:
            - queued
            - in_progress
            - completed
            - failed
            - unknown
          description: 统一视频任务状态。
        progress:
          type: integer
          description: 任务进度百分比。
        created_at:
          type: integer
          format: int64
          description: 秒级 Unix 时间戳。
    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: 错误代码。
          example: invalid_request
        message:
          type: string
          description: 错误说明。
        data:
          nullable: true
          description: 附加错误数据。当前通常为 null。
    ReferenceToVideoMediaInput:
      type: object
      required:
        - type
        - url
      properties:
        type:
          type: string
          enum:
            - reference_image
            - reference_video
            - first_frame
          description: |-
            type string （必选）

            媒体素材类型。可选值为：

            reference_image：参考图像。提供主体角色（人物/动物/物体）和场景参考。

            reference_video：参考视频。提供主体角色（人物/动物/物体）和音色参考，不推荐传入空镜视频。

            first_frame：首帧图像。基于首帧生成视频，通常包含主体角色（人物/动物/物体）。支持同时传入首帧图联合控制，常见用法如下：

            首帧中已经出现待参考主体：此时可以搭配主体参考强化一致性，或进行音色参考。

            首帧中未出现待参考主体：此时可以用主体参考来定义视频动态过程中新出现的主体特征。

            素材限制：

            首帧图像，最多传入1张。

            参考图像和参考视频至少传入1个，参考图像 + 参考视频 ≤ 5。

            参考素材为主体角色时，仅包含单一角色。
        url:
          type: string
          description: >-
            媒体素材 URL。每个值可指向一张图像或一段视频。


            **传入参考图像（`type=reference_image`）：**

            参考图像 URL 或 Base64 编码数据。参考图可以是主体（人物/动物/物体）或者背景。当包含主体时，仅包含一个角色。


            图像限制：

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

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

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

            - 文件大小：不超过20MB。


            支持输入的格式：

            - 公网 URL：支持HTTP或HTTPS协议。示例值：`https://xxx/xxx.png`。

            - 临时 URL（OSS）：支持OSS协议，必须通过上传文件获取临时
            URL。示例值：`oss://dashscope-instant/xxx/xxx.png`。

            - Base64
            编码图像后的字符串：`data:{MIME_type};base64,{base64_data}`。示例值：`data:image/png;base64,GDU7MtCZzEbTbmRZ......`。


            **传入参考视频（`type=reference_video`）：**

            参考视频
            URL。视频内容建议包含主体（人物/动物/物体），不建议使用背景或空镜视频。当包含主体时，仅包含一个角色。若视频有声音，也可以参考音色。


            视频限制：

            - 格式：mp4、mov。

            - 时长：1～30s。

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

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

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


            支持输入的格式：

            - 公网 URL：支持HTTP和HTTPS协议。示例值：`https://xxx/xxx.mp4`。

            - 临时 URL（OSS）：支持OSS协议，必须通过上传文件获取临时
            URL。示例值：`oss://dashscope-instant/xxx/xxx.mp4`。
        reference_voice:
          type: string
          description: >-
            音频 URL。用于指定参考素材（图像/视频）中主体角色的音色。与 `reference_image` 或
            `reference_video` 搭配使用。该音频仅参考音色，与说话内容无关。建议参考音频语种与提示词语种保持一致，匹配效果更佳。


            **音频生效逻辑：**

            - 默认行为：若 `reference_video` 本身包含音频，但未指定 `reference_voice`，默认使用视频原声。

            - 优先级：若同时传入 `reference_video`（含音频）和 `reference_voice`，则优先使用
            `reference_voice` 的音色，覆盖视频原声。


            音频限制：

            - 格式：wav、mp3。

            - 时长：1～10s。

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


            支持输入的格式：

            - 公网 URL：支持HTTP和HTTPS协议。示例值：`https://xxx/xxx.mp3`。

            - 临时 URL（OSS）：支持OSS协议，必须通过上传文件获取临时
            URL。示例值：`oss://dashscope-instant/xxx/xxx.mp3`。
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: '在请求头中传入 `Authorization: Bearer <token>`。'

````