视频生成技能
本技能指导如何使用 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 "A cat playing with a ball" --poll
# 使用短选项
z-ai video -p "Beautiful landscape with mountains" --poll
自定义质量与设置
# 质量模式(speed 或 quality)
z-ai video -p "Ocean waves at sunset" --quality quality --poll
# 自定义分辨率和帧率
z-ai video \
-p "City timelapse" \
--size "1920x1080" \
--fps 60 \
--poll
# 自定义时长(5 或 10 秒)
z-ai video -p "Fireworks display" --duration 10 --poll
图像到视频
重要提示: 对于 image_url 参数,强烈建议使用 base64 编码的图像数据 而非 URL。这种方法更可靠,可以避免潜在的网络问题或访问限制。
注意: 确保 data URI 中的 MIME 类型与实际图像格式匹配(image/jpeg, image/png, image/webp 等),以避免解码问题。
# 从单张图像生成视频(推荐使用 base64)
# 将图像转换为 base64 并确保 MIME 类型正确
# 对于 PNG 图像
IMAGE_BASE64=$(base64 -i image.png)
z-ai video \
--image-url "data:image/png;base64,${IMAGE_BASE64}" \
--prompt "Make the scene come alive" \
--poll
# 对于 JPEG 图像
IMAGE_BASE64=$(base64 -i photo.jpg)
z-ai video \
--image-url "data:image/jpeg;base64,${IMAGE_BASE64}" \
--prompt "Make the scene come alive" \
--poll
# 对于 WebP 图像
IMAGE_BASE64=$(base64 -i image.webp)
z-ai video \
--image-url "data:image/webp;base64,${IMAGE_BASE64}" \
--prompt "Make the scene come alive" \
--poll
# 使用 URL(不推荐,可能存在可靠性问题)
z-ai video \
-i "https://example.com/photo.jpg" \
-p "Add motion to this scene" \
--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 "Smooth transition between frames" \
--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 "Smooth transition between frames" \
--poll
# 使用 URL(不推荐)
z-ai video \
--image-url "https://example.com/start.png,https://example.com/end.png" \
--prompt "Smooth transition between frames" \
--poll
带音频生成
# 生成视频并附带 AI 生成的音效
z-ai video \
-p "Thunder storm approaching" \
--with-audio \
--poll
保存输出
# 将任务结果保存到 JSON 文件
z-ai video \
-p "Sunrise over mountains" \
--poll \
-o video_result.json
自定义轮询参数
# 自定义轮询行为
z-ai video \
-p "Dancing robot" \
--poll \
--poll-interval 10 \
--max-polls 30
# 创建任务但不进行轮询(获取任务 ID)
z-ai video -p "Abstract art animation" -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('Task ID:', task.id);
console.log('Task Status:', 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('Video URL:', videoUrl);
return videoUrl;
} else {
console.log('任务失败或仍在处理中');
return null;
}
} catch (error) {
console.error('视频生成失败:', error.message);
throw error;
}
}
// 使用示例
const videoUrl = await generateVideo('A cat is playing with a ball.');
console.log('生成的视频:', videoUrl);
图像到视频生成
重要提示: image_url 参数接受 base64 编码的图像数据和 URL,但强烈建议使用 base64 编码以提高可靠性并避免网络相关问题。
关键: 始终确保 base64 data 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('Task Status:', 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('Video 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.error('查询任务状态失败:', error.message);
throw error;
}
}
轮询直至完成
import ZAI from 'z-ai-web-dev-sdk';
async function pollUntilComplete(taskId, options = {}) {
const {
interval = 5000,
maxPolls = 60,
onProgress = null
} = options;
const zai = await ZAI.create();
let result = await zai.async.result.query(taskId);
let pollCount = 0;
while (result.task_status === 'PROCESSING' && pollCount < maxPolls) {
pollCount++;
if (onProgress) {
onProgress(pollCount, maxPolls, result);
}
await new Promise(resolve => setTimeout(resolve, interval));
result = await zai.async.result.query(taskId);
}
return result;
}
// 使用示例
const finalResult = await pollUntilComplete(taskId, {
interval: 3000, // 每 3 秒轮询一次
maxPolls: 100, // 最多轮询 100 次
onProgress: (current, max, result) => {
console.log(`处理中的轮询 ${current}/${max}...`);
}
});
if (finalResult.task_status === 'SUCCESS') {
const videoUrl = finalResult.video_result?.[0]?.url || finalResult.video_url;
console.log('生成的视频:', videoUrl);
}
视频生成最佳实践
使用 base64 编码的图像
- 强烈推荐使用 base64 编码的图像而非 URL
- 确保 MIME 类型与实际图像格式匹配(image/jpeg, image/png, image/webp 等)
- Base64 避免网络问题并确保更快、更可靠的处理
动态检测 MIME 类型
import path from 'path';
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';
}
自定义轮询逻辑
- 根据任务复杂度调整轮询间隔和最大轮询次数
- 对长时间运行的任务实现指数退避
- 在 UI 应用中提供进度反馈
- 优雅地处理超时和错误
从结果中提取视频 URL
根据 API 响应结构,视频 URL 可能位于不同字段:
// 处理多种响应格式
const videoUrl = result.video_result?.[0]?.url ||
result.video_url ||
result.url ||
result.video;
常见问题排查
图像编码问题
- 问题: 视频生成失败,出现解码错误
- 解决方案: 验证 base64 字符串格式并确保 MIME 类型与实际图像格式匹配。使用
data:image/png;base64,...格式。
轮询超时
- 问题: 任务长时间处于 "PROCESSING" 状态
- 解决方案: 增加
maxPolls或pollInterval。对于复杂视频,生成可能需要几分钟。
图像格式支持
- 支持: JPEG, PNG, WebP, GIF, BMP
- 推荐: 为获得最佳兼容性,使用 JPEG 或 PNG
- 注意: 首尾帧模式允许混合格式(例如,起始帧使用 JPEG,结束帧使用 PNG/WebP)
相关文档
z-ai-web-dev-sdk包文档- 视频生成 API 参考
async.result.query方法文档