Vidu 视频生成 API​

POST https://api.yu-yu.ai/v1/videos

本页说明 Vidu 家族（Q4 / Q3 / Q2 / Q1 / 2.0）在本网关的对外调用方式。接口是异步的：提交任务后立即拿到任务 ID，再用任务 ID 轮询状态，成功后取回视频。

本网关同时提供两条等价入口：

两条入口共用同一套模型能力与参数校验；任务 ID 也是同一套，用哪条入口创建、用另一条入口查询都可以。下文先讲 OpenAI 兼容入口，Vidu 原生入口的差异集中在Vidu 原生协议入口。

模型能力​

Vidu 家族共 15 个对外模型名。所有模型共用同一套请求字段，差别只在 model 取值，以及下表列出的可用输入组合、输出档位与时长范围。

音视频直出​

Q4 / Q3 / Q2 系列支持 audio=true（成片直接带配音）。viduq1 / viduq1-classic / vidu2.0 传 audio=true 会被拒绝。

错峰生成​

off_peak=true 表示允许把任务排到低峰时段执行，可用条件随模型不同：

鉴权​

本接口仅支持 API Key 鉴权，请在 https://api.yu-yu.ai/console 获取 API Key：

Authorization: Bearer <API_KEY>
Content-Type: application/json

提交任务​

POST https://api.yu-yu.ai/v1/videos

同一入口还有一条别名：POST https://api.yu-yu.ai/v1/video/generations，行为完全一致。

Body 参数​

model string 必选

需要调用的模型名，取值见上文的模型能力。不在清单内的模型名返回 400 unsupported_vidu_model。

prompt string 必选

画面描述，不能为空。按字符计长度，上限随动作不同：文生视频（Q3 系列）20000 字符，参考生视频 5000 字符，其余场景 2000 字符。

images string[] 可选

输入图片列表，决定本次请求走哪种生成场景（见下文输入组合与动作）。每张图片可以是公网 http(s) URL，也可以是 data:image/<类型>;base64,<数据> 内联形式。

image string 可选

单张图片的简写，仅在 images 为空时生效，等价于只传一张图。

duration integer 可选

生成时长，单位秒，只接受整数。取值必须在模型的时长区间内；vidu2.0 只接受 4 或 8。不传时默认 5 秒，模型不接受 5 秒时取该模型的时长下限。

seconds string 可选

时长的字符串写法，如 "8"，仅在 duration 缺省时生效。

size string 可选

输出档位，与 metadata.resolution 等价，两者同时给出时以 metadata.resolution 为准。大小写不敏感，也接受 1280x720 这类 WxH 写法（按像素面积折算到该模型允许的最近档位）。两者都不传时默认 720p；该模型没有 720p 档时取它档位表中的第一个（因此 viduq1 / viduq1-classic 缺省 1080p）。

metadata object | string 可选

模型专用参数。对象或 JSON 字符串都接受。只接受下表中的键，未知键返回 400（不会静默丢弃）：

三类特殊键：

• callback_url：任务终态回调地址，放在顶层或 metadata 下都会被识别，由网关在任务结束后回调，不会转发给模型服务方。
• prompt / model：写在 metadata 下会被忽略，以顶层字段为准。
• sounds / videos / subjects / auto_subjects / voice_id：本期未开放，传入返回 400。

callback_url string 可选

任务进入终态后由网关 POST 回调的地址（也可写在 metadata.callback_url）。回调前会做可达性校验，指向内网或非法协议的地址返回 400 invalid_callback_url。

输入组合与动作​

请求实际走哪种生成场景，由输入图片张数与模型能力共同决定；也可以用 metadata.action 显式指定。

图片要求​

请求示例​

文生视频：

curl -X POST 'https://api.yu-yu.ai/v1/videos' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "viduq3-pro",
    "prompt": "一只橘猫坐在窗边打哈欠，清晨自然光，镜头缓慢推进",
    "duration": 5,
    "size": "720p",
    "metadata": { "aspect_ratio": "16:9", "seed": 12345 }
  }'

