API 协议

Vidu Q3 Turbo:参数、场景与调用指南

预览指南

粘贴给 AI,帮助理解文档并完成接入。 仅包含文档与示例,不包含真实密钥。

预览指南

Vidu Q3 Turbo:参数、场景与调用指南

直接答案本站入口为 JSON POST /v1/videos;使用本站 API Key,保存返回的 id,再以 GET /v1/videos/{id} 查询到 completed 或 failed。官方直连的 task_id、state 和鉴权格式不要混入本站请求。

更新 · 审核信息

模型定位与适用场景

Vidu Q3 Turbo 支持文生视频、图生视频、首尾帧、图片参考。以下覆盖官方创建参数、模式限制及本站字段映射;标注“未开放”的参数仅供了解官方能力,不加入本站可执行示例。

本指南核对本站请求契约,不代表所有场景均已完成收费出片验收。使用模型广场显示的精确模型、分组和有效端点;示例中的 example.com 素材与占位任务 ID 必须替换。先以最小请求确认可用,再逐项添加参考素材和高级参数。价格以模型广场及实际账单为准。

型号与入口

viduq3-turbo

POST /v1/videos

参考素材格式

素材字段传输格式文件准备与限制
图片images公开 URL 或 data:image/<真实格式>;base64,...;JSON 数组,不能填本地路径。PNG/JPEG/JPG/WebP;整个请求体小于 20 MB(Base64 会增大体积)。官方单张图片上限 50 MB;Q3 参考图至少 128×128;数量限制见 images。Q3 页面画幅边界的表述有歧义,建议选择 1:4–4:1 范围内素材。

参数与组合限制

  • 本站入口为 JSON POST /v1/videos;使用本站 API Key,保存返回的 id,再以 GET /v1/videos/{id} 查询到 completed 或 failed。官方直连的 task_id、state 和鉴权格式不要混入本站请求。
  • 官方参数于 2026-11-17 按型号及模式核对;本站示例仅含已实现转发的参数,新增控制尚未通过真实出片验收。本站非 Mix 省略参数时为 5 秒、1080p,与部分官方默认值不同。 metadata.duration/resolution 会覆盖顶层参数;meta_data 是另一个官方字段。
  • 官方创建响应包含 task_id、state;查询返回 err_code、payload、creations[].id/url/cover_url/watermarked_url 等。本站统一查询主要返回 status、video_url、metadata.url,不保证透传所有官方字段。官方生成物 URL 通常 24 小时有效,完成后及时下载;下载外部 URL 时不携带本站 Key。
  • 官方部分参数表有相互矛盾的类型或默认值:已在相关行注明,不将文档歧义当作本站能力。尚未开放的字段可能被忽略或拒绝,不能通过塞进 metadata 来启用。本文不声称所有场景已经收费出片验收。
