Vidu Q4 Preview 视频生成

curl --request POST \
  --url https://api.apimart.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "viduq4-preview",
    "prompt": "女孩回头微笑，长发被风吹起，镜头缓缓推近",
    "image_urls": ["https://example.com/first-frame.png"],
    "duration": 5,
    "resolution": "1080p"
  }'

import requests

response = requests.post(
    "https://api.apimart.ai/v1/videos/generations",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "viduq4-preview",
        "prompt": "女孩回头微笑，长发被风吹起，镜头缓缓推近",
        "image_urls": ["https://example.com/first-frame.png"],
        "duration": 5,
        "resolution": "1080p"
    }
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.apimart.ai/v1/videos/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "viduq4-preview",
    prompt: "女孩回头微笑，长发被风吹起，镜头缓缓推近",
    image_urls: ["https://example.com/first-frame.png"],
    duration: 5,
    resolution: "1080p"
  })
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K..."
    }
  ]
}

POST

videos

generations

curl --request POST \
  --url https://api.apimart.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "viduq4-preview",
    "prompt": "女孩回头微笑，长发被风吹起，镜头缓缓推近",
    "image_urls": ["https://example.com/first-frame.png"],
    "duration": 5,
    "resolution": "1080p"
  }'

import requests

response = requests.post(
    "https://api.apimart.ai/v1/videos/generations",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "viduq4-preview",
        "prompt": "女孩回头微笑，长发被风吹起，镜头缓缓推近",
        "image_urls": ["https://example.com/first-frame.png"],
        "duration": 5,
        "resolution": "1080p"
    }
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.apimart.ai/v1/videos/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "viduq4-preview",
    prompt: "女孩回头微笑，长发被风吹起，镜头缓缓推近",
    image_urls: ["https://example.com/first-frame.png"],
    duration: 5,
    resolution: "1080p"
  })
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K..."
    }
  ]
}

本模型支持图生视频和参考生视频，不支持无图文生视频或首尾帧。提交成功后从 data[0].task_id 获取任务 ID，通过任务查询获取状态和结果。

生成模式

同一个模型 viduq4-preview 根据图片、角色及参考音频自动选择模式，不需要额外的模式参数。

输入方式	模式
仅提供 `first_frame_image` 或一个 `role: "first_frame"` 图片	图生视频
仅 1 张无角色图片，未提供参考音频	图生视频
图片包含 `reference_image` 或 `reference` 角色，且没有显式首帧	参考生视频
合计 2–15 张图片，且没有显式首帧	参考生视频
提供参考音频，同时提供 1–15 张图片，且没有显式首帧	参考生视频

图生视频：恰好 1 张首帧，提示词可选，不接受参考音频。
参考生视频：1–15 张参考图，最多 3 段参考音频，提示词必填。没有参考音频且仅用 1 张图时，请显式设置 role: "reference_image"，否则按图生视频处理。
显式首帧（first_frame_image 或 role: "first_frame"）不能与其他图片、参考图角色或参考音频混用，否则返回 HTTP 400。

curl --request POST \
  --url https://api.apimart.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "viduq4-preview",
    "prompt": "女孩回头微笑，长发被风吹起，镜头缓缓推近",
    "image_urls": ["https://example.com/first-frame.png"],
    "duration": 5,
    "resolution": "1080p"
  }'

import requests

response = requests.post(
    "https://api.apimart.ai/v1/videos/generations",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "viduq4-preview",
        "prompt": "女孩回头微笑，长发被风吹起，镜头缓缓推近",
        "image_urls": ["https://example.com/first-frame.png"],
        "duration": 5,
        "resolution": "1080p"
    }
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.apimart.ai/v1/videos/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "viduq4-preview",
    prompt: "女孩回头微笑，长发被风吹起，镜头缓缓推近",
    image_urls: ["https://example.com/first-frame.png"],
    duration: 5,
    resolution: "1080p"
  })
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K..."
    }
  ]
}

请求头

string

必填

Bearer 认证，格式为 Bearer <token>，其中 <token> 为你的 APIMart API Key。

请求参数

string

必填

固定为 viduq4-preview，全小写，需精确匹配。

string

视频生成提示词，最多 20,000 个字符。

图生视频：可选，不传时由模型根据首帧自行生成内容。
参考生视频：必填，缺失时返回 HTTP 400。

string[]

图片数组，支持公网可访问的图片 URL 或 Base64 Data URL，例如 data:image/png;base64,...。