图生视频（首帧）：

curl -X POST 'https://api.yu-yu.ai/v1/videos' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "viduq2-pro",
    "prompt": "镜头缓慢环绕，发丝随风摆动",
    "image": "https://your-cdn.example.com/first-frame.png",
    "duration": 5,
    "metadata": { "resolution": "1080p", "movement_amplitude": "small" }
  }'

首尾帧生视频：

{
  "model": "viduq1",
  "prompt": "人物从静止到转身离开，镜头固定",
  "images": [
    "https://your-cdn.example.com/first.png",
    "https://your-cdn.example.com/last.png"
  ]
}

参考生视频（显式指定动作与音视频直出）：

{
  "model": "viduq4-preview",
  "prompt": "三位角色依次登场，保持各自的服装与发型",
  "images": [
    "https://your-cdn.example.com/ref-1.png",
    "https://your-cdn.example.com/ref-2.png",
    "https://your-cdn.example.com/ref-3.png"
  ],
  "duration": 8,
  "metadata": {
    "action": "referenceGenerate",
    "resolution": "1080p",
    "audio": true
  }
}

提交响应​

提交成功后立即返回任务对象，此时视频还没生成：

{
  "id": "task_xxxxxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "viduq3-pro",
  "status": "queued",
  "progress": 0,
  "created_at": 1767225600,
  "upstream_task_id": ""
}

查询任务​

GET https://api.yu-yu.ai/v1/videos/{task_id}

旧入口的兼容别名是 GET https://api.yu-yu.ai/v1/video/generations/{task_id}：它返回网关通用任务体 {"code":"success","data":{...}}，字段与本页描述的视频对象不同；要下面这套字段请用 /v1/videos/{task_id}。

Path 参数​

task_id string 必选

提交任务时返回的任务 ID。

响应参数​

{
  "id": "task_xxxxxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "viduq3-pro",
  "status": "completed",
  "progress": 100,
  "created_at": 1767225600,
  "completed_at": 1767225720,
  "upstream_task_id": "",
  "metadata": {
    "url": "https://your-cdn.example.com/result.mp4",
    "cover_url": "https://your-cdn.example.com/result-cover.jpg",
    "watermarked_url": "https://your-cdn.example.com/result-watermark.mp4"
  }
}

状态取值​

取回视频文件​

GET https://api.yu-yu.ai/v1/videos/{task_id}/content 返回视频二进制流（不是 JSON），响应头带内容类型，适合直接交给播放器或下载：

curl -L 'https://api.yu-yu.ai/v1/videos/task_xxxxxxxxxxxxxxxx/content' \
  -H 'Authorization: Bearer <API_KEY>' \
  -o result.mp4

任务未完成时该端点不会返回半成品，会按任务状态报错；也可以直接用查询结果里的 metadata.url。

轮询建议​

• 首次查询延迟 5 秒以上，之后每隔 5 秒查询一次；命中 completed / failed / cancelled 立即停止。
• 1080p 以上档位、较长时长的任务耗时更久，请放宽轮询上限；也可以提交时传入 callback_url，由网关在终态回调。
• 查询返回 5xx 属于网关或模型服务方临时故障，重试 2~3 次即可，不要无限重试。

常见错误​

错误响应分两种形状，取决于失败发生在哪一步。

请求本身失败（提交或查询返回 HTTP 4xx / 5xx）：

{
  "code": "invalid_duration",
  "message": "viduq2 的时长必须在 1–10 秒之间（收到 12）",
  "data": null
}

任务失败（查询返回 HTTP 200、status 为 failed）——错误信息在 error 对象里：

{
  "id": "task_xxxxxxxxxxxxxxxx",
  "status": "failed",
  "error": {
    "code": "content_policy_violation",
    "message": "输入未通过内容审核"
  }
}

两种形状的 code 命名规则一致，但可出现的取值不同：

Vidu 原生协议入口​

