Communitygithub.com

ARYAN2302/liquid_researcher

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

liquid_researcher 是什么?

该技能专门用于利用 z-ai-web-dev-sdk 包实现视频生成功能,使 AI 模型能够通过异步任务处理从文本描述或图像创建视频。它支持多种视频生成模式,包括基本的文本到视频、图像到视频(支持单张和首尾帧模式),并可自定义分辨率、帧率、时长和质量设置。API 采用异步任务模型:首先创建任务并获取任务 ID,然后轮询任务状态直至完成并检索结果。该技能提供了详细的 CLI 用法示例,适用于快速测试和简单自动化,以及全面的 SDK 用法示例,适用于复杂的生产工作流程。强烈建议使用 base64 编码的图像数据而不是 URL,以提高可靠性和避免网络问题。此技能主要适用于 Claude Code 等 AI 代理平台的后端开发场景。

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

在你喜欢的 AI 中提问

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

文档

视频生成技能

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

受支持的分辨率

  • 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('任务 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()

创建一个新的视频生成任务。

选项:

参数类型必需描述
promptstring否(除非无图像)视频的文本描述
image_urlstring 或 array否(除非无提示)图像数据(URL 或 base64 字符串)。对于两张图像,传入字符串数组
qualitystring否输出模式:speed 或 quality(默认:speed)
with_audioboolean否生成 AI 音效(默认:false)
sizestring否分辨率(例如 "1920x1080")(默认:"1024x1024")
fpsnumber否帧率:30 或 60(默认:30)
durationnumber否时长:5 或 10 秒(默认:5)

响应:

字段类型描述
idstring用于轮询的任务 ID
task_statusstring初始状态("PROCESSING")
created_atnumber创建时间戳

zai.async.result.query()

查询现有任务的状态和结果。

参数:

参数类型描述
taskIdstring要查询的任务 ID

响应:

字段类型描述
task_statusstringQUERYING(查询中)、PROCESSING(处理中)、SUCCESS(成功)或 FAIL(失败)
video_resultarray视频 URL 对象数组(成功时)
video_urlstring直接视频 URL(成功时)
urlstring替代视频 URL(成功时)
videostring另一个替代视频 URL(成功时)
errorstring错误消息(失败时)

完整示例

查看 {技能位置}/scripts/video.ts 获取包含以下内容的完整工作示例:

  • 文本到视频生成
  • 使用 base64 编码的图像到视频生成
  • 带轮询的异步结果处理
  • 错误处理和输入验证

最佳实践

  1. 使用 base64 编码的图像:尽可能始终将图像编码为 base64 格式,以确保可靠性和性能
  2. 始终匹配 MIME 类型:在 base64 数据 URI 中使用正确的 MIME 类型,以防止解码错误
  3. 实现适当的轮询:使用指数退避或合理的轮询间隔,避免过载 API
  4. 处理所有状态:代码应优雅地处理成功、失败和处理中状态
  5. 验证输入:确保 prompt 和 image_url 参数的输入验证正确
  6. 检查文件限制:注意文件大小限制,并根据需要压缩大图像
  7. 监控配额:注意 API 使用限制和配额

限制

  • 视频时长:5 或 10 秒
  • 帧率:30 或 60 FPS
  • 分辨率:多种宽高比受支持(见受支持的分辨率部分)
  • 最大轮询尝试次数:建议 60 次(默认轮询间隔为 5 秒时为 5 分钟)
  • 图像格式:JPEG、PNG、GIF、WebP、BMP

Individual skills in this repo

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

ARYAN2302/liquid_researcher

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.

ARYAN2302/liquid_researcher

Chinese-market SaaS pricing page template — soft sky-blue glass-morphism, 4-tier card grid with one elevated "recommended" tier, monthly/annual toggle, FAQ accordion, ¥ pricing with Inter numerals, careful CJK linebreaking, ICP filing footer.

ARYAN2302/liquid_researcher

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.

ARYAN2302/liquid_researcher

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.

ARYAN2302/liquid_researcher

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.

ARYAN2302/liquid_researcher

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

ARYAN2302/liquid_researcher

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.

ARYAN2302/liquid_researcher

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.

相关技能