Vidu Q3

Vidu Q3 多参考版视频生成,支持多参考图和 Subjects 模式,多机位一致性最优,540p-1080p。

CokeAPI 接入 Vidu Q3 多参考版视频模型。默认是异步任务: POST 创建后拿到 task_id,再通过 GET /v1/generations/{task_id} 轮询直到 succeeded。

图生视频提示:生成接口不再接收内联 base64 图片数据。请先使用文件上传接口上传参考图片获取 URL,再传入 image_urls。

模型 ID: viduq3

调用示例

curl https://cokeapi.com/v1/video/generations \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3",
    "prompt": "@cat 和 @dog 在公园里奔跑,阳光明媚",
    "duration": 8,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "audio": true,
    "metadata": {
      "subjects": [
        {"name": "cat", "images": ["https://cdn.cokeapi.com/uploads/2026/05/17/cat.jpg"]},
        {"name": "dog", "images": ["https://cdn.cokeapi.com/uploads/2026/05/17/dog.jpg"]}
      ]
    }
  }'

curl https://cokeapi.com/v1/video/generations \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3",
    "prompt": "让图片中的人物缓缓转身并微笑",
    "image_urls": ["https://cdn.cokeapi.com/uploads/2026/05/17/photo.png"],
    "duration": 5,
    "resolution": "720p"
  }'

curl https://cokeapi.com/v1/video/generations \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3",
    "prompt": "@cat 在沙发上睡觉,温馨居家风格",
    "image_urls": ["https://cdn.cokeapi.com/uploads/2026/05/17/room.jpg"],
    "duration": 8,
    "resolution": "720p",
    "audio": true,
    "metadata": {
      "subjects": [
        {"name": "cat", "images": ["https://cdn.cokeapi.com/uploads/2026/05/17/cat.jpg"]}
      ],
      "audio_type": "all"
    }
  }'

TASK_ID="01HX..."
curl https://cokeapi.com/v1/generations/$TASK_ID \
  -H "Authorization: Bearer sk-xxxxxxxx"

import httpx, time

BASE = "https://cokeapi.com/v1"
HEADERS = {"Authorization": "Bearer sk-xxxxxxxx"}

r = httpx.post(
    f"{BASE}/video/generations",
    headers=HEADERS,
    json={
        "model": "viduq3",
        "prompt": "@cat 在沙发上睡觉,温馨居家风格",
        "duration": 8,
        "resolution": "720p",
        "aspect_ratio": "16:9",
        "audio": True,
    },
    timeout=60,
)
task_id = r.json()["id"]

while True:
    r = httpx.get(f"{BASE}/generations/{task_id}", headers=HEADERS, timeout=30)
    data = r.json()
    if data["status"] in ("succeeded", "failed", "refunded"):
        print(data)
        break
    time.sleep(5)

const BASE = "https://cokeapi.com/v1";
const KEY = process.env.COKEAPI_KEY;

const create = await fetch(`${BASE}/video/generations`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "viduq3",
    prompt: "@cat 在沙发上睡觉,温馨居家风格",
    duration: 8,
    resolution: "720p",
    aspect_ratio: "16:9",
    audio: true,
  }),
});
const { id: taskId } = await create.json();

while (true) {
  const poll = await fetch(`${BASE}/generations/${taskId}`, {
    headers: { "Authorization": `Bearer ${KEY}` },
  });
  const data = await poll.json();
  if (["succeeded", "failed", "refunded"].includes(data.status)) {
    console.log(data);
    break;
  }
  await new Promise((r) => setTimeout(r, 5000));
}

请求参数

参数	类型	必填	默认值	说明
model	string	是	—	`viduq3`
prompt	string	是	—	视频提示词,最大 5000 字符。使用 subjects 时可通过 `@name` 引用主体
duration	int	否	5	视频时长(秒): 3-16
resolution	string	否	`720p`	视频分辨率: `540p` / `720p` / `1080p`
aspect_ratio	string	否	—	视频宽高比,支持任意值: `16:9` / `9:16` / `1:1` 等
image_urls	string[]	否	—	参考图片 URL 数组,最多 7 张
audio	bool	否	true	是否启用音视频输出
seed	int	否	—	随机种子,可复现结果
metadata	object	否	—	扩展字段,见下方说明

metadata 字段

参数	类型	说明
metadata.subjects	object[]	Subjects 模式,每个主体包含 `name` 和 `images` 字段,最多 7 个主体,每个主体最多 3 张图片
metadata.auto_subjects	bool	是否启用智能实体库能力,默认 `false`
metadata.voice_id	string	语音 ID,用于指定视频中的语音角色
metadata.audio_type	string	音频类型: `all`(音效+人声,默认) / `speech_only`(仅人声) / `sound-effect_only`(仅音效)
metadata.off_peak	bool	闲时模式,默认 `false`。闲时任务将在 48 小时内生成
metadata.payload	string	透传参数,不做处理仅传递数据,最大 1048576 字符
metadata.callback_url	string	回调地址,任务状态变更时发送 POST 回调

响应

创建任务 (`POST`)

{
  "id": "video_abc123def456",
  "task_id": "video_abc123def456",
  "object": "video.generation.task",
  "model": "viduq3",
  "status": "queued",
  "progress": 0,
  "created": 1768380224,
  "kind": "video",
  "mode": "text_to_video"
}

查询任务 (`GET /v1/generations/{task_id}`)

进行中:

{
  "id": "video_abc123def456",
  "task_id": "video_abc123def456",
  "object": "video.generation.task",
  "model": "viduq3",
  "status": "running",
  "progress": 45,
  "created": 1768380224,
  "kind": "video",
  "mode": "text_to_video"
}

完成后:

{
  "id": "video_abc123def456",
  "task_id": "video_abc123def456",
  "object": "video.generation.task",
  "model": "viduq3",
  "status": "succeeded",
  "progress": 100,
  "created": 1768380224,
  "kind": "video",
  "mode": "text_to_video",
  "result": {
    "id": "video_abc123def456",
    "object": "video.generation",
    "created": 1768380224,
    "model": "viduq3",
    "data": [
      {
        "url": "https://cdn.cokeapi.com/v/video_abc123def456.mp4",
        "duration_ms": 8000,
        "width": 1280,
        "height": 720
      }
    ]
  }
}

任务状态说明

状态	说明
queued	任务已排队等待处理
running	任务正在处理中
succeeded	任务已完成
failed	任务失败
refunded	任务失败已退款

计费

按 6 秒基准档计费,超过 6 秒按 10 秒档计费(费用 = 基准价 × 10/6)。

分辨率	6 秒基准价	10 秒价
720p	$0.069	$0.115
1080p	$0.086	$0.143

失败任务不计费,自动退款。价格为 2026-07 快照,以模型列表页实时价目为准。

注意事项

图生视频请先上传参考图 URL,再通过 image_urls 传入
viduq3 模型支持最多 7 张参考图,配合 metadata.subjects 可指定角色
音频生成功能默认开启,可通过 metadata.voice_id 指定声音
失败的任务不计费,会自动返还预扣点数

本页目录