图生视频：仅 1 张，作为首帧。
参考生视频：与 image_with_roles 合计 1–15 张。

可与 image_with_roles 混用，张数合计计算；不要与 first_frame_image 或显式 first_frame 角色混用。单张无角色图片是否进入参考生模式，还取决于是否提供参考音频。

object[]

带角色的图片数组。图生视频使用 1 个元素；参考生视频与 image_urls 合计 1–15 张。

显示显示图片字段

string

必填

图片的公网 URL 或 Base64 Data URL。

string

图片角色，大小写不敏感：

first_frame：图生视频首帧。
reference_image：参考生视频参考图，也接受 reference。
不传或留空：无参考音频时按合计张数判断，1 张为图生视频，2 张及以上为参考生视频；有参考音频时进入参考生视频。

其他值（如 last_frame）会同步返回 HTTP 400。

可与 image_urls 合并提供参考图，但首帧角色不能与参考素材混用。

string

仅用于图生视频，传入首帧图片的公网 URL 或 Base64 Data URL。使用此字段时不要再提供其他图片或参考音频。参考生视频请使用 image_urls 或 image_with_roles。

string[]

参考音频 URL 数组，仅用于参考生视频。与 audio_url 合计最多 3 段。要求 MP3 格式，每段 3–12 秒、单段不超过 50MB。提供参考音频时仍需至少 1 张图片，并且必须填写 prompt。音频格式或时长不符合要求时，会在任务执行阶段失败并全额退款，而不是提交时同步返回 HTTP 400。

string

单段参考音频 URL，要求与 audio_urls 相同；两个字段合计最多 3 段。

string

默认值:"16:9"

仅用于参考生视频，支持 1:1、9:16、16:9、3:4、4:3，默认 16:9。图生视频的宽高比由首帧图片决定，此参数会被忽略。

string

宽高比的兼容字段，可替代 aspect_ratio，支持相同取值。建议只使用其中一个字段。图生视频中不生效。

integer

默认值:"5"

视频时长，单位为秒。支持 3–16 秒，不支持 1–2 秒。

string

默认值:"720p"

视频分辨率，支持 540p、720p、1080p、2K、4K，大小写不敏感。

boolean

默认值:"true"

是否输出带对白和音效的音视频。

true：输出带音轨的视频（默认）。
false：输出无声视频。

有声和无声视频价格相同。

integer

随机种子。不传或传 0 时随机生成。

素材要求

图生视频：必须恰好提供 1 张首帧图，不接受参考音频。
参考生视频：必须提供 1–15 张参考图，可选最多 3 段参考音频。
支持 PNG、JPEG、JPG、WEBP，单张图片不超过 50MB。
使用 Base64 时，整个请求体必须小于 20MB，建议优先使用公网 URL。
图片 URL 必须能从公网访问。请将示例中的 URL 替换为实际可访问的图片地址。

两种模式均不能省略图片，也不支持 last_frame_image。首帧与参考素材混用、图片或音频数量超限等参数错误会在提交时返回 HTTP 400，不创建任务、不扣费。参考音频的格式和时长不符则在执行阶段失败并退款。

请求示例

仅提供首帧，不传提示词

{
  "model": "viduq4-preview",
  "image_urls": ["https://example.com/first-frame.png"]
}

默认生成 5 秒、720p、带音轨的视频。

带角色的首帧与 4K 输出

{
  "model": "viduq4-preview",
  "prompt": "镜头缓缓推近，人物自然微笑",
  "image_with_roles": [
    {
      "url": "https://example.com/first-frame.png",
      "role": "first_frame"
    }
  ],
  "duration": 8,
  "resolution": "4K",
  "audio": true
}

使用首帧字段生成无声视频

{
  "model": "viduq4-preview",
  "first_frame_image": "https://example.com/first-frame.png",
  "duration": 5,
  "resolution": "1080p",
  "audio": false
}

多图与参考音频生成视频

{
  "model": "viduq4-preview",
  "prompt": "图1的男孩用参考音频的内容对图2的女孩说话，背景是图3的咖啡馆",
  "image_urls": [
    "https://example.com/boy.png",
    "https://example.com/girl.png",
    "https://example.com/cafe.png"
  ],
  "audio_urls": ["https://example.com/line.mp3"],
  "aspect_ratio": "16:9",
  "duration": 8,
  "resolution": "720p"
}

单张图片进入参考生模式