字段类型用法与限制
Authorizationheader string必填。本站使用 Bearer <本站 API Key>,Content-Type: application/json。官方直连文档使用 Token <Vidu Key>,不要把两种凭证或鉴权格式混用。
modelstring必填,固定为 viduq3-turbo。
metadata.actionstring本站模式选择:文生视频=textGenerate;图生视频=generate;首尾帧=firstTailGenerate;图片参考=referenceGenerate。建议始终显式填写,Turbo 参考模式单独计价。这是本站字段;官方使用不同创建端点选择模式。
promptstring描述内容、动作、镜头和声音。官方文生及参考模式必填,图生/首尾帧可选;本站要求非空 prompt,图生且显式 is_rec=true 时可省略。最多 20000 字符;Turbo 图片参考模式最多 5000,主体引用模式为 20000。官方图生 is_rec=true 时会改用推荐提示词;本站图生支持该开关。
imagesstring[]图片模式必填,本站传数组:图生 1 张;首尾帧 2 张,顺序为首帧、尾帧;图片参考 1–7 张;文生不传图片;支持公开 URL 或带 MIME 前缀的 Base64 data URI,PNG/JPEG/JPG/WebP。首尾帧分辨率比为 0.8–1.25;官方页面“string/1 张”与其双帧说明不一致,本站按双图数组发送。
durationinteger官方 1–16 秒,默认 5 秒;图片参考限定 3–15 秒,主体引用文档标注 3–16 秒(本站未开放主体引用)。本站使用顶层 duration,省略时默认 5 秒;metadata.duration 优先覆盖。也接受 seconds 别名;建议使用 duration。
resolutionstring官方 540p/720p/1080p,默认 720p。本站按 metadata.resolution > resolution > size 优先选择,省略时默认 1080p。
seedinteger可选;官方省略或 0 都表示随机,非零值指定种子,文档未给出数值上下界。本站传 顶层 seed 或 metadata.seed,metadata 优先;显式 0 保留。相同种子不保证完全一致的输出。
payloadstring可选透传文本,最多 1048576 字符,不是对象。本站传 payload 或 metadata.payload(metadata 优先)。官方任务/回调可返回该文本;本站统一查询不保证展示所有官方透传字段。
callback_urlstring可选状态通知地址,本站传 callback_url 或 metadata.callback_url(metadata 优先)。Vidu 以 POST 通知 processing/success/failed,成功或失败通知发送失败会重试三次;回调体沿用官方任务查询结构,验签见官方回调签名文档。回调中的官方任务 ID 不等于本站 id;本站仍用 GET /v1/videos/{id} 查询。
aspect_ratiostring官方文生/参考模式的画幅;1:1/16:9/9:16/3:4/4:3/auto(仅参考模式)。默认 16:9。参考模式的 auto 按素材推荐画幅。图生/首尾帧创建表没有此开关,画幅由输入图决定。本站文生/参考模式可传顶层 aspect_ratio 或 metadata.aspect_ratio,默认 16:9。
audioboolean官方可选,默认 true;false 输出静音。文生/图生/首尾帧和主体引用提供此开关,图片参考创建表没有 audio。主体 voice_id 仅在 audio=true 时生效。
is_recboolean仅官方图生模式,自动推荐/扩写提示词;Q3 默认 false,true 时改用推荐提示词而忽略用户 prompt。本站支持 true/false,显式 false 会保留;省略时沿用官方默认行为。
off_peakboolean官方默认 false(即时),true 为错峰,最长排队 48 小时,可取消,超时未完成会自动取消。实际适用价格以官方报价及本站分组为准;本站支持具备此能力的型号传 off_peak;折扣是否生效以本站实际配置价格为准,不会因发送该字段自动改价。
watermarkboolean可选水印开关。官方多处标注默认 true,但同页文字又写“默认不加”,存在冲突,不能承诺统一默认值。官方通过 watermarked_url 提供带水印结果;本站统一查询没有承诺返回此字段。
wm_positioninteger可选,默认 3;1 左上、2 右上、3 右下、4 左下,仅与水印输出一起使用。
wm_urlstring可选水印图片 URL;省略时官方使用内置“内容由AI生成”标记,依赖水印开关。
meta_datastring (JSON)可选,必须为 JSON 编码字符串;用于产出标识,不是本站 metadata 对象。官方示例键包括 Label、ContentProducer、ContentPropagator、ProduceID、PropagateID、ReservedCode1、ReservedCode2,亦可自定义;省略时使用官方生成标识。
auto_subjectsboolean仅官方主体引用模式,默认 false;true 开启智能主体库能力。 本站当前未开放此参数;不要放进本站请求示例。
subjectsobject[]官方主体引用模式必填,最多 7 个图片/文字主体;不要与普通 images 数组视作同一种模式。 本站当前未开放此参数;不要放进本站请求示例。
subjects[].namestring主体名称,必填;在 prompt 中用 [@name] 引用。 本站当前未开放此参数;不要放进本站请求示例。
subjects[].imagesstring[]临时主体图片,官方标为必填,每主体最多 3 张;URL 或带 MIME 的 Base64,PNG/JPEG/JPG/WebP,至少 128×128。使用 server_id 时如何搭配图片须按官方主体接口约定,不自行省略必填项。 本站当前未开放此参数;不要放进本站请求示例。
subjects[].voice_idstring可选主体音色 ID,省略时自动推荐;来自官方音色列表或声音复刻,audio=true 时才生效。 本站当前未开放此参数;不要放进本站请求示例。
subjects[].server_idstring可选已创建的主体 ID。省略时本次上传图片形成不保存的临时主体;不能填写本站视频任务 ID。 本站当前未开放此参数;不要放进本站请求示例。

场景与代码示例

文生视频:最小请求

适用型号:viduq3-turbo

POST /v1/videos

{
  "model": "viduq3-turbo",
  "prompt": "镜头缓慢推进,保持主体外观一致。",
  "duration": 1,
  "size": "540p",
  "metadata": {
    "action": "textGenerate"
  }
}

