Communitygithub.com

ARYAN2302/liquid_researcher

使用 z-ai-web-dev-sdk 實現 AI 驅動的影片生成功能。當使用者需要從文字提示或圖片生成影片、以程式化方式建立影片內容,或建構能產生影片輸出的應用程式時,可使用此技能。支援非同步任務管理,包含狀態輪詢與結果擷取。

liquid_researcher 是什麼?

此技能基於 z-ai-web-dev-sdk 套件,提供全面的 AI 影片生成能力,讓開發者能從文字描述或圖片(包括起始與結束影格)建立影片內容。主要功能包含文字轉影片、圖片轉影片、雙影格關鍵幀模式,以及音效生成與自訂參數(如解析度、幀率、時長與品質模式)。SDK 採用非同步任務模型:使用者先提交生成請求並取得任務 ID,再透過輪詢機制監控進度直至完成,最後擷取影片 URL。支援 CLI 快速測試(例如:`z-ai video --poll` 自動輪詢)與 SDK 深度整合(適用於批次處理與生產環境)。技能強調使用 Base64 編碼圖片而非 URL 以確保可靠性,並提供完整的 JavaScript 範例與 MIME 類型偵測輔助函式。支援多種解析度(如 1920x1080、1024x1024)與幀率(30/60 FPS),且適用於 Claude Code、Cursor、Codex 等 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

此技能位於上述專案路徑。

參考腳本:測試用範例腳本位於 {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。這種方法更可靠,能避免潛在的網路問題或存取限制。

注意:請將資料 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 的時機:

  • 批次影片生成搭配自訂邏輯
  • 整合至網頁應用程式
  • 自訂任務佇列管理
  • 具有複雜工作流程的生產應用程式

影片生成工作流程

影片生成遵循兩步驟非同步模式:

  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('A cat is playing with a ball.');
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
  'Animate this scene with gentle motion'
);

const task2 = await generateVideoFromImage(
  './images/graphic.png',  // 支援 PNG
  'Add dynamic movement'
);

const task3 = await generateVideoFromImage(
  './images/animation.webp',  // 支援 WebP
  'Bring this to life'
);

包含起始與結束影格的圖片轉影片

重要:對於關鍵幀模式,強烈建議使用 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 結束影格
  'Smooth transition between these scenes'
);

const task2 = await generateVideoWithKeyframes(
  './frames/start.png',  // PNG 起始影格
  './frames/end.webp',   // WebP 結束影格 - 不同格式也能運作!
  'Morphing effect between images'
);

非同步結果管理

查詢任務狀態

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(task.id);
if (status.success) {
  console.log('影片 URL:', status.url);
}

輪詢任務直到完成

import ZAI from 'z-ai-web-dev-sdk';

async function pollUntilComplete(taskId, interval = 5000, maxPolls = 60) {
  const zai = await ZAI.create();
  
  for (let i = 0; i < maxPolls; i++) {
    const result = await zai.async.result.query(taskId);
    
    switch (result.task_status) {
      case 'SUCCESS':
        return result;
      case 'FAIL':
        throw new Error(`任務失敗:${JSON.stringify(result)}`);
      case 'PROCESSING':
        if (i < maxPolls - 1) {
          console.log(`輪詢 ${i + 1}/${maxPolls}...`);
          await new Promise(resolve => setTimeout(resolve, interval));
        }
        break;
      default:
        throw new Error(`未知的任務狀態:${result.task_status}`);
    }
  }
  
  throw new Error('輪詢已達最大次數,任務未完成');
}

// 使用方式
const result = await pollUntilComplete(task.id);
const videoUrl = result.video_result?.[0]?.url || result.video_url;
console.log('影片 URL:', videoUrl);

進階設定

影片品質與模式

const task = await zai.video.generations.create({
  prompt: 'Slow motion waterfall',
  quality: 'quality', // 優先追求品質
  with_audio: true,   // 啟用 AI 音效生成
  size: '1920x1080',  // 全高畫質解析度
  fps: 60,            // 60 FPS 流暢播放
  duration: 10        // 10 秒時長
});

使用不同解析度

// 行動裝置與社群媒體格式
const mobileTask = await zai.video.generations.create({
  prompt: 'Vertical video for TikTok',
  size: '720x1440'  // 縱向模式
});

// 正方形格式
const squareTask = await zai.video.generations.create({
  prompt: 'Square aspect ratio video',
  size: '1024x1024'  // 正方形
});

// 寬螢幕格式
const wideTask = await zai.video.generations.create({
  prompt: 'Cinematic landscape shot',
  size: '1920x1080',  // 16:9 寬螢幕
  fps: 60
});

錯誤處理與最佳實踐

常見錯誤

以下是使用影片生成時可能遇到的常見錯誤:

  • 無效的圖片格式:確保您的圖片格式受支援(JPEG、PNG、WebP、GIF、BMP)
  • MIME 類型不符:Base64 資料 URI 中的 MIME 類型必須與實際圖片格式相符
  • 圖片檔案過大:若圖片太大,請考慮先壓縮再編碼為 Base64
  • 任務逾時:較複雜的影片可能需要較長時間;必要時增加 maxPolls 或 pollInterval
  • 無效的提示:提示若過長或包含不支援的字元可能會導致失敗

建議

import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
import path from 'path';

async function safeGenerateVideo(config) {
  const zai = await ZAI.create();
  
  try {
    // 驗證設定
    if (config.duration && ![5, 10].includes(config.duration)) {
      throw new Error('Duration must be 5 or 10 seconds');
    }
    if (config.fps && ![30, 60].includes(config.fps)) {
      throw new Error('FPS must be 30 or 60');
    }
    
    // 若提供圖片路徑,自動處理 Base64
    if (config.imagePath && !config.image_url) {
      const imageBuffer = fs.readFileSync(config.imagePath);
      const mimeType = getMimeType(config.imagePath);
      config.image_url = `data:${mimeType};base64,${imageBuffer.toString('base64')}`;
    }
    
    // 建立任務與輪詢
    const task = await zai.video.generations.create({
      prompt: config.prompt,
      image_url: config.image_url,
      quality: config.quality || 'speed',
      with_audio: config.with_audio || false,
      size: config.size || '1920x1080',
      fps: config.fps || 30,
      duration: config.duration || 5
    });
    
    const result = await pollUntilComplete(task.id);
    return {
      success: true,
      url: result.video_result?.[0]?.url || result.video_url
    };
  } catch (error) {
    console.error('影片生成失敗:', error.message);
    return {
      success: false,
      error: error.message
    };
  }
}

// 使用安全包裝器
const result = await safeGenerateVideo({
  prompt: 'A serene beach at sunset',
  quality: 'quality',
  duration: 10,
  fps: 60,
  imagePath: './images/beach.jpg'  // 自動轉換為 Base64
});

完整範例

查看位於 {Skill Location}/scripts/video.ts 的範例腳本,內含完整的可運作範例,展示:

  • 基本文字轉影片
  • 圖片轉影片(使用 Base64 編碼)
  • 雙影格關鍵幀
  • 使用不同解析度的影片
  • 同步處理多個影片任務
# 從技能目錄執行範例腳本
cd {Skill Location}
npx tsx scripts/video.ts --prompt "Your video description here"

如需進一步協助,請參閱套件文件或聯絡支援團隊。

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.

相關技能