{
  "model": "viduq4-preview",
  "prompt": "参考图中的人物走进咖啡馆，与店员挥手打招呼",
  "image_with_roles": [
    {
      "url": "https://example.com/person.png",
      "role": "reference_image"
    }
  ],
  "aspect_ratio": "9:16",
  "duration": 5,
  "resolution": "1080p"
}

此示例未传参考音频，通过 reference_image 角色明确选择参考生模式。示例中的图片和音频 URL 均需替换为实际可访问的素材地址。

提交响应

integer

响应状态码，成功为 200。

array

任务提交结果。

显示显示任务字段

string

提交成功时为 submitted，不代表视频生成完成。

string

任务 ID，用于查询状态和结果。

查询任务结果

建议每 5–10 秒轮询一次，状态为 completed 或 failed 时停止。使用统一查询接口：

curl --request GET \
  --url https://api.apimart.ai/v1/tasks/task_01K... \
  --header 'Authorization: Bearer <token>'

成功响应示例（视频 URL 为占位示例）：

{
  "code": 200,
  "data": {
    "id": "task_01K...",
    "status": "completed",
    "progress": 100,
    "result": {
      "videos": [
        {
          "url": ["https://example.com/generated-video.mp4"]
        }
      ]
    }
  }
}

状态	处理方式
`pending`	排队中，继续轮询
`processing`	生成中，继续轮询
`completed`	成功，从 `data.result.videos[0].url` 数组读取视频链接
`failed`	失败，从 `data.error.message` 获取原因；停止轮询，费用全额退回

视频链接有效期为 24 小时，请及时下载转存。不要依赖固定进度节点判断任务完成，以 status 为准。

计费说明

按视频时长与分辨率计费：费用 = 时长（秒）× 对应分辨率每秒单价。具体价格以模型定价为准。图生与参考生同价，开启或关闭音轨同价，参考图片与参考音频不额外收费；任务失败时自动全额退款。

常见参数错误

以下情况同步返回 HTTP 400，不创建任务、不扣费：

情况	处理方式
未提供图片	图生提供 1 张首帧，参考生提供 1–15 张参考图
显式首帧与其他图片、参考角色或参考音频混用	图生只保留 1 张首帧；参考生移除显式首帧字段或角色
`role` 为 `last_frame` 等不支持的值	使用 `first_frame`、`reference_image`、`reference`，或留空
参考生超过 15 张图片	减少图片数量，`image_urls` 与 `image_with_roles` 合计不超过 15 张
参考音频超过 3 段	`audio_urls` 与 `audio_url` 合计不超过 3 段
参考生缺少 `prompt`	补充提示词，最多 20,000 个字符
参考生宽高比不支持，例如 `21:9`	使用 `1:1`、`9:16`、`16:9`、`3:4` 或 `4:3`
提供 `last_frame_image`	删除该字段，本模型不支持首尾帧
`duration` 小于 3 或大于 16	使用 3–16 秒的整数
分辨率为 `480p`、`8K` 等不支持的值	使用 `540p`、`720p`、`1080p`、`2K` 或 `4K`

其他 Vidu 模型

需要文生视频或首尾帧时，使用 Vidu Q3 Pro / Turbo。本模型已支持多图参考，也可查看 Vidu Q3 Mix / Standard 的参考生能力。需要 1–2 秒短片时可选择 viduq3-pro，本模型最短为 3 秒。

概览

模型

文字系列

图像系列

视频系列

音频系列

审核系列

上传管理

任务管理

账户管理

Vidu Q4 Preview 视频生成

生成模式

请求头

请求参数

素材要求

请求示例

仅提供首帧，不传提示词

带角色的首帧与 4K 输出

使用首帧字段生成无声视频

多图与参考音频生成视频

单张图片进入参考生模式

提交响应

查询任务结果

计费说明

常见参数错误

其他 Vidu 模型

​生成模式

​请求头

​请求参数

​素材要求

​请求示例

​仅提供首帧，不传提示词

​带角色的首帧与 4K 输出

​使用首帧字段生成无声视频

​多图与参考音频生成视频

​单张图片进入参考生模式

​提交响应

​查询任务结果

​计费说明

​常见参数错误

​其他 Vidu 模型

生成模式

请求头

请求参数

素材要求

请求示例

仅提供首帧，不传提示词

带角色的首帧与 4K 输出

使用首帧字段生成无声视频

多图与参考音频生成视频

单张图片进入参考生模式

提交响应

查询任务结果

计费说明

常见参数错误

其他 Vidu 模型