curl

curl --fail-with-body --silent --show-error --connect-timeout 10 --max-time 120 --request POST 'https://api.tu-zi.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "viduq3-turbo",
  "prompt": "镜头缓慢推进,保持主体外观一致。",
  "duration": 1,
  "size": "540p",
  "metadata": {
    "action": "textGenerate"
  }
}'

python

import json
import os
import requests

url = "https://api.tu-zi.com/v1/videos"
headers = json.loads("{\"Authorization\":\"Bearer YOUR_API_KEY\",\"Content-Type\":\"application/json\"}")
for name in ["API_KEY"]:
    if not os.environ.get(name, "").strip():
        raise RuntimeError("Set environment variable: " + name)
headers["Authorization"] = "Bearer " + os.environ["API_KEY"]
payload = json.loads("{\"model\":\"viduq3-turbo\",\"prompt\":\"镜头缓慢推进,保持主体外观一致。\",\"duration\":1,\"size\":\"540p\",\"metadata\":{\"action\":\"textGenerate\"}}")
response = requests.request("POST", url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
result = response.json()
if isinstance(result, dict) and (result.get("success") is False or result.get("code") is False or result.get("error")):
    raise RuntimeError(json.dumps(result, ensure_ascii=False))
print(json.dumps(result, ensure_ascii=False, indent=2))

javascript

// Node.js 20+
const url = "https://api.tu-zi.com/v1/videos";
const headers = {
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
};
for (const name of ["API_KEY"]) {
  if (!process.env[name]?.trim()) throw new Error("Set environment variable: " + name);
}
headers.Authorization = 'Bearer ' + process.env.API_KEY;
const response = await fetch(url, { method: "POST", headers, body: JSON.stringify({
  "model": "viduq3-turbo",
  "prompt": "镜头缓慢推进,保持主体外观一致。",
  "duration": 1,
  "size": "540p",
  "metadata": {
    "action": "textGenerate"
  }
}), signal: AbortSignal.timeout(120000) });
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
if (result?.success === false || result?.code === false || result?.error) throw new Error(JSON.stringify(result));
console.log(JSON.stringify(result, null, 2));

图生视频:最小请求

适用型号:viduq3-turbo

POST /v1/videos

{
  "model": "viduq3-turbo",
  "prompt": "镜头缓慢推进,保持主体外观一致。",
  "duration": 1,
  "size": "540p",
  "metadata": {
    "action": "generate"
  },
  "images": [
    "https://example.com/frame-1.png"
  ]
}

curl

curl --fail-with-body --silent --show-error --connect-timeout 10 --max-time 120 --request POST 'https://api.tu-zi.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "viduq3-turbo",
  "prompt": "镜头缓慢推进,保持主体外观一致。",
  "duration": 1,
  "size": "540p",
  "metadata": {
    "action": "generate"
  },
  "images": [
    "https://example.com/frame-1.png"
  ]
}'

python

import json
import os
import requests

url = "https://api.tu-zi.com/v1/videos"
headers = json.loads("{\"Authorization\":\"Bearer YOUR_API_KEY\",\"Content-Type\":\"application/json\"}")
for name in ["API_KEY"]:
    if not os.environ.get(name, "").strip():
        raise RuntimeError("Set environment variable: " + name)
