Communitygithub.com

AcTR-app / 動画生成スキル

z-ai-web-dev-sdk を利用してAIによる動画生成機能を実装します。テキストや画像から動画を生成する際に使用します。非同期タスク管理、ステータスポーリング、結果取得をサポートします。

動画生成スキル とは?

このスキルは、z-ai-web-dev-sdk パッケージを使用した動画生成機能の実装をガイドします。テキストプロンプトや画像から動画を生成するための非同期タスク処理を提供し、解像度、フレームレート、品質などのパラメータをカスタマイズできます。APIは非同期タスクモデルに基づいており、タスクを作成し、結果をポーリングして取得します。CLIとSDKの両方をサポートし、CLIは簡単なテストや自動化に、SDKはバッチ生成や複雑なワークフローに適しています。画像データはBase64エンコードが推奨され、MIMEタイプの一致が重要です。主にバックエンドコードで使用し、クライアントサイドでは使用しません。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Cetc2211/AcTR-app/tree/HEAD/skills/video-generation

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

動画生成スキル

このスキルは、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 "ボールで遊ぶ猫" --poll

# 短いオプションを使用
z-ai video -p "山々の美しい風景" --poll

カスタム品質と設定

# 品質モード(speed または quality)
z-ai video -p "夕日の海の波" --quality quality --poll

# カスタム解像度とFPS
z-ai video \
  -p "都市のタイムラプス" \
  --size "1920x1080" \
  --fps 60 \
  --poll

# カスタム再生時間(5秒または10秒)
z-ai video -p "花火のショー" --duration 10 --poll

画像から動画への生成

重要: image_url パラメータには、URLではなくBase64エンコードされた画像データを使用することを強く推奨します。この方法はより信頼性が高く、ネットワークの問題やアクセス制限を回避できます。

注記: データURIのMIMEタイプを実際の画像形式(image/jpeg、image/png、image/webpなど)に合わせて、デコードの問題を避けてください。

# 単一画像から動画を生成(Base64使用、推奨)
# 正しいMIMEタイプで画像をBase64に変換

# 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

開始・終了フレームモード

重要: 最良の信頼性を得るには、URLではなくBase64エンコードされた画像を使用してください。MIMEタイプが実際の画像形式と一致していることを確認してください。

# 2つのフレーム間で動画を生成(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 <テキスト>: オプション - 動画のテキスト説明
  • --image-url, -i <データ>: オプション - できればBase64エンコードされた画像データ(例: "data:image/png;base64,iVBORw...")。URLもサポートされていますが、推奨されません。2つの画像の場合はカンマ区切りで指定。
  • --quality, -q <モード>: オプション - 出力モード: speed または quality(デフォルト: speed)
  • --with-audio: オプション - AIオーディオエフェクトを生成(デフォルト: false)
  • --size, -s <解像度>: オプション - 動画解像度(例: "1920x1080")
  • --fps <レート>: オプション - フレームレート: 30 または 60(デフォルト: 30)
  • --duration, -d <秒>: オプション - 再生時間: 5秒または10秒(デフォルト: 5)
  • --model, -m <モデル>: オプション - 使用するモデル名
  • --poll: オプション - タスク完了まで自動ポーリング
  • --poll-interval <秒>: オプション - ポーリング間隔(デフォルト: 5)
  • --max-polls <回数>: オプション - 最大ポーリング試行回数(デフォルト: 60)
  • --output, -o <パス>: オプション - 出力ファイルパス(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アプリケーションとの統合
  • カスタムタスクキューの管理
  • 複雑なワークフローを伴う本番アプリケーション

動画生成ワークフロー

動画生成は2段階の非同期パターンに従います:

  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('ボールで遊ぶ猫。');
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で動作
  'これを生き生きとさせる'
);

開始フレームと終了フレームを使用した画像から動画への生成

重要: キーフレームモードでは、一貫性と信頼性のある動画生成のために、URLよりもBase64エンコードされた画像を強く推奨します。各画像に正しい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

[注: オリジナルのSKILL.mdが途中で切れていますが、翻訳可能な部分は翻訳しました。完全な翻訳が必要な場合は、完全なSKILL.mdを提供してください。]

Individual skills in this repo

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

Cetc2211/AcTR-app

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.

Cetc2211/AcTR-app

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.

Cetc2211/AcTR-app

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.

Cetc2211/AcTR-app

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.

Cetc2211/AcTR-app

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

Cetc2211/AcTR-app

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.

Cetc2211/AcTR-app

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.

関連スキル