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
请求参数
| 参数 | 类型 | 必填 | 默认值 | 取值与说明 |
|---|---|---|---|---|
model | string | 是 | — | 固定为 q4-preview-video。 |
images | array<string> | 是 | — | 仅包含 1 张首帧图片,可使用可访问的 HTTP/HTTPS URL 或完整图片 Base64。 |
prompt | string | 否 | — | 描述画面、运动、镜头、对白和音效,最多 20,000 个字符。 |
is_rec | boolean | 否 | true | 是否由 AI 优化提示词;设为 false 使用提供的提示词。建议显式指定。 |
duration | integer | 否 | 5 | 输出视频时长,单位秒,取值 3 至 16。 |
resolution | string | 否 | 720p | 540p、720p、1080p、2K、4K。请保留大小写。 |
audio | boolean | 否 | true | true 生成包含对白、音效的有声视频;false 生成静音视频。 |
seed | integer | 否 | 0 | 非负随机种子。不传或为 0 时随机生成;指定正整数用于控制生成随机性。 |
payload | string | 否 | — | 自定义业务关联数据,最多 1,048,576 个字符。可记录订单号、素材号等。平台任务结果以 task_id 为主要关联标识。 |
watermark | boolean | 否 | true | 是否在画面添加水印。需要无水印视频时请显式传 false。 |
wm_position | integer | 否 | 3 | 水印位置:1 左上、2 右上、3 右下、4 左下。 |
wm_url | string | 否 | — | 自定义水印图片的 HTTP/HTTPS URL。不提供时使用默认的 AI 生成标识。 |
meta_data | string | 否 | — | 自定义元数据标识,必须是有效 JSON 的字符串形式,不能直接提交 JSON 对象。 |
callback_url | string | 否 | — | 任务完成或失败时接收平台 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"
}
}
| 字段 | 类型 | 说明 |
|---|---|---|
code | integer | 1 表示本次 API 请求成功,0 表示失败。 |
msg | string | 本次请求说明。 |
data.task_id | string | 平台任务标识,后续查询和业务关联均使用此值。 |
data.status | string | 创建后通常为 processing,不表示视频已经生成。 |
data.model | string | 本次提交的公开模型编码。 |
data.channel | string | 可选的公开渠道标识;无需指定渠道时忽略此字段。 |
data.frozen_points | number | 按本次价格快照预扣的点数;失败时按平台规则退回。 |
data.created_at | string | 任务创建时间。 |
查询任务
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_url | string | 主要视频下载地址。 |
data.result.outputs | array<string> | 可下载视频地址集合。 |
data.usage.points_cost | number | 本次任务实际扣除的平台点数。视频按秒计费,token 字段不参与计费。 |
data.completed_at | string | 完成时间,仅完成时返回。 |
data.response_time_ms | integer | 平台记录的响应耗时,单位毫秒。 |
data.error.code | string | 失败代码,失败或异常状态下返回。 |
data.error.message | string | 平台错误说明。 |
平台统一返回可下载的视频地址,不返回生成服务的任务编号、服务积分或原始回包。提示词、种子、业务数据和元数据等请求内容可在自己的业务系统中与平台 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 查询任务并核验状态。不要仅凭回调内容完成不可撤销的业务动作。