headers["Authorization"] = "Bearer " + os.environ["API_KEY"]
payload = json.loads("{\"model\":\"viduq3-turbo\",\"prompt\":\"镜头缓慢推进,保持主体外观一致。\",\"duration\":1,\"size\":\"540p\",\"metadata\":{\"action\":\"generate\"},\"images\":[\"https://example.com/frame-1.png\"]}")
response = requests.request("POST", url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
result = response.json()
if isinstance(result, dict) and (result.get("success") is False or result.get("code") is False or result.get("error")):
    raise RuntimeError(json.dumps(result, ensure_ascii=False))
print(json.dumps(result, ensure_ascii=False, indent=2))

javascript

// Node.js 20+
const url = "https://api.tu-zi.com/v1/videos";
const headers = {
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
};
for (const name of ["API_KEY"]) {
  if (!process.env[name]?.trim()) throw new Error("Set environment variable: " + name);
}
headers.Authorization = 'Bearer ' + process.env.API_KEY;
const response = await fetch(url, { method: "POST", headers, body: JSON.stringify({
  "model": "viduq3-turbo",
  "prompt": "镜头缓慢推进,保持主体外观一致。",
  "duration": 1,
  "size": "540p",
  "metadata": {
    "action": "generate"
  },
  "images": [
    "https://example.com/frame-1.png"
  ]
}), signal: AbortSignal.timeout(120000) });
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
if (result?.success === false || result?.code === false || result?.error) throw new Error(JSON.stringify(result));
console.log(JSON.stringify(result, null, 2));

首尾帧:最小请求

适用型号:viduq3-turbo

POST /v1/videos

{
  "model": "viduq3-turbo",
  "prompt": "镜头缓慢推进,保持主体外观一致。",
  "duration": 1,
  "size": "540p",
  "metadata": {
    "action": "firstTailGenerate"
  },
  "images": [
    "https://example.com/frame-1.png",
    "https://example.com/frame-2.png"
  ]
}

curl

curl --fail-with-body --silent --show-error --connect-timeout 10 --max-time 120 --request POST 'https://api.tu-zi.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "viduq3-turbo",
  "prompt": "镜头缓慢推进,保持主体外观一致。",
  "duration": 1,
  "size": "540p",
  "metadata": {
    "action": "firstTailGenerate"
  },
  "images": [
    "https://example.com/frame-1.png",
    "https://example.com/frame-2.png"
  ]
}'

python

import json
import os
import requests

url = "https://api.tu-zi.com/v1/videos"
headers = json.loads("{\"Authorization\":\"Bearer YOUR_API_KEY\",\"Content-Type\":\"application/json\"}")
for name in ["API_KEY"]:
    if not os.environ.get(name, "").strip():
        raise RuntimeError("Set environment variable: " + name)
headers["Authorization"] = "Bearer " + os.environ["API_KEY"]
payload = json.loads("{\"model\":\"viduq3-turbo\",\"prompt\":\"镜头缓慢推进,保持主体外观一致。\",\"duration\":1,\"size\":\"540p\",\"metadata\":{\"action\":\"firstTailGenerate\"},\"images\":[\"https://example.com/frame-1.png\",\"https://example.com/frame-2.png\"]}")
response = requests.request("POST", url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
result = response.json()
if isinstance(result, dict) and (result.get("success") is False or result.get("code") is False or result.get("error")):
    raise RuntimeError(json.dumps(result, ensure_ascii=False))
print(json.dumps(result, ensure_ascii=False, indent=2))

javascript

// Node.js 20+
const url = "https://api.tu-zi.com/v1/videos";
const headers = {
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
};
for (const name of ["API_KEY"]) {
  if (!process.env[name]?.trim()) throw new Error("Set environment variable: " + name);
}
headers.Authorization = 'Bearer ' + process.env.API_KEY;
const response = await fetch(url, { method: "POST", headers, body: JSON.stringify({
  "model": "viduq3-turbo",
  "prompt": "镜头缓慢推进,保持主体外观一致。",
  "duration": 1,
  "size": "540p",
  "metadata": {
    "action": "firstTailGenerate"
  },
  "images": [
    "https://example.com/frame-1.png",
    "https://example.com/frame-2.png"
  ]
}), signal: AbortSignal.timeout(120000) });
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
if (result?.success === false || result?.code === false || result?.error) throw new Error(JSON.stringify(result));
console.log(JSON.stringify(result, null, 2));

图片参考:最小请求

适用型号:viduq3-turbo

POST /v1/videos

{
  "model": "viduq3-turbo",
  "prompt": "镜头缓慢推进,保持主体外观一致。",
  "duration": 3,
  "size": "540p",
  "metadata": {
    "action": "referenceGenerate"
  },
  "images": [
    "https://example.com/frame-1.png"
  ]
}

curl

curl --fail-with-body --silent --show-error --connect-timeout 10 --max-time 120 --request POST 'https://api.tu-zi.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "viduq3-turbo",
  "prompt": "镜头缓慢推进,保持主体外观一致。",
  "duration": 3,
  "size": "540p",
  "metadata": {
    "action": "referenceGenerate"
  },
  "images": [
    "https://example.com/frame-1.png"
  ]
}'

python

import json
import os
import requests