原生入口的路径与上游逐字一致，只需要把 base URL 换成 https://api.yu-yu.ai。请求体沿用上游字段，但只支持下面列出的白名单；白名单外的键与未开放能力会在提交校验阶段失败，见本节末尾的说明。

原生入口固定使用 Vidu 渠道。同一模型名如果还配置在其它渠道上，原生入口不会选到那些渠道；请确认要承接 /ent/v2/* 的模型挂在 Vidu 渠道下。

鉴权​

原生入口同时接受上游写法与网关写法：

Authorization: Token <API_KEY>

Authorization: Bearer <API_KEY>

请求体​

原生请求体按上游字段原样提交，支持的键：

model、prompt、images、duration、resolution、aspect_ratio、seed、audio、off_peak、watermark、wm_position、wm_url、meta_data、payload、is_rec、movement_amplitude、bgm、callback_url。

{
  "model": "viduq3-turbo",
  "images": ["https://example.com/first.jpg"],
  "prompt": "镜头缓慢推进，清晨自然光",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "seed": 0,
  "audio": false,
  "off_peak": false,
  "watermark": false
}

提交响应​

{
  "task_id": "cgt-20261022160000-abcde",
  "state": "created",
  "model": "viduq3-turbo"
}

这里的 task_id 是本网关的任务 ID，直接拿去 /ent/v2/tasks/{task_id}/creations 查询即可。提交阶段还没有调用上游，因此只回 state=created，不回 credits 等上游回显字段。

查询响应​

{
  "id": "cgt-20261022160000-abcde",
  "state": "success",
  "credits": 62.5,
  "off_peak": false,
  "bgm": false,
  "creations": [
    {
      "id": "creation-1",
      "url": "https://cdn.example.com/video.mp4",
      "cover_url": "https://cdn.example.com/cover.jpg",
      "watermarked_url": "https://cdn.example.com/video-wm.mp4"
    }
  ]
}

state 的取值与上游一致：

failed 时 err_code 优先回上游原始错误码（如 TaskPromptPolicyViolation）；本地判死、上游没给码时回网关错误码（如 empty_creation）。message 是可读文案，可直接展示给用户。

错误响应​

鉴权、限流、分发等早于任务的失败，以及查询/取消失败，都使用上游同形的错误信封：

{
  "code": 400,
  "reason": "invalid_duration",
  "message": "vidu2.0 只接受 4 或 8 秒（收到 5）",
  "metadata": { "trace_id": "" }
}

reason 按 Vidu 的错误码命名（Unauthorized、CreditInsufficient、QuotaExceeded、TooManyRequests、TaskNotFound、BadRequest、TaskPromptPolicyViolation、UserCancelled …）。网关内部独有的错误码（如 invalid_duration）会原样出现在 reason 里，而不是被编造成上游码。

取消​

POST https://api.yu-yu.ai/ent/v2/tasks/{task_id}/cancel 已注册，但本网关暂未接上游取消能力：任务存在时返回 501 + reason=cancel_not_supported，任务不存在时返回 404 + reason=TaskNotFound。任务会继续执行到终态并正常结算，如需提前终止请联系管理员。

常见问题​

• 提交返回 unsupported_vidu_model：model 必须是本页清单里的名字，其它写法（含自定义别名）都会被拒绝。
• 只想文生视频却收到 400：viduq4-preview、viduq3-pro-fast、viduq3-mix、viduq3-drama、viduq3-ad、viduq3、viduq2-pro、viduq2-turbo、viduq2-pro-fast、viduq1-classic、vidu2.0 都不支持纯文本输入，至少要给一张图。
• vidu2.0 传 5 秒报错：该模型只接受 4 或 8 秒。
• 参考图较多时报错：除 viduq4-preview（15 张）外，参考生视频最多 7 张。
• 查询一直 in_progress：模型正在生成或任务在排队；错峰任务排队时间可能明显更长。
• 结果地址打不开：metadata.url 有有效期，请及时下载；也可以调用 GET /v1/videos/{task_id}/content 由网关转发。

在线调试​