Vidu 统一视频格式

使用 /v1/videos 接入 Vidu Q2、Q3，设置 images、seconds、size 与 metadata.vidu_operation，并查询统一结果。

统一格式通过 POST /v1/videos 创建任务，也支持 POST /v1/video/generations。请求使用 JSON 和 ModelSell Bearer API Key，模型权限及可用操作见接口概览。

Q3 图生视频

curl --max-time 300 "$MODELSELL_BASE_URL/v1/videos" \
  -H "Authorization: Bearer $MODELSELL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "viduq3-turbo",
    "prompt": "镜头缓慢拉远，参考图中的人物向镜头挥手",
    "images": ["https://example.com/first-frame.png"],
    "seconds": "5",
    "size": "720p",
    "metadata": {
      "vidu_operation": "img2video",
      "audio": false,
      "is_rec": false,
      "watermark": false,
      "seed": 0
    }
  }'

先按地址与鉴权设置环境变量，并替换图片 URL。统一创建响应中的公共任务 ID 为 id：

{
  "id": "task_example_vidu",
  "object": "video",
  "model": "viduq3-turbo",
  "status": "queued"
}

公共参数映射

统一字段	Vidu 上游字段	说明
`model`	`model`	使用已授权的模型名
`prompt`	`prompt`	视频描述；参考生需提供提示词
`images`	`images`	图片 URL / data URI 数组；首尾帧保持顺序
`seconds`	`duration`	示例使用字符串 `"5"`，上游转换为整数秒
`size`	`resolution`	例如 `720p`；使用所选模型支持的档位
`metadata` 中的指定字段	对应顶层字段	见下文

原生请求的 duration 是整数，统一示例的 seconds 是字符串；不要混用响应格式或将 1920x1080 当作这里的分辨率档位。

显式选择操作

通过 metadata.vidu_operation 指定操作：

值	图片输入	模型要求
`text2video`	无	模型支持文生视频
`img2video`	一张首帧	模型支持图生视频
`start-end2video`	首帧、尾帧两张	模型支持首尾帧视频
`reference2video`	参考图	模型及渠道支持参考生视频

省略操作时，系统通常按图片数量选择：一张图走图生，两张图走首尾帧，多张图走参考生；Q4 多图走参考生。自动选择不会使模型获得额外能力。建议显式设置，尤其是 viduq2 单张参考图、两张图片作为参考等场景。

Q2 单张参考图

该模型支持参考生，需显式选择 reference2video：

{
  "model": "viduq2",
  "prompt": "保持参考图中茶壶的造型，生成温暖晨光中的产品短片",
  "images": ["https://example.com/teapot.png"],
  "seconds": "5",
  "size": "720p",
  "metadata": {
    "vidu_operation": "reference2video",
    "aspect_ratio": "16:9",
    "audio": false,
    "watermark": false
  }
}

文生视频去掉 images、选择支持文生的模型并设置 text2video；首尾帧使用两张图片并设置 start-end2video。Q4 示例仅在模型及渠道开放后适用，不能通过更改操作名绕过其模型能力限制。

Vidu 扩展参数

统一格式从 metadata 映射下列字段：

resolution、aspect_ratio、audio、is_rec、seed、off_peak、watermark、wm_position、wm_url、payload、meta_data、callback_url、sounds、subjects、auto_subjects。

vidu_operation 用于选择路径；省略 size 时，也可通过 metadata.resolution 指定分辨率。false、0 保留原本含义；meta_data 仍需为 JSON 字符串。参数的类型、范围及可用性见请求参数。当前不要传 off_peak: true；Q3 使用 is_rec: false。

metadata 不会任意透传所有供应商字段。需要 Q2 的 bgm、movement_amplitude、voice_id 或后续新增原生字段时，使用 /ent/v2/... 原生格式，并确认该模型和渠道支持。

查询统一结果

使用创建响应的真实 id：

export TASK_ID="<returned-task-id>"
curl --max-time 300 "$MODELSELL_BASE_URL/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer $MODELSELL_API_KEY"

统一 status 为 queued、in_progress、completed 或 failed。成功时从 video_url 或 metadata.url 读取视频地址，封面见 metadata.cover_url，完整生成物见 metadata.creations：

{
  "id": "task_example_vidu",
  "object": "video",
  "model": "viduq3-turbo",
  "status": "completed",
  "progress": 100,
  "video_url": "https://example.com/generated-video.mp4",
  "metadata": {
    "url": "https://example.com/generated-video.mp4",
    "cover_url": "https://example.com/cover.jpg",
    "credits": 35
  }
}

积分仅展示计量信息，示例数值不表示固定价格。与原生查询一样，统一查询不重复收取生成费用，结果地址应在有效期内下载。失败时读取错误信息并保留公共 ID；不要因等待时间较长而重复创建同一任务。