url = "https://api.tu-zi.com/v1/videos"
headers = json.loads("{\"Authorization\":\"Bearer YOUR_API_KEY\",\"Content-Type\":\"application/json\"}")
for name in ["API_KEY"]:
    if not os.environ.get(name, "").strip():
        raise RuntimeError("Set environment variable: " + name)
headers["Authorization"] = "Bearer " + os.environ["API_KEY"]
payload = json.loads("{\"model\":\"viduq3-turbo\",\"prompt\":\"镜头缓慢推进,保持主体外观一致。\",\"duration\":3,\"size\":\"540p\",\"metadata\":{\"action\":\"referenceGenerate\"},\"images\":[\"https://example.com/frame-1.png\"]}")
response = requests.request("POST", url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
result = response.json()
if isinstance(result, dict) and (result.get("success") is False or result.get("code") is False or result.get("error")):
    raise RuntimeError(json.dumps(result, ensure_ascii=False))
print(json.dumps(result, ensure_ascii=False, indent=2))

javascript

// Node.js 20+
const url = "https://api.tu-zi.com/v1/videos";
const headers = {
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
};
for (const name of ["API_KEY"]) {
  if (!process.env[name]?.trim()) throw new Error("Set environment variable: " + name);
}
headers.Authorization = 'Bearer ' + process.env.API_KEY;
const response = await fetch(url, { method: "POST", headers, body: JSON.stringify({
  "model": "viduq3-turbo",
  "prompt": "镜头缓慢推进,保持主体外观一致。",
  "duration": 3,
  "size": "540p",
  "metadata": {
    "action": "referenceGenerate"
  },
  "images": [
    "https://example.com/frame-1.png"
  ]
}), signal: AbortSignal.timeout(120000) });
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
if (result?.success === false || result?.code === false || result?.error) throw new Error(JSON.stringify(result));
console.log(JSON.stringify(result, null, 2));

任务结果与下载

保存提交返回的 id 或 task_id。统一视频查询使用 GET /v1/videos/{task_id},等待 queued / in_progress 到 completed 或 failed;完成后读取 video_url(部分响应同时在 metadata.url 提供)。本站相对路径需与调用域名拼接,/content 入口使用本站 Key;外部下载 URL 不携带本站 Key。结果可能过期,请及时下载。网络超时保留任务 ID 继续 GET,不自动重试创建 POST。

统一视频完整 Python / JavaScript 轮询下载示例

常见问题定位

现象检查方式
Error validating image / 图片 URI 错误视频或任务 ID 是否误填到了图片字段;检查媒体 URL 是否返回真实素材
unsupported content type / 字段不支持检查系列、版本和 content/contents/input 的准确类型;不要把音频 URL 填入 voice_id
400 参数冲突检查 prompt 与 input、首尾帧与多参考、秒数与 response_format 的互斥项
HTTP 成功但任务 failed记录本站任务 ID、时间、模型、域名和已脱敏参数;按任务错误定位,不能依据提交 200 宣称成功
404 或不可访问任务确认域名、Key 权限、本站任务类型;不要使用其他站点或官方任务 ID
本地文件无法访问使用系列明确支持的上传方式,或提供可读取的 HTTPS 媒体 URL

资料与适用范围

Vidu Text to video

Vidu Image to video

Vidu First/last frames

Vidu Image references

Vidu Subject references

Vidu callback signature

适用场景

  • 选择视频模型和素材协议
  • 排查参数与任务失败

API 协议

  • /v1/videos

常见问题

拿到 task_id 就代表生成成功吗?

不代表。保存本站任务 ID,查询到成功终态并确认结果可读取后才算完成;failed 要查看错误,不要自动重建任务。

本地图片、视频和 WAV 能直接填写路径吗?

不能。URL 字段需要服务可读取的媒体地址;localhost、电脑路径及需要浏览器登录的链接不可用。Kling 本地 PCM WAV 的 multipart 音色上传需本站先启用该接口(2026-11-15 两站实测均为 404);其他素材按该系列上传或素材流程处理。

能把不同模型的参数和任务 ID 互换吗?

不能假定兼容。核对精确型号、入口、大小写、媒体角色及互斥字段。编辑、草稿和音色都要求对应类型、本人可访问的成功任务;官方能力也不等于本站已验收。

官方来源

  1. Vidu Text to video 官方
  2. Vidu Image to video 官方
  3. Vidu First/last frames 官方
  4. Vidu Image references 官方
  5. Vidu Subject references 官方
  6. Vidu callback signature 官方