视频生成技能
本技能指导如何使用 z-ai-web-dev-sdk 包实现视频生成功能,使 AI 模型能够通过异步任务处理从文本描述或图像创建视频。
技能路径
技能位置:{project_path}/skills/video-generation
此技能位于项目中的上述路径。
参考脚本:示例测试脚本位于 {技能位置}/scripts/ 目录中,可快速进行测试和参考。请参见 {技能位置}/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
自定义质量与设置
# 质量模式(速度或质量)
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 从单张图像生成视频(推荐)
# 将图像转换为 base64 并确保 MIME 类型正确
# 对于 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.error('查询任务状态失败:', error.message);
throw error;
}
}
// 使用示例
const status = await checkTaskStatus('your-task-id-here');
console.log('状态:', status);
完整轮询实现
import ZAI from 'z-ai-web-dev-sdk';
async function pollUntilComplete(taskId, options = {}) {
const {
maxAttempts = 60,
interval = 5000
} = options;
const zai = await ZAI.create();
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
const result = await zai.async.result.query(taskId);
console.log(`尝试 ${attempt}/${maxAttempts}:状态 = ${result.task_status}`);
if (result.task_status === 'SUCCESS') {
// 提取结果 URL
const urls = [
result.video_result?.[0]?.url,
result.video_url,
result.url,
result.video
].filter(Boolean);
return {
success: true,
url: urls[0],
allUrls: urls,
fullResult: result
};
}
if (result.task_status === 'FAIL') {
return {
success: false,
status: 'failed',
error: result.error || result.message || '未知错误',
fullResult: result
};
}
if (attempt < maxAttempts) {
await new Promise(resolve => setTimeout(resolve, interval));
}
}
return {
success: false,
status: 'timeout',
message: `经过 ${maxAttempts} 次尝试后超时`
};
}
// 使用示例
const result = await pollUntilComplete('your-task-id', {
maxAttempts: 30,
interval: 3000
});
if (result.success) {
console.log('视频 URL:', result.url);
} else {
console.error('失败:', result.error);
}
API 参考
zai.video.generations.create()
创建一个新的视频生成任务。
选项:
| 参数 | 类型 | 必需 | 描述 |
|---|---|---|---|
prompt | string | 否(除非无图像) | 视频的文本描述 |
image_url | string 或 array | 否(除非无提示) | 图像数据(URL 或 base64 字符串)。对于两张图像,传入字符串数组 |
quality | string | 否 | 输出模式:speed 或 quality(默认:speed) |
with_audio | boolean | 否 | 生成 AI 音效(默认:false) |
size | string | 否 | 分辨率(例如 "1920x1080")(默认:"1024x1024") |
fps | number | 否 | 帧率:30 或 60(默认:30) |
duration | number | 否 | 时长:5 或 10 秒(默认:5) |
响应:
| 字段 | 类型 | 描述 |
|---|---|---|
id | string | 用于轮询的任务 ID |
task_status | string | 初始状态("PROCESSING") |
created_at | number | 创建时间戳 |
zai.async.result.query()
查询现有任务的状态和结果。
参数:
| 参数 | 类型 | 描述 |
|---|---|---|
taskId | string | 要查询的任务 ID |
响应:
| 字段 | 类型 | 描述 |
|---|---|---|
task_status | string | QUERYING(查询中)、PROCESSING(处理中)、SUCCESS(成功)或 FAIL(失败) |
video_result | array | 视频 URL 对象数组(成功时) |
video_url | string | 直接视频 URL(成功时) |
url | string | 替代视频 URL(成功时) |
video | string | 另一个替代视频 URL(成功时) |
error | string | 错误消息(失败时) |
完整示例
查看 {技能位置}/scripts/video.ts 获取包含以下内容的完整工作示例:
- 文本到视频生成
- 使用 base64 编码的图像到视频生成
- 带轮询的异步结果处理
- 错误处理和输入验证
最佳实践
- 使用 base64 编码的图像:尽可能始终将图像编码为 base64 格式,以确保可靠性和性能
- 始终匹配 MIME 类型:在 base64 数据 URI 中使用正确的 MIME 类型,以防止解码错误
- 实现适当的轮询:使用指数退避或合理的轮询间隔,避免过载 API
- 处理所有状态:代码应优雅地处理成功、失败和处理中状态
- 验证输入:确保 prompt 和 image_url 参数的输入验证正确
- 检查文件限制:注意文件大小限制,并根据需要压缩大图像
- 监控配额:注意 API 使用限制和配额
限制
- 视频时长:5 或 10 秒
- 帧率:30 或 60 FPS
- 分辨率:多种宽高比受支持(见受支持的分辨率部分)
- 最大轮询尝试次数:建议 60 次(默认轮询间隔为 5 秒时为 5 分钟)
- 图像格式:JPEG、PNG、GIF、WebP、BMP