Q4 Preview 图生视频

目录路径:视频系列 / Q4 Preview 图生视频
文档 slug:model-q4-preview-video


根据一张首帧图片生成视频,支持音画同步和自动切镜。模型编码为 q4-preview-video。本文覆盖图片输入、提示词、声音、水印、元数据、任务查询和回调。

接入信息

项目内容
模型类型视频生成
调用方式异步任务
创建任务POST /api/v1/tasks
查询任务GET /api/v1/tasks/{task_id}
输出时长3 至 16 秒,整数,默认 5 秒
输出分辨率540p、720p、1080p、2K、4K,默认 720p
输入图片仅 1 张,作为视频首帧

请将示例中的 YOUR_API_DOMAIN 替换为当前租户的 API 域名,YOUR_API_KEY 替换为平台分配的 API Key。模型需要在当前租户上架,且 API Key 具有视频模型访问权限。

鉴权与请求格式

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

必须提交 JSON。布尔值使用 true / false,不要使用字符串 "true" / "false";时长、种子和水印位置使用整数。

创建任务

POST /api/v1/tasks

请求参数

参数类型必填默认值取值与说明
modelstring是—固定为 q4-preview-video。
imagesarray<string>是—仅包含 1 张首帧图片,可使用可访问的 HTTP/HTTPS URL 或完整图片 Base64。
promptstring否—描述画面、运动、镜头、对白和音效,最多 20,000 个字符。
is_recboolean否true是否由 AI 优化提示词;设为 false 使用提供的提示词。建议显式指定。
durationinteger否5输出视频时长,单位秒,取值 3 至 16。
resolutionstring否720p540p、720p、1080p、2K、4K。请保留大小写。
audioboolean否truetrue 生成包含对白、音效的有声视频;false 生成静音视频。
seedinteger否0非负随机种子。不传或为 0 时随机生成;指定正整数用于控制生成随机性。
payloadstring否—自定义业务关联数据,最多 1,048,576 个字符。可记录订单号、素材号等。平台任务结果以 task_id 为主要关联标识。
watermarkboolean否true是否在画面添加水印。需要无水印视频时请显式传 false。
wm_positioninteger否3水印位置:1 左上、2 右上、3 右下、4 左下。
wm_urlstring否—自定义水印图片的 HTTP/HTTPS URL。不提供时使用默认的 AI 生成标识。
meta_datastring否—自定义元数据标识,必须是有效 JSON 的字符串形式,不能直接提交 JSON 对象。
callback_urlstring否—任务完成或失败时接收平台 POST 通知的地址,建议使用 HTTPS。

wm_position、wm_url 用于 watermark=true 的场景。watermark 控制画面水印;meta_data 控制文件元数据,两者分别设置。若对元数据标识有明确要求,请显式填写 meta_data。

图片限制

  • images 必须为数组,例如 ["https://example.com/first-frame.png"],不能直接传字符串。
  • 支持 PNG、JPEG、JPG、WEBP;单张原始图片不超过 50 MB。
  • HTTP/HTTPS 图片必须在生成期间保持可访问,不应要求浏览器登录。
  • Base64 必须包含 MIME 类型前缀,例如 data:image/png;base64,iVBORw0...。示例省略号不能用于实际调用。
  • 整个 JSON 请求体必须小于 20 MB。Base64 编码会增加体积,较大图片建议通过 URL 提交。
  • 图片格式、文件大小和访问权限均需满足要求;URL 能打开不代表素材符合生成要求。

最小请求

{
  "model": "q4-preview-video",
  "images": ["https://example.com/first-frame.png"]
}

该请求生成 5 秒、720p 的有声视频,启用提示词优化和水印。需要稳定控制行为时,显式填写可选参数。

完整请求示例

curl --request POST 'https://YOUR_API_DOMAIN/api/v1/tasks' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "q4-preview-video",
    "images": ["https://example.com/first-frame.png"],
    "prompt": "宇航员向镜头挥手,镜头缓缓上移,背景出现星空,配合轻柔的环境音。",
    "is_rec": false,
    "duration": 5,
    "resolution": "1080p",
    "audio": true,
    "seed": 12345,
    "payload": "order-20261011-001",
    "watermark": true,
    "wm_position": 3,
    "wm_url": "https://example.com/watermark.png",
    "meta_data": "{\"Label\":\"1\",\"ContentProducer\":\"creator\",\"ContentPropagator\":\"publisher\",\"ProduceID\":\"video-001\",\"PropagateID\":\"post-001\",\"ReservedCode1\":\"\",\"ReservedCode2\":\"\"}",
    "callback_url": "https://example.com/hooks/video"
  }'

图片、水印和回调 URL 为格式示例,请替换成真实可访问资源;不使用自定义水印或元数据时可删除相应字段。

创建成功响应

{
  "code": 1,
  "msg": "success",
  "data": {
    "task_id": "task_xxxxxxxxxxxx",
    "status": "processing",
    "model": "q4-preview-video",
    "channel": "",
    "frozen_points": 375,
    "created_at": "2026-10-11T08:00:00Z"
  }
}
字段类型说明
codeinteger1 表示本次 API 请求成功,0 表示失败。
msgstring本次请求说明。
data.task_idstring平台任务标识,后续查询和业务关联均使用此值。
data.statusstring创建后通常为 processing,不表示视频已经生成。
data.modelstring本次提交的公开模型编码。
data.channelstring可选的公开渠道标识;无需指定渠道时忽略此字段。
data.frozen_pointsnumber按本次价格快照预扣的点数;失败时按平台规则退回。
data.created_atstring任务创建时间。

查询任务

curl --request GET 'https://YOUR_API_DOMAIN/api/v1/tasks/task_xxxxxxxxxxxx' \
  --header 'Authorization: Bearer YOUR_API_KEY'

路径参数 task_id 必须使用创建接口返回的 data.task_id。无需 GET 请求体。查询仅能访问当前调用方有权限的任务。

data.status含义下一步
pending待处理或排队继续等待。
processing生成或结果交付处理中继续等待。
completed任务完成获取 result.video_url。
failed任务失败查看 error,修正后按需要重新创建。
cancelled任务已取消停止查询。

完成响应

{
  "code": 1,
  "msg": "success",
  "data": {
    "task_id": "task_xxxxxxxxxxxx",
    "model": "q4-preview-video",
    "type": "video",
    "call_type": "async",
    "status": "completed",
    "created_at": "2026-10-11T08:00:00Z",
    "result": {
      "video_url": "https://example.com/generated.mp4",
      "outputs": ["https://example.com/generated.mp4"]
    },
    "usage": {
      "input_tokens": 0,
      "output_tokens": 0,
      "total_tokens": 0,
      "points_cost": 375
    },
    "completed_at": "2026-10-11T08:02:00Z",
    "response_time_ms": 120000
  }
}
字段类型说明
data.result.video_urlstring主要视频下载地址。
data.result.outputsarray<string>可下载视频地址集合。
data.usage.points_costnumber本次任务实际扣除的平台点数。视频按秒计费,token 字段不参与计费。
data.completed_atstring完成时间,仅完成时返回。
data.response_time_msinteger平台记录的响应耗时,单位毫秒。
data.error.codestring失败代码,失败或异常状态下返回。
data.error.messagestring平台错误说明。

平台统一返回可下载的视频地址,不返回生成服务的任务编号、服务积分或原始回包。提示词、种子、业务数据和元数据等请求内容可在自己的业务系统中与平台 task_id 关联保存。视频下载链接有效期为 24 小时,请及时下载并保存。

轮询示例(Python)

import os
import time
import requests

base_url = os.environ["PLATFORM_API_BASE_URL"].rstrip("/")
headers = {"Authorization": f"Bearer {os.environ['PLATFORM_API_KEY']}"}
response = requests.post(f"{base_url}/api/v1/tasks", headers=headers, json={
    "model": "q4-preview-video",
    "images": ["https://example.com/first-frame.png"],
    "prompt": "镜头缓慢推进,人物自然微笑。",
    "duration": 5,
    "resolution": "720p",
    "is_rec": False,
    "watermark": False,
    "audio": False,
}, timeout=120)
response.raise_for_status()
created = response.json()
if created.get("code") != 1:
    raise RuntimeError(created)
task_id = created["data"]["task_id"]

deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    response = requests.get(f"{base_url}/api/v1/tasks/{task_id}", headers=headers, timeout=30)
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 1:
        raise RuntimeError(body)
    task = body["data"]
    if task["status"] == "completed":
        print(task["result"]["video_url"])
        break
    if task["status"] in ("failed", "cancelled"):
        raise RuntimeError(task.get("error", task))
    time.sleep(5)
else:
    raise TimeoutError(f"请稍后继续查询原任务 {task_id},避免重复创建")

回调通知

创建时传入 callback_url,平台在任务完成或失败后向该地址发送 JSON POST 通知。回调采用平台终态通知格式,与查询接口的外层响应不同;处理中状态请通过查询接口获取。

{
  "task_id": "task_xxxxxxxxxxxx",
  "model_code": "q4-preview-video",
  "type_code": "video",
  "status": "completed",
  "status_desc": "已完成",
  "input_tokens": 0,
  "output_tokens": 0,
  "total_tokens": 0,
  "actual_points": 375,
  "error_code": null,
  "error_message": null,
  "create_time": "2026-10-11 16:00:00",
  "completed_at": "2026-10-11 16:02:00",
  "result": {
    "video_url": "https://example.com/generated.mp4",
    "outputs": ["https://example.com/generated.mp4"]
  }
}

回调服务应尽快返回 HTTP 2xx,并按 task_id 幂等处理,避免重复通知触发重复业务动作。当前平台回调不提供签名字段;需要确认通知真实性时,请使用自己的平台 API Key 查询任务并核验状态。不要仅凭回调内容完成不可撤销的业务动作。

同类文章