视频生成技能
本技能指导如何使用 z-ai-web-dev-sdk 包实现视频生成功能,使AI模型能够通过异步任务处理从文本描述或图像创建视频。
技能路径
技能位置:{project_path}/skills/video-generation
此技能位于项目中的上述路径。
参考脚本:示例测试脚本位于 {Skill Location}/scripts/ 目录中,可用于快速测试和参考。请参阅 {Skill Location}/scripts/video.ts 获取工作示例。
概述
视频生成允许您构建能够从文本提示或图像创建视频内容的应用程序,并带有可自定义的参数,如分辨率、帧率、时长和质量设置。该API使用异步任务模型,您需要创建一个任务并轮询结果。
重要提示:z-ai-web-dev-sdk 必须 仅在后端代码中使用。切勿在客户端代码中使用。
前提条件
z-ai-web-dev-sdk 包已安装。如下例所示导入它。
CLI 使用(适用于简单任务)
对于简单的视频生成任务,您可以使用 z-ai CLI 而不是编写代码。CLI 自动处理任务创建和轮询,非常适合快速测试和简单自动化。
基本文本转视频
# 生成视频并自动轮询
z-ai video --prompt "一只猫在玩球" --poll
# 使用短选项
z-ai video -p "美丽的山景" --poll
自定义质量和设置
# 质量模式(speed 或 quality)
z-ai video -p "日落时的海浪" --quality quality --poll
# 自定义分辨率和帧率
z-ai video \
-p "城市延时摄影" \
--size "1920x1080" \
--fps 60 \
--poll
# 自定义时长(5 或 10 秒)
z-ai video -p "烟花表演" --duration 10 --poll
图像转视频
重要提示:对于 image_url 参数,强烈建议使用 base64 编码的图像数据 而不是 URL。这种方法更可靠,可以避免潜在的网络问题或访问限制。
注意:将数据 URI 中的 MIME 类型与您的实际图像格式(image/jpeg、image/png、image/webp 等)匹配,以避免解码问题。
# 使用 base64 从单张图像生成视频(推荐)
# 使用正确的 MIME 类型将图像转换为 base64
# 对于 PNG 图像
IMAGE_BASE64=$(base64 -i image.png)
z-ai video \
--image-url "data:image/png;base64,${IMAGE_BASE64}" \
--prompt "让场景活起来" \
--poll
# 对于 JPEG 图像
IMAGE_BASE64=$(base64 -i photo.jpg)
z-ai video \
--image-url "data:image/jpeg;base64,${IMAGE_BASE64}" \
--prompt "让场景活起来" \
--poll
# 对于 WebP 图像
IMAGE_BASE64=$(base64 -i image.webp)
z-ai video \
--image-url "data:image/webp;base64,${IMAGE_BASE64}" \
--prompt "让场景活起来" \
--poll
# 使用 URL(不太推荐,可能存在可靠性问题)
z-ai video \
-i "https://example.com/photo.jpg" \
-p "为此场景添加运动" \
--poll
首尾帧模式
重要提示:为了获得最佳可靠性,请使用 base64 编码的图像而不是 URL。确保 MIME 类型与您的实际图像格式匹配。
# 使用 base64 在两帧之间生成视频(推荐)
# 确保为每个图像使用正确的 MIME 类型
# PNG 图像示例
START_BASE64=$(base64 -i start.png)
END_BASE64=$(base64 -i end.png)
z-ai video \
--image-url "data:image/png;base64,${START_BASE64},data:image/png;base64,${END_BASE64}" \
--prompt "帧之间的平滑过渡" \
--poll
# JPEG 图像示例
START_BASE64=$(base64 -i start.jpg)
END_BASE64=$(base64 -i end.jpg)
z-ai video \
--image-url "data:image/jpeg;base64,${START_BASE64},data:image/jpeg;base64,${END_BASE64}" \
--prompt "帧之间的平滑过渡" \
--poll
# 使用 URL(不太推荐)
z-ai video \
--image-url "https://example.com/start.png,https://example.com/end.png" \
--prompt "帧之间的平滑过渡" \
--poll
带音频生成
# 生成带有 AI 生成音频效果的视频
z-ai video \
-p "暴风雨来临" \
--with-audio \
--poll
保存输出
# 将任务结果保存到 JSON 文件
z-ai video \
-p "山间日出" \
--poll \
-o video_result.json
自定义轮询参数
# 自定义轮询行为
z-ai video \
-p "跳舞的机器人" \
--poll \
--poll-interval 10 \
--max-polls 30
# 创建任务但不轮询(获取任务 ID)
z-ai video -p "抽象艺术动画" -o task.json
CLI 参数
--prompt, -p <text>:可选 - 视频的文本描述--image-url, -i <data>:可选 - 最好使用 base64 编码的图像数据(例如,“data:image/png;base64,iVBORw...”)。也支持 URL,但不推荐。对于两张图像,请使用逗号分隔的值。--quality, -q <mode>:可选 - 输出模式:speed或quality(默认:speed)--with-audio:可选 - 生成 AI 音频效果(默认:false)--size, -s <resolution>:可选 - 视频分辨率(例如,“1920x1080”)--fps <rate>:可选 - 帧率:30 或 60(默认:30)--duration, -d <seconds>:可选 - 时长:5 或 10 秒(默认:5)--model, -m <model>:可选 - 要使用的模型名称--poll:可选 - 自动轮询直到任务完成--poll-interval <seconds>:可选 - 轮询间隔(默认:5)--max-polls <count>:可选 - 最大轮询尝试次数(默认:60)--output, -o <path>:可选 - 输出文件路径(JSON 格式)
支持的分辨率
1024x1024768x1344864x11521344x7681152x8641440x720720x14401920x1080(以及其他标准分辨率)
稍后检查任务状态
如果您创建任务时没有使用 --poll,可以稍后检查其状态:
# 从初始响应中获取任务 ID
z-ai async-result --id "task-id-here" --poll
何时使用 CLI 与 SDK
使用 CLI 的场景:
- 快速视频生成测试
- 简单的一次性视频创建
- 命令行自动化脚本
- 测试不同的提示和设置
使用 SDK 的场景:
- 使用自定义逻辑进行批量视频生成
- 与 Web 应用程序集成
- 自定义任务队列管理
- 具有复杂工作流的生产应用程序
视频生成工作流
视频生成遵循两步异步模式:
- 创建任务:提交视频生成请求并接收任务 ID
- 轮询结果:查询任务状态直到完成,然后检索视频 URL
基本视频生成实现
简单文本转视频生成
import ZAI from 'z-ai-web-dev-sdk';
async function generateVideo(prompt) {
try {
const zai = await ZAI.create();
// 创建视频生成任务
const task = await zai.video.generations.create({
prompt: prompt,
quality: 'speed', // 'speed' 或 'quality'
with_audio: false,
size: '1920x1080',
fps: 30,
duration: 5
});
console.log('任务 ID:', task.id);
console.log('任务状态:', task.task_status);
// 轮询结果
let result = await zai.async.result.query(task.id);
let pollCount = 0;
const maxPolls = 60;
const pollInterval = 5000; // 5 秒
while (result.task_status === 'PROCESSING' && pollCount < maxPolls) {
pollCount++;
console.log(`轮询 ${pollCount}/${maxPolls}: 状态为 ${result.task_status}`);
await new Promise(resolve => setTimeout(resolve, pollInterval));
result = await zai.async.result.query(task.id);
}
if (result.task_status === 'SUCCESS') {
// 从多个可能的字段获取视频 URL
const videoUrl = result.video_result?.[0]?.url ||
result.video_url ||
result.url ||
result.video;
console.log('视频 URL:', videoUrl);
return videoUrl;
} else {
console.log('任务失败或仍在处理中');
return null;
}
} catch (error) {
console.error('视频生成失败:', error.message);
throw error;
}
}
// 用法
const videoUrl = await generateVideo('一只猫在玩球。');
console.log('生成的视频:', videoUrl);
图像转视频生成
重要提示:image_url 参数接受 base64 编码的图像数据和 URL,但 强烈推荐使用 base64 编码 以获得更好的可靠性并避免网络相关问题。
关键:始终将 base64 数据 URI 中的 MIME 类型与实际的图像格式匹配,以防止解码错误。
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
import path from 'path';
// 辅助函数:根据文件扩展名检测 MIME 类型
function getMimeType(filePath) {
const ext = path.extname(filePath).toLowerCase();
const mimeTypes = {
'.jpg': 'image/jpeg',
'.jpeg': 'image/jpeg',
'.png': 'image/png',
'.gif': 'image/gif',
'.webp': 'image/webp',
'.bmp': 'image/bmp'
};
return mimeTypes[ext] || 'image/jpeg'; // 默认 JPEG
}
async function generateVideoFromImage(imagePath, prompt) {
const zai = await ZAI.create();
// 方法 1:使用 base64 编码的图像(推荐)
// 自动根据文件扩展名检测 MIME 类型
const imageBuffer = fs.readFileSync(imagePath);
const mimeType = getMimeType(imagePath);
const base64Image = `data:${mimeType};base64,${imageBuffer.toString('base64')}`;
const task = await zai.video.generations.create({
image_url: base64Image, // 带有正确 MIME 类型的 Base64 数据字符串
prompt: prompt,
quality: 'quality',
duration: 5,
fps: 30
});
return task;
}
// 方法 2:使用 URL(不太推荐)
async function generateVideoFromImageUrl(imageUrl, prompt) {
const zai = await ZAI.create();
const task = await zai.video.generations.create({
image_url: imageUrl, // URL 字符串
prompt: prompt,
quality: 'quality',
duration: 5,
fps: 30
});
return task;
}
// 用法示例
const task1 = await generateVideoFromImage(
'./images/photo.jpg', // 支持 JPEG
'用轻柔的动作动画化这个场景'
);
const task2 = await generateVideoFromImage(
'./images/graphic.png', // 支持 PNG
'添加动态运动'
);
const task3 = await generateVideoFromImage(
'./images/animation.webp', // 支持 WebP
'让这个活起来'
);
带起始帧和结束帧的图像转视频
重要提示:对于关键帧模式,强烈推荐 使用 base64 编码的图像而非 URL,以确保一致且可靠的视频生成。始终为每个图像使用正确的 MIME 类型。
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
import path from 'path';
// 辅助函数:根据文件扩展名检测 MIME 类型
function getMimeType(filePath) {
const ext = path.extname(filePath).toLowerCase();
const mimeTypes = {
'.jpg': 'image/jpeg',
'.jpeg': 'image/jpeg',
'.png': 'image/png',
'.gif': 'image/gif',
'.webp': 'image/webp',
'.bmp': 'image/bmp'
};
return mimeTypes[ext] || 'image/jpeg';
}
async function generateVideoWithKeyframes(startImagePath, endImagePath, prompt) {
const zai = await ZAI.create();
// 方法 1:使用 base64 编码的图像(推荐)
// 自动为每个图像检测 MIME 类型
const startBuffer = fs.readFileSync(startImagePath);
const endBuffer = fs.readFileSync(endImagePath);
const startMimeType = getMimeType(startImagePath);
const endMimeType = getMimeType(endImagePath);
const startBase64 = `data:${startMimeType};base64,${startBuffer.toString('base64')}`;
const endBase64 = `data:${endMimeType};base64,${endBuffer.toString('base64')}`;
const task = await zai.video.generations.create({
image_url: [startBase64, endBase64], // 带有正确 MIME 类型的 base64 字符串数组
prompt: prompt,
quality: 'quality',
duration: 10,
fps: 30
});
console.log('使用关键帧创建的任务:', task.id);
return task;
}
// 方法 2:使用 URL(不太推荐)
async function generateVideoWithKeyframesUrl(startImageUrl, endImageUrl, prompt) {
const zai = await ZAI.create();
const task = await zai.video.generations.create({
image_url: [startImageUrl, endImageUrl], // URL 字符串数组
prompt: prompt,
quality: 'quality',
duration: 10,
fps: 30
});
console.log('使用关键帧创建的任务:', task.id);
return task;
}
// 不同格式的用法示例
const task1 = await generateVideoWithKeyframes(
'./frames/start.jpg', // JPEG 起始帧
'./frames/end.jpg', // JPEG 结束帧
'这些场景之间的平滑过渡'
);
const task2 = await generateVideoWithKeyframes(
'./frames/start.png', // PNG 起始帧
'./frames/end.webp', // WebP 结束帧 - 不同格式也可以!
'图像之间的变形效果'
);
异步结果管理
查询任务状态
import ZAI from 'z-ai-web-dev-sdk';
async function checkTaskStatus(taskId) {
try {
const zai = await ZAI.create();
const result = await zai.async.result.query(taskId);
console.log('任务状态:', result.task_status);
if (result.task_status === 'SUCCESS') {
// 从结果中提取视频 URL
const videoUrl = result.video_result?.[0]?.url ||
result.video_url ||
result.url ||
result.video;
if (videoUrl) {
console.log('视频 URL:', videoUrl);
return { success: true, url: videoUrl };
}
} else if (result.task_status === 'PROCESSING') {
console.log('任务仍在处理中');
return { success: false, status: 'processing' };
} else if (result.task_status === 'FAIL') {
console.log('任务失败');
return { success: false, status: 'failed' };
}
} catch (error) {
console.log(error)
}
}
// 用法
const taskStatus = await checkTaskStatus('your-task-id');
console.log('状态:', JSON.stringify(taskStatus, null, 2));
任务结果数据结构
任务结果包含多个字段以处理不同的 API 响应格式:
{
"task_id": "your-task-id",
"task_status": "SUCCESS|PROCESSING|FAIL",
"video_result": [
{
"url": "https://example.com/generated-video.mp4",
"duration": 5.0,
"size": "1920x1080",
"fps": 30
}
],
// 视频 URL 的备选字段
"video_url": "https://example.com/generated-video.mp4",
"url": "https://example.com/generated-video.mp4",
"video": "https://example.com/generated-video.mp4",
"error_message": null
}
SDK API 参考
zai.video.generations.create(params)
| 参数 | 类型 | 必需 | 默认值 | 描述 |
|---|---|---|---|---|
prompt | string | 否 | - | 视频的文本描述 |
image_url | string 或 string[] | 否 | - | Base64 图像数据(推荐)或 URL。对于关键帧,使用数组。 |
quality | string | 否 | "speed" | 输出质量:"speed" 或 "quality" |
with_audio | boolean | 否 | false | 生成 AI 音频效果 |
size | string | 否 | - | 视频分辨率(例如 "1920x1080") |
fps | integer | 否 | 30 | 帧率:30 或 60 |
duration | integer | 否 | 5 | 视频时长(秒):5 或 10 |
model | string | 否 | - | 要使用的模型名称 |
zai.async.result.query(taskId)
| 参数 | 类型 | 必需 | 描述 |
|---|---|---|---|
taskId | string | 是 | 要查询的任务 ID |
返回一个包含 task_status、video_result 和备选视频 URL 字段的对象。