Communitygithub.com

AiCurv/ADBCommander

使用 z-ai-web-dev-sdk 实现 AI 驱动的视频生成功能。当用户需要从文本提示或图像生成视频、以编程方式创建视频内容或构建生成视频输出的应用程序时使用此技能。支持异步任务管理,包括状态轮询和结果获取。

ADBCommander 是什么?

该技能指导开发者使用 `z-ai-web-dev-sdk` 包实现视频生成功能,允许 AI 模型通过异步任务处理从文本描述或图像创建视频。它详细介绍了两种使用方式:**CLI 工具**(适用于快速测试和简单自动化)和 **SDK 编程方式**(适用于需要自定义逻辑的批量生成、Web 应用集成或复杂工作流)。技能涵盖文本到视频、图像到视频(强烈推荐使用 base64 编码图像而非 URL)、首尾帧过渡模式以及音频生成等场景。它解释了如何设置参数(如分辨率、帧率、时长、质量模式),并通过创建任务和轮询结果的两步异步模式管理视频生成。该技能支持多种平台,并强调在服务端代码中使用 SDK。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/AiCurv/ADBCommander/tree/HEAD/skills/video-generation

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

视频生成技能

本技能指导如何使用 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 格式)

支持的分辨率

  • 1024x1024
  • 768x1344
  • 864x1152
  • 1344x768
  • 1152x864
  • 1440x720
  • 720x1440
  • 1920x1080(以及其它标准分辨率)

稍后检查任务状态

如果您在没有 --poll 参数的情况下创建了任务,可以稍后检查其状态:

# 从初始响应中获取任务 ID
z-ai async-result --id "task-id-here" --poll

何时使用 CLI 与 SDK

使用 CLI 的场景:

  • 快速视频生成测试
  • 简单的一次性视频创建
  • 命令行自动化脚本
  • 测试不同的提示和设置

使用 SDK 的场景:

  • 带自定义逻辑的批量视频生成
  • 与 Web 应用集成
  • 自定义任务队列管理
  • 具有复杂工作流的生产应用程序

视频生成工作流

视频生成遵循两步异步模式:

  1. 创建任务:提交视频生成请求并接收任务 ID
  2. 轮询结果:查询任务状态直至完成并获取视频 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 方法文档

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

AiCurv/ADBCommander

Generate a single-file Chinese atelier-style portfolio website (horizontal-row list + hover-reveal thumb interaction, art lishu typography "Alimama DaoLiTi" via CDN, light/dark theme, hash-routed detail pages). Takes a natural-language description of the studio (name, director, discipline, works) and outputs ONE working .html file. Runs in BOTH Claude Code (writes to ~/Desktop) and GLM / online chat (outputs HTML inline). Trigger phrases include "做个中式工作室作品集", "做个隶书作品集", "lishu-portfolio-gen ...", "做个白屋风格的作品集", or when user drags this skill folder into chat asking for an atelier-style site.

AiCurv/ADBCommander

Premium calm-tech SaaS landing template — bilingual (CN/EN) literary voice over a dark forest-night palette with warm gold accent, Cormorant + Noto Serif SC, Three.js procedural forest hero, station-based scrolling narrative, custom cursor. Built for ambient-AI / creative-tool / philosophical SaaS, not loud commercial launch.

AiCurv/ADBCommander

Pro-camera HUD mockup template — full-viewport black canvas wrapping a real video with monospace overlays (corner brackets, top status bar, side AF/exposure columns, bottom timecode + aperture/shutter/ISO row, vertical 8-filter wheel, animated reticle). For cinematographer portfolios, camera-app demos, LUT pack previews, filter-look auditions. NOT a TikTok/Reels mockup, NOT a storyboard, NOT a shot list, NOT a script document. The chrome wraps real footage — never a div placeholder.

AiCurv/ADBCommander

Premium pre-launch waitlist page template — dark charcoal canvas with subtle vignette, drifting portrait video-thumbnail cards, fade-up cascades, glass nav, live-updating join counter, single email form with success/error states. Built for creative-tool / AI / niche-SaaS invite-only launches with hushed exclusive tone, not loud growth-marketing.

AiCurv/ADBCommander

Route design-related HTML artifact tasks to the right artifact skill, reference, design system generation, or export skill.

AiCurv/ADBCommander

Implement text-to-speech (TTS) capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to convert text into natural-sounding speech, create audio content, build voice-enabled applications, or generate spoken audio files. Supports multiple voices, adjustable speed, and various audio formats.

AiCurv/ADBCommander

Implement specialized video understanding capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to analyze video content, understand motion and temporal sequences, extract information from video frames, describe video scenes, or perform video-based AI analysis. Optimized for MP4, AVI, MOV, and other common video formats.